shiso
Configuration

Troubleshooting

Fixes for the most common configuration and rendering problems.

Use this page when something in your docs is not building or rendering as expected.

A page does not show up#

Check these first:

  1. The page slug is listed in docs.json.
  2. The file exists under content/docs.
  3. The slug matches the file path.

Examples:

  • "installation" -> content/docs/installation.mdx
  • "components/tabs" -> content/docs/components/tabs.mdx

The sidebar is wrong or empty#

Usually this means a navigation typo.

Check:

  1. navigation exists in docs.json.
  2. Each tab/group has valid pages.
  3. No duplicate page slugs.
  4. 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:

  • Missing page file referenced in pages
  • Duplicate slug entries
  • Invalid object structure in navigation
  • A malformed value under a supported key (e.g. a navbar link without href)

Run pnpm check:config before building to validate both configuration and content. In addition to the schema, it checks page files, route collisions, internal links and heading anchors, local assets, redirect destinations, and orphaned content. Markdown and MDX diagnostics include the source line.

A redirect is not working#

  • Sources are matched exactly against the full route, including the docs prefix: /docs/old-page, not old-page.
  • Wildcard patterns such as /old/:slug* 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 history for accurate dates — use fetch-depth: 0 with shallow-cloning CI systems.

"On this page" links are missing#

This section appears only when the page has headings.

Add headings like:

Page title is not what I expect#

Title priority is:

  1. frontmatter title
  2. page label in docs.json (label wins over title)

If neither is set, the label is derived from the file name.

Last updated on
Edit this page