Troubleshooting

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.

An internal link is broken#

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.

Opening hosted files directly loses styling or search#

The hosted site uses clean server URLs and loads its search index over HTTP. Do not open dist/manual/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.