About This Guide

This developer guide is built with Docusaurus and lives inside the monorepo at apps/upp-guide/. It is part of the Docker development ecosystem — served as a static site by its own container in the stack defined by docker/nx/docker-compose.yml.

How It Is Served (Docker Stack)

The guide runs as a dedicated service in the Docker Compose stack:

Component	Role
documentation (container upp-docs)	Nginx serving static files from docs/upp-guide/
Traefik	Routes https://how.{domain}/ to the guide
Volume	The repo docs/ tree is mounted at /usr/share/nginx/html/docs; Nginx uses root …/docs/upp-guide for how.* so URLs are unchanged

When you run docker compose up -d, the guide is available at https://how.nx.{domain}/ (e.g. https://how.nx.unpispas4.mywire.org/). No separate local server is needed — the content is served by the same stack as the app, API, and other documentation.

Build and Update Flow

To build or update the guide:

cd docker
docker compose exec nx-dev bash -c "cd /app && npx nx build upp-guide"

This:

1. Builds upp-test (demos) with --base-href=/demos/
2. Runs Docusaurus build, outputting to docs/upp-guide/
3. Copies the built demos into docs/upp-guide/demos/

Because the container bind-mounts the parent docs/ directory (not only docs/upp-guide/), Docusaurus can recreate docs/upp-guide during the build without Docker holding a stale inode; the guide updates without restarting upp-docs.

Source Structure

apps/upp-guide/
├── docs/                   # Markdown pages (the actual content)
│   ├── intro.md            # Home page (slug: /)
│   ├── getting-started/
│   ├── core-concepts/
│   ├── libraries/
│   ├── guides/
│   ├── about-this-guide.md
│   └── resources.md
├── src/
│   ├── components/         # Custom React components usable from Markdown
│   └── css/custom.css      # Theme overrides
├── sidebars.ts             # Sidebar tree definition
├── docusaurus.config.ts    # Site configuration, navbar, footer, custom fields
└── project.json            # Nx targets (serve, build)

Adding a New Page

1. Create the Markdown file in the appropriate docs/ subfolder. Use the standard frontmatter:

---
sidebar_position: 3
---

# Page Title

Content goes here.

sidebar_position controls the order within its category.

2. Register it in the sidebar. Open sidebars.ts and add the document id (path relative to docs/, without .md) in the right place:

{
  type: 'category',
  label: 'Guides',
  items: [
    'guides/adding-a-feature',
    'guides/adding-a-widget',
    'guides/my-new-page',      // ← new page
  ],
},

3. Build and refresh. Run npx nx build upp-guide inside nx-dev and reload the guide in the browser.

Adding a New Category

To create a new top-level section (like "Getting Started" or "Guides"), add a category object in sidebars.ts:

{
  type: 'category',
  label: 'New Section',
  items: [
    'new-section/first-page',
    'new-section/second-page',
  ],
},

Then create the corresponding folder and files under docs/.

Using Custom Components

Docusaurus supports MDX, so you can import and use React components directly in Markdown. Custom components live in src/components/.

Example (from resources.md):

import ResourceLinks from '@site/src/components/ResourceLinks';

<ResourceLinks />

To create a new component, add a .tsx file in src/components/ and import it from any .md page using the @site/ alias.

Custom Fields

docusaurus.config.ts exposes runtime variables through customFields, populated from docker/nx/.env:

Field	Value	Purpose
domain	nx.{domain} (e.g. nx.unpispas4.mywire.org)	NX subdomain
swaggerUrl	https://doc.nx.{domain}/swagger/	Swagger UI
doxygenUrl	https://doc.nx.{domain}/codedoc/	PHP code documentation
coverageUrl	https://doc.nx.{domain}/coverage/	Test coverage reports
appUrl	https://app.nx.{domain}/	Main POS application
apiUrl	https://api.nx.{domain}/	Backend REST API

Components can read these via useDocusaurusContext().siteConfig.customFields.

Documentation Services Overview

The project maintains several documentation services, all served through Docker and Traefik:

Service	URL	Source	How to update
Developer Guide	https://how.nx.{domain}/	apps/upp-guide/docs/	Edit Markdown, rebuild with nx build upp-guide
Swagger (API)	https://doc.nx.{domain}/swagger/	server/docs/swagger/openapi.yaml	Edit the OpenAPI spec directly
Doxygen (PHP)	https://doc.nx.{domain}/codedoc/	PHP source docblocks	Regenerate with Doxygen
Coverage	https://doc.nx.{domain}/coverage/	Test output	Run tests with --coverage, then npm run coverage:to-docs

All four are accessible from the navbar links and from the Resources page.

Writing Guidelines

• Write in English (consistent with the codebase comment rules).
• Use standard Markdown with Docusaurus extensions (admonitions, tabs, MDX).
• Keep pages focused on one topic. Prefer multiple short pages over one long page.
• Include code examples wherever possible — runnable snippets are better than descriptions.
• For widget documentation, include an interactive demo from upp-test when available.
• Use relative links between pages (e.g. [Data Model](/core-concepts/data-model)).