Build Sites with Python

Use this workflow when Python 3.11 or newer is installed on the build machine. No third-party Python packages are required.

Build the bundled documentation#

From the Simple Docs repository, run:

python3 build.py

This uses the bundled manual/ directory and writes:

dist/
artifacts/manual-site.tar.gz

Build external documentation#

The external source can be in another public or private Git repository:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz

The --source value points to either a flat English tree of ordered section directories and optional images/, or a parent containing languages.json and language directories. Both use the same command. See language configuration.

The generator uses core assets and selectable themes shipped beside build.py. The external repository only needs to contain documentation source.

Select a theme#

Use the light paper theme instead of the default ef-maris-dark theme:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz \
  --theme paper

See create and select themes to add a theme.

Use relative command paths#

Explicit relative paths are resolved from the current working directory:

python3 /path/to/simple-docs/build.py \
  --source ../private-project/docs \
  --output ../private-project-build/site \
  --archive ../private-project-build/manual-site.tar.gz

Absolute paths are clearer for automated jobs and avoid depending on the current working directory.

Build for a URL prefix#

The default build expects the site at the domain root. Add --base-path when a static host publishes it below a project path:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz \
  --base-path /project-name/

The generated site must be mounted at the same /project-name/ path. Rebuild when the deployment prefix changes.

Build an offline ZIP#

Add an offline archive path when readers need to open the documentation without a web server:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz \
  --offline-archive /path/to/private-project-build/manual-site-offline.zip

Extract the ZIP and open manual-site-offline/index.html to choose a language. The offline pages use relative file links and embedded search data. External links work when internet access is available, but external images are rejected because they would make the documentation depend on the network.

Optional Mermaid Rendering#

Default builds display mermaid fences as escaped, searchable code and require no renderer. If npm-installed Mermaid CLI (mmdc) and Node.js 22.12 or newer (node) are on PATH, with a working Puppeteer browser, opt in with:

python3 build.py --mermaid \
  --offline-archive artifacts/manual-site-offline.zip

The Make equivalent is make offline-bundle MERMAID=1, which uses the host renderer and writes under .build-simple-docs/. Add --mermaid to the external source commands above in the same way.

A build-time helper loads the CLI package and its Puppeteer dependency from the mmdc installation, then preloads the bundled JetBrains Mono font before label layout. Every output SVG embeds the full Regular font at 14px and its OFL license; no font-processing dependencies are needed. The supported toolchain is Mermaid CLI 11.17.0 with Puppeteer 25.11.0, as locked in tools/mermaid/.

For shell-wrapper installations, Node's NODE_PATH can point to the directory containing the installed npm packages. To customize browser launch options, set SIMPLE_DOCS_PUPPETEER_CONFIG to a Puppeteer JSON configuration file. The optional container sets these paths automatically; its no-sandbox setting is not applied to host builds.

The existing --theme option also selects diagram colors automatically; for example, use python3 build.py --theme paper --mermaid. See Mermaid diagram colors for the custom-theme palette contract and neutral fallback.

The generator looks up mmdc on PATH only when it reaches a diagram in an enabled build. Missing renderers, invalid diagrams, and rejected SVGs report the source path and fence line before replacing previous outputs. Both hosted and offline output receive static SVGs; the diagram source remains searchable.

The recommended Mermaid container workflow supplies the optional toolchain without a host installation. See Mermaid authoring for examples, alt text, and the supported static subset.

Rebuild after changes#

Run the same command after changing Markdown. Ownership markers let the generator safely replace its previous site and archives.

An existing non-empty output directory or archive without a valid marker is left untouched. Choose a new empty output location instead of deleting an unrelated file.

The generator prepares the complete site and archives in temporary locations before replacing output. If publication fails, it attempts to restore the previous site, archives, and ownership markers. If restoration also fails, the error lists retained backup locations for manual recovery. Do not delete those backups until you have recovered the required files.

Markers must be regular files, not symlinks. Allow enough disk space for both old and new outputs while rebuilding. Publication is not a crash-safe transaction, and readers may briefly see missing paths during replacement. Do not run concurrent builds against the same output paths.

Return to the generating sites overview, compare the container workflow, use the Make helpers, or continue with serving generated sites. You can also create or select a theme.