About This Guide

This developer guide is built with Docusaurus and lives inside the monorepo at apps/upp-guide/. It is served as a static site through Nginx and Traefik in the Docker stack.

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)

Previewing Locally

Start the Docusaurus dev server inside nx-dev:

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

The dev server listens on port 4300 with hot reload. Open http://localhost:4300 in your browser. Changes to any .md file under docs/ are reflected immediately.

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. Preview. The dev server picks up the change automatically.

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/.env:

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

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

Building and Deploying

The build target produces a static site in dist/apps/upp-guide/:

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

This runs three steps in sequence:

1. Builds upp-test (demo app) with --base-href=/demos/.
2. Runs docusaurus build, outputting to dist/apps/upp-guide/.
3. Copies the built upp-test into dist/apps/upp-guide/demos/ so interactive widget demos work.

The upp-guide container (Nginx) serves dist/apps/upp-guide/ at https://how.{domain}/. After building, restart the container to pick up the new output:

docker compose restart guide

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.{domain}/	apps/upp-guide/docs/	Edit Markdown, rebuild with nx build upp-guide
Swagger (API)	https://doc.{domain}/swagger/	server/docs/swagger/openapi.yaml	Edit the OpenAPI spec directly
Doxygen (PHP)	https://doc.{domain}/codedoc/	PHP source docblocks	Regenerate with Doxygen
Coverage	https://doc.{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)).