Troubleshooting

A page does not show up#

Check these first:

• The page slug is listed in docs.json
• The file exists under content/docs
• The slug matches the file path — for example "installation" maps to content/docs/installation.mdx, and "components/tabs" maps to content/docs/components/tabs.mdx

The sidebar is wrong or empty#

Usually this means a navigation typo. Check that navigation exists in docs.json, each tab/group has valid pages, there are no duplicate page slugs, and the page or an ancestor group is not marked hidden.

Build fails after editing docs.json#

The build validates docs.json against the schema bundled with your installed shiso version first, so read the error — it names the offending key and suggests a fix for likely typos. Common causes: a missing page file referenced in pages, duplicate slug entries, invalid object structure in navigation, or a malformed value under a supported key.

A redirect is not working#

Sources are matched exactly against the full route, including the docs prefix. Wildcard patterns are not supported; use an exact source for each redirect. Pages take precedence when a redirect source matches an existing page.

An icon does not render#

Icon names must exist in the lucide icon set. Names are collected from content and docs.json at build time; a typo'd name logs a warning in dev and renders nothing.

"Last updated" dates are missing or wrong#

Timestamps come from git history at build time. A file that has never been committed falls back to its filesystem date. CI checkouts need full history for accurate dates — use a full-depth checkout with shallow-cloning CI systems.

"On this page" links are missing#

This section appears only when the page has headings. Add ## and ### headings to populate it.

Page title is not what I expect#

Title priority: frontmatter title, then the page label in docs.json (label wins over title). If neither is set, the label is derived from the file name.

Back to Configuration overview.