Skip to main content

Troubleshooting

"Your Docusaurus site did not load properly"​

vdoc renders its chrome around this message, and it names the path it wanted.

The site was built for a different baseUrl than the one it is served from, almost always for the readable URL instead of the framed /static/projects/... one. Let createConfig() derive baseUrl, and check that the version the site was built with matches the one it was uploaded under. See Deployment.

Assets 404, or MIME type ("text/html") mismatch​

Same cause, seen from the browser: the request resolved against the wrong root, the server answered with an HTML 404 page, and the browser refused it as CSS. A site cannot be re-served from a path other than the one it was built for. Rebuild.

Error: Docusaurus found broken links!

Intentional, as described in Strict builds. Read the list it prints; it names the source file and the target.

Usual causes: a renamed file whose links were not updated, a heading whose anchor changed, or a link written as a route (/configuration) where a file path (03-configuration.md) was meant.

An admonition title shows up as body text​

:::warning Pay Attention

The MDX v1 shims are off, so the legacy title syntax is gone. Use brackets:

:::warning[Pay Attention]

An HTML comment is visible on the page​

Same cause. <!-- comment --> is not a comment in MDX:

{/* comment */}

A Mermaid diagram is empty in the built HTML​

Expected. Mermaid renders in the browser, so the static markup is empty until the page hydrates. Check it in a browser rather than in the HTML file.

If it is empty in the browser too, the language tag is probably not exactly mermaid.

The wheel scrolls the page instead of zooming a diagram​

Deliberate. Hold Ctrl or Cmd to zoom, so that scrolling past a diagram cannot get caught in it. See Diagrams.

Ctrl and + zooms the page, not the diagram​

A diagram claims those keys only while it has focus, because they are the browser's zoom shortcuts everywhere else. Tab to the diagram, or open it full screen.

Search returns nothing, or every result 404s​

Every result 404ing means docsRouteBasePath no longer matches your docs plugin. The theme derives it, so this only happens if you overrode it. Remove the override.

Nothing at all usually means the index was not built. Test search against a npm run build, not npm start.

The navbar shows no version​

version was not passed, so it defaulted to dev. See Deployment.

My styles are ignored​

If you loaded them through the classic preset's theme.customCss, they land before the theme. Pass them as customCss to createConfig() instead. See Customizing.

FATAL ERROR: Reached heap limit​

On a large site, raise the limit:

NODE_OPTIONS=--max-old-space-size=8192 npm run build

If you are changing the theme itself, it is more likely the @theme-original recursion. See Developing this repository.