Configuration

The generator accepts a deployment URL prefix, a visual theme, and an optional language manifest in the source directory.

Root hosting#

The default build uses / as its base path:

python3 build.py

The generated root index.html redirects to the configured default language, which is /en/ for the bundled manual. Polish is available at /pl/ as a partial example. Language routes replace the former /manual/ route; no compatibility redirect is generated.

Project-path hosting#

Pass an origin-relative path that starts and ends with /:

python3 build.py --base-path /example-project/

The output must then be hosted at /example-project/, with English contents at /example-project/en/ and Polish contents at /example-project/pl/. See the command reference for a summary.

Theme selection#

The default ef-maris-dark theme matches the current dark desktop palette. Select the light paper theme with:

python3 build.py --theme paper

Theme selection also works with hosted prefixes and offline ZIPs. See create and select themes for the theme directory contract.

Languages#

Without a manifest, --source accepts a flat tree of numbered section directories and optional images/, and generates English output at /en/. For multiple languages, put languages.json beside the language directories:

manual/
├── languages.json
├── en/
│   ├── 01-getting-started/
│   │   ├── 01-introduction.md
│   │   └── 02-installation.md
│   └── images/
└── pl/
    └── 01-getting-started/
        ├── 01-introduction.md
        └── 02-installation.md

Keep --source manual pointing at the parent. The manifest declares the default language and every language directory:

{
  "default": "en",
  "languages": {
    "en": {"name": "English"},
    "pl": {
      "name": "Polski",
      "sections": {"getting-started": "Pierwsze kroki"},
      "messages": {
        "manual": "Podręcznik",
        "project_manual": "Podręcznik projektu",
        "search": "Szukaj"
      }
    }
  }
}

Language codes use two or three lowercase ASCII letters, optionally followed by hyphen-separated lowercase ASCII letters or digits in groups of two to eight, such as pt-br. Each declared language needs at least one section and page. The source parent contains only languages.json and the declared language directories. The default value must name one of those languages.

The name is the switcher label. Optional sections maps existing section slugs to translated display labels; omitted labels are derived from the slug. Keep section and page slugs stable across translations, while translating page titles, headings, and prose. Numeric prefixes control each language's reading order and are not part of translation matching.

The switcher opens a page with matching section and page slugs. If that page has not been translated, it opens the target language's contents instead. Open the current language name in the header to reveal the language links. This compact menu works without JavaScript and is hidden when only one language is configured. The offline root shows all language choices directly. Navigation and search contain only the selected language's pages. Source links stay within that language tree, and local images belong in its images/ directory. From a page inside a section, use ../ to reach another section or the image directory.

Optional messages overrides English UI defaults. Supported keys are manual, project_manual, description, skip, search, search_placeholder, search_results, contents, on_this_page, diagram_open, diagram_scroll_hint, previous, next, page_navigation, language, browse, no_results, results_count, loading, and unavailable. Values must be strings; unknown keys are rejected. Preserve {query} in no_results and both {query} and {count} in results_count. The bundled manual/languages.json contains the complete Polish UI translation; the short example above demonstrates that omitted messages fall back to English.

Hosted output has a contents page, search index, and local images under each language route, with shared styles, scripts, and themes under /assets/. For offline output, extract the ZIP and open manual-site-offline/index.html. That root page is a language chooser without an automatic redirect. Language links use relative file paths, and search data is embedded in each page.