Skip to main content

Documentation Tools

The documentation is built using Docusaurus and is located in the documentation folder. The documentation is hosted on GitHub Pages and is no longer included in the Docker container image.

Folder Structure​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   ├── hi/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

Internationalization (i18n)​

The documentation uses Docusaurus's built-in i18n system with English as the default locale. Translated content lives in i18n/{locale}/docusaurus-plugin-content-docs/current/, mirroring the structure of the docs/ folder.

  • Source files: docs/**/*.md (English)
  • Translated files: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • UI translations: i18n/{locale}/docusaurus-theme-classic/*.json and other JSON files
  • Localised Screenshots: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, generated by pnpm take-screenhots in the basedir.

The pnpm write-translations command extracts UI strings (from Docusaurus theme and custom components) into JSON translation files. The pnpm translate script (from documentation/, delegates to the repo root) runs ai-i18n-tools to translate markdown, JSON, SVGs, and the landing HTML per ai-i18n-tools.config.json.

The docs homepage is src/landing/landing.html wrapped by src/pages/index.tsx. Edit the HTML file for copy; locale copies live under src/landing/i18n/ and are generated by pnpm i18n:translate:docs.

important

Only edit files in docs/, the landing source src/landing/landing.html, and the source JSON files in i18n/en-GB/. Translated markdown under i18n/{other-locales}/ and landing copies under src/landing/i18n/ are generated and should not be edited manually.

Supported Locales​

LocaleLanguageDirectory
en-GBEnglish (default)docs/ (source)
deGermani18n/de/docusaurus-plugin-content-docs/current/
esSpanishi18n/es/docusaurus-plugin-content-docs/current/
frFrenchi18n/fr/docusaurus-plugin-content-docs/current/
hiHindii18n/hi/docusaurus-plugin-content-docs/current/
pt-BRBrazilian Portuguesei18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansSimplified Chinesei18n/zh-Hans/docusaurus-plugin-content-docs/current/

Translate the Documentation​

The documentation uses an AI-powered translation system to translate both content (markdown files) and UI strings (from Docusaurus and custom components). The source content is in English (docs/), and translations are generated for German, French, Spanish, Brazilian Portuguese, Hindi, and Simplified Chinese.

How Translation Works​

  1. Docusaurus UI strings: pnpm write-translations extracts theme/custom strings into i18n/en/*.json.
  2. AI translation (OpenRouter; config in ai-i18n-tools.config.json at the repo root): from documentation/, pnpm translate runs the root i18n:translate script (UI strings, SVGs, Docusaurus markdown/JSON, and default notification templates) into documentation/i18n/, src/locales/, and src/locales/templates/ as configured.
  3. Build: pnpm build generates static HTML for all locales under documentation/build/.

Running Translation​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs + json)
pnpm translate:docs
pnpm translate:json
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

CLI flags are defined by ai-i18n-tools; run pnpm exec ai-i18n-tools --help from the repo root or see Translation Workflow.

Manual Translation Overrides​

Edit documentation/glossary-user.csv (and optionally clear stale entries under .translation-cache/ at the repo root), then re-run the relevant pnpm translate:* command.

Common Commands​

All commands should be run from the documentation directory:

Development​

Start the development server with hot-reload for a specific locale:

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

The site will be available at http://localhost:3000/duplistatus/ (or the next available port). The /duplistatus/ path matches the GitHub Pages baseUrl and the in-app Help button links.

Build​

Build the documentation site for production:

cd documentation
pnpm build

This generates static HTML files in the documentation/build directory.

Serve Production Build​

Preview the production build locally:

cd documentation
pnpm serve

This serves the built site from the documentation/build directory.

Other Useful Commands​

  • pnpm clear - Clear Docusaurus cache
  • pnpm typecheck - Run TypeScript type checking
  • pnpm write-heading-ids - Write explicit {/* #id */} heading anchors into markdown using Docusaurus MDX comment syntax (run from documentation/ for stable links across translations). The CLI skips h1 titles, which Docusaurus uses as sidebar labels.

Generating README.md​

The project's README.md file is automatically generated from documentation/docs/intro.md to keep the GitHub repository README synchronised with the Docusaurus documentation.

To generate or update the README.md file:

./scripts/generate-readme-from-intro.sh

This script:

  • Extracts the current version from package.json and adds a version badge
  • Copies content from documentation/docs/intro.md
  • Converts Docusaurus admonitions (note, tip, warning, etc.) to GitHub-style alerts
  • Converts all relative Docusaurus links to absolute GitHub docs URLs (https://wsj-br.github.io/duplistatus/...)
  • Converts image paths from /img/ to documentation/static/img/ for GitHub compatibility
  • Removes the migration IMPORTANT block and adds a Migration Information section with a link to the Docusaurus docs
  • Generates a table of contents using doctoc
  • Generates README_dockerhub.md with Docker Hub-compatible formatting (converts images and links to absolute URLs, converts GitHub alerts to emoji-based format)
  • Generates GitHub release notes (RELEASE_NOTES_github_VERSION.md) from documentation/docs/release-notes/VERSION.md (converts links and images to absolute URLs)

Update README for Docker Hub​

The generate-readme-from-intro.sh script automatically generates README_dockerhub.md with Docker Hub-compatible formatting. It:

  • Copies README.md to README_dockerhub.md
  • Converts relative image paths to absolute GitHub raw URLs
  • Converts relative document links to absolute GitHub blob URLs
  • Converts GitHub-style alerts ([!NOTE], [!WARNING], etc.) to emoji-based format for better Docker Hub compatibility
  • Ensures all images and links work correctly on Docker Hub

Generate GitHub Release Notes​

The generate-readme-from-intro.sh script automatically generates GitHub release notes when run. It:

  • Reads the release notes from documentation/docs/release-notes/VERSION.md (where VERSION is extracted from package.json)
  • Changes the title from "# Version xxxx" to "# Release Notes - Version xxxxx"
  • Converts relative markdown links to absolute GitHub docs URLs (https://wsj-br.github.io/duplistatus/...)
  • Converts image paths to GitHub raw URLs (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) for proper display in release descriptions
  • Handles relative paths with ../ prefix
  • Preserves absolute URLs (http:// and https://) unchanged
  • Creates RELEASE_NOTES_github_VERSION.md in the project root

Example:

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

The generated release notes file can be copied and pasted directly into the GitHub release description. All links and images will work correctly in the GitHub release context.

Take screenshots for documentation​

pnpm take-screenshots

Or run directly: pnpm take-screenshots (use --env-file=.env if needed for environment variables).

This script automatically takes screenshots of the application for documentation purposes. It:

  • After env and health checks, runs pnpm exec playwright install so Playwright browsers are present
  • Launches a headless browser (Playwright Chromium)
  • Logs in as admin and regular user
  • Navigates through various pages (dashboard, server details, settings, etc.)
  • Takes screenshots at different viewport sizes
  • Saves screenshots to documentation/static/assets/ (English) or documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (other locales)

Requirements:

  • The development server must be running on http://localhost:8666
  • Environment variables must be set, add these to your .env file or export them:
    • ADMIN_PASSWORD: Password for admin account
    • USER_PASSWORD: Password for regular user account

Options: --locale limits screenshots to one or more locales (comma-separated). If omitted, all locales are captured. Valid locales: en-GB, de, fr, es, pt-BR, hi, zh-Hans. Use -h or --help to print usage.

Example:

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,de,pt-BR

Deploying the Documentation​

To deploy the documentation to GitHub Pages, you will need to generate a GitHub Personal Access Token. Go to GitHub Personal Access Tokens and create a new token with the repo scope.

When you have the token, store it in the Git credential store (e.g. using git config credential.helper store or your system's credential manager).

Then, to deploy the documentation to GitHub Pages, run the following command from the documentation directory:

pnpm run deploy

This will build the documentation and push it to the gh-pages branch of the repository, and the documentation will be available at https://wsj-br.github.io/duplistatus/.

Working with Documentation​

For the complete translation workflow (glossary management, AI translation, cache management), see Translation Workflow.

Source Files​

  • Documentation content: English markdown files in documentation/docs/
  • UI translations: English JSON files in documentation/i18n/en/ (auto-generated by pnpm write-translations)
  • Sidebar navigation: documentation/sidebars.ts
  • Docusaurus configuration: documentation/docusaurus.config.ts
  • Custom React components: documentation/src/components/
  • Static assets: documentation/static/
  • Main homepage: documentation/docs/intro.md (source for generating README.md)

Adding New Components​

  1. Create your React component in documentation/src/components/
  2. Export it from documentation/src/theme/MDXComponents.js to make it available in MDX
  3. If the component includes translatable UI strings, run pnpm write-translations to extract them
  4. Run pnpm translate to translate the new strings to all locales

Adding New Documentation Pages​

  1. Create a new .md file in documentation/docs/ (or a subdirectory)
  2. Add it to the sidebar in documentation/sidebars.ts
  3. Run pnpm write-translations to update the translation files structure
  4. Run pnpm write-heading-ids to generate heading IDs (anchors)
  5. Run pnpm translate to translate the new page to all locales
  6. Build and test: pnpm build

Static Assets​

  • Images: Place in documentation/static/img/ and reference with /img/filename.png in markdown
  • Downloads/PDFs: Place in documentation/static/ and reference with /filename.pdf
  • Per-locale assets: If an asset needs to be locale-specific (e.g., screenshots), place it in documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/

Build & Test​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

Always test your changes in at least the default English locale and one other locale to ensure translations appear correctly.