Troubleshooting

Start with pnpm run check. It validates content collections, MDX imports, Astro components, and TypeScript before a production build.

A docs page does not appear in the sidebar

Confirm the page is in the docs collection, is not draft: true in production, and is matched by either a sidebar string item or an autogenerate.directory entry. In i18n projects, sidebar values are locale-neutral, so use configuration/project, not en/configuration/project.

A generated route is not the URL I expected

Check docsBase, locale directory, and frontmatter slug. slug changes the public URL, but sidebar ownership still follows the content entry ID.

The search index returns 404

Confirm docsBase and the active locale. With the default docsBase: '/', the root search index is /search.json. With docsBase: '/docs', it is /docs/search.json; localized indexes include the locale prefix, such as /docs/zh-cn/search.json.

Icons do not render

Use full Iconify names such as lucide:search or configure aliases where supported. If an icon name is built dynamically, add it to iconify.preload because static scanning cannot detect it.

A component override does not apply

Confirm the key matches a supported override slot exactly, the path is relative to the project root, and the dev server was restarted after editing src/theme.config.ts.

A translated page falls back to English

Add the matching file under the locale directory. Fallback pages keep the target locale route but use the default-locale source file for edit links and contributors.