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
│   └── pt-BR/         # Brazilian Portuguese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   └── pages/         # Additional pages (e.g., 404)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
├── package.json       # Dependencies and scripts
└── .intlayer/         # Intlayer generated UI translation files (auto-generated)

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 uses AI to translate both the markdown documentation and UI JSON files.

important

Only edit files in docs/ and the source JSON files in i18n/en/. The translated markdown files in i18n/{other-locales}/ are auto-generated and should not be edited manually.

Supported Locales​

LocaleLanguageDirectory
enEnglish (default)docs/ (source)
deGermani18n/de/docusaurus-plugin-content-docs/current/
esSpanishi18n/es/docusaurus-plugin-content-docs/current/
frFrenchi18n/fr/docusaurus-plugin-content-docs/current/
pt-BRBrazilian Portuguesei18n/pt-BR/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, and Brazilian Portuguese.

How Translation Works​

  1. UI strings extraction: pnpm write-translations extracts translatable strings from Docusaurus UI and custom components into JSON files in i18n/en/

  2. Content translation: pnpm translate uses OpenRouter AI to translate:

    • Markdown files from docs/ → i18n/{locale}/docusaurus-plugin-content-docs/current/
    • JSON UI strings from i18n/en/ → i18n/{locale}/
    • SVG files from static/img/duplistatus*.svg (translates text inside SVGs and exports to PNG via Inkscape)

  3. Build: pnpm build generates static HTML for all locales in build/ (one subdirectory per locale)

Running Translation​

cd documentation
pnpm translate                       # Translate everything to all locales
pnpm translate --force               # force the translation of all files
pnpm translate --locale fr           # Translate only to French
pnpm translate --no-svg              # Skip SVG translation
pnpm translate --path docs/intro.md  # Translate specific file
pnpm translate:status                # Show the status of translation of all files

For detailed options, cache management, troubleshooting, and the glossary system, see Translation Workflow.

Manual Translation Overrides​

If you need to manually adjust a translation:

  1. add the terms to glossary-user.csv
  2. delete the cache entries for these terms using the the web-based cache editing tool
  3. rerun the translation with pnpm translate --force

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 (or the next available port).

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 - Generate heading IDs in Docusaurus internal format (does not modify markdown files)
  • pnpm heading-ids - Add explicit anchor IDs {#id} to all markdown headings (modifies files; ensures consistent IDs across translations)

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:

  • Launches a headless browser (Puppeteer)
  • 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, de, fr, es, pt-BR. 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
# Multiple locales:
pnpm take-screenshots --locale en,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 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.