Skip to main content

Troubleshooting

Use this page when the docs change looks right in the diff but wrong in the running site.

Imported page did not update​

Check:

  • the source path in scripts/doc-metadata.mjs
  • the target path under docs/<project>/...
  • whether you ran make sync

If the source file moved, fix the import manifest first. Re-running sync without fixing the manifest will not help.

Page exists but is missing from the sidebar​

Check:

  • sidebars.ts for the main product docs
  • _category_.json files for folder labels
  • the page slug and file path

Remember that a page can build successfully and still be invisible if the sidebar entry never got wired.

Search does not find the page​

Check:

  • whether the page title and body contain the phrase you are searching for
  • whether the page is marked unlisted
  • whether you rebuilt the site after the content change

Local search is generated from the built content. If the search result looks stale, rebuild first.

Check:

  • src/data/projects.ts for project-level repo links
  • scripts/doc-metadata.mjs if imported markdown needs link rewriting

If the page text contains hard-coded old URLs, update the page content too.

The page renders in dev but breaks in build​

Run:

make build

Common causes:

  • broken markdown links
  • malformed front matter
  • invalid MDX or Mermaid syntax
  • references to files that only existed in a local draft

The docs look correct but still feel hard to use​

That is usually an information-architecture issue, not a rendering issue. Re-check:

  • the starting page for newcomers
  • whether the page belongs in start-here, build, reference, or examples
  • whether the sidebar labels are too vague
  • whether the important repo docs are linked early enough

Next steps​