Project Manual
Contents

Troubleshooting

On this page

Build failures identify the source file and the invalid value whenever possible.

A page has no title#

Make # Page Title the first line of the file. Do not add frontmatter or blank lines before it.

Resolve links from the current source file. From a page directly inside a section, another section is one directory up:

[Commands](../03-reference/01-commands.md)

The deployed site has missing assets#

Rebuild with the path where the site is mounted:

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

Do not reuse a bundle at a different deployment prefix without rebuilding it.

The hosted site uses clean server URLs and loads its search index over HTTP. Do not open dist/en/index.html through file://.

Generate the offline ZIP instead:

make offline-bundle

Extract .build-simple-docs/manual-site-offline.zip, then open manual-site-offline/index.html to choose a language.

A language switch opens the contents page#

The target language does not have a page with the same section and page slugs. This is expected for the partial Polish example. To add a matching translation, keep those slugs unchanged and translate the title and body. Local source links must point to existing pages within the selected language.

A multilingual source is rejected#

Point --source at the parent containing languages.json and the declared language directories. Check that default names a declared language, each language has a name, and section labels refer to existing section slugs. See language configuration for the schema and supported message keys.

Mermaid appears as code#

This is the default. Add --mermaid to the builder command or MERMAID=1 to the Make helper to render a diagram. The fence label must be exactly mermaid. Its source remains searchable after rendering.

Mermaid colors do not match the theme#

With rendering enabled, the selected --theme or Make THEME supplies diagram colors automatically. A custom theme with an unsupported or incomplete palette falls back as a whole to neutral diagrams on a white panel. The builder reports this once on stderr per build; the palette fallback is not a build failure.

Check the diagram palette contract for the seven literal hex colors and light/dark color-scheme required in unconditional :root rules. Rebuild after changing the theme: runtime CSS changes cannot recolor already rendered SVGs. Do not add Mermaid frontmatter or configuration directives to override the palette.

Mermaid rendering fails#

Read the source path:line diagnostic; the line points to the opening fence. If mmdc is missing, use the optional Mermaid container or provide a working host renderer on PATH. Default builds and enabled builds without diagrams do not require it.

Font-aware rendering also needs Node.js 22.12 or newer (node on PATH) and access to the npm-installed Mermaid CLI and Puppeteer packages. If the helper reports a module-resolution error for a shell-wrapped mmdc, set Node's NODE_PATH to the installed package directory or use the optional container. A custom host browser can be selected through the SIMPLE_DOCS_PUPPETEER_CONFIG launch-options JSON file.

For invalid diagrams or rejected SVGs, simplify the source to the supported static subset. Remove Mermaid frontmatter, configuration directives, HTML labels, HTML-based math, and references to external resources. Rendering and SVG validation finish before previous outputs are replaced, so a failed diagram leaves those outputs intact.