Troubleshooting

What goes wrong, what it means, and what to do. Roughly in the order people hit it.

The build

json.decoder.JSONDecodeError: Expecting property name

A trailing comma, almost always. JSON does not allow the comma after the last item in a list or object, which is the one habit every other language teaches you. The message names the file, the line and the column. Delete the comma.

FileNotFoundError: build.py

There is no build.py. The package ships two scripts, build-core.py and build-site.py, both inside source/. Run them from that directory.

KeyError: 'something'

A section is missing a field that its type requires, or names a type that does not exist. Check the entry against the section catalogue; the seventeen valid type names are listed there.

python3: command not found on Windows

Windows installs it as python. Either use python build-core.py, or tick "Add Python to PATH" when installing from python.org.

The built site

A page is blank below the hero.

Its sections array is empty, or every section in it names a type that does not exist. An unknown app name renders an HTML comment rather than failing, so check the page source for <!-- app "..." not found -->.

The globe or molecule is a still image.

That is the fallback working. The visitor's browser has no usable WebGL context, which is common on locked-down corporate machines and virtualised desktops. See the WebGL contract in behaviour. To see it deliberately, disable hardware acceleration in your browser.

The figures all read zero.

They should not, and no longer do: the real number is in the HTML and the script zeroes it only when it is about to animate. If you see zeros in a build made from an older package, rebuild with the current build-site.py.

Nothing fades in.

Reveal animations are gated on an html.js class that the page sets when scripting runs. If the class is missing, everything renders in its final state, which is the intended behaviour with JavaScript off. If you have scripting on and still see no animation, check whether your operating system has "reduce motion" enabled, which collapses every transition deliberately.

Links work locally and 404 once deployed, or the reverse.

A clean-URL mismatch. Some hosts serve /page from page.html and some do not. See deploying for which hosts do what.

Dark mode looks wrong on one section.

A tone: "dark" band inside a page that is already dark. The tone is a full-width band colour, not a theme switch; two dark bands in a row read as one. Remove the tone from one of them.

The contact form does nothing.

Correct. It validates in the browser and shows its success state, but posts nowhere until you set data-endpoint on the form to your own handler. There is no backend in this package and there was never meant to be one.

Content

A new article does not appear in the news list.

Listing sections are content, not a directory scan. Adding a markdown file gives you a page at its own URL; to have it appear in a list, add an entry to articles.json as well. This is deliberate, so that a draft on disk is not published by existing.

A new product does not appear in the catalogue filters.

It will, as soon as it has a category. The filter pills are built from the distinct categories present in products.json, so a product without one is listed but unfilterable.

Changing a name in the HTML did not change it everywhere.

You edited the built output rather than the content. That is supported, but each built page is a separate file, so the edit reaches one page. Edit source/content/*.json and rebuild to change every page at once. See architecture for which route to take when.

Edits disappeared after a rebuild.

Same cause, opposite direction. A rebuild regenerates the built HTML from the content model, so edits made directly to built pages are overwritten. Pick one route and stay on it.

Deployment

The site works from a file path but not from a server, or the reverse.

Absolute paths beginning with / resolve to the server root, which is not the same as the folder when you open a file directly. The built HTML uses relative paths for exactly this reason; if you have rewritten some by hand, that is where to look.

Fonts do not load on the deployed site.

The assets/fonts/ folder was not uploaded, or the host is serving .woff2 with the wrong content type. Both fonts are bundled; nothing is fetched from a font service, so this is always a hosting question rather than a network one.

Search engines are not indexing it.

Check robots.txt and the robots block in content/seo.json. If you deployed a preview build, it is blocked from indexing on purpose.

Still stuck

[email protected]. Include the format you are using, the page, and what you were doing. If it is a build error, paste the whole message rather than the last line: the useful part is usually the file and line above it.