Troubleshooting

Start with these commands:

pnpm check
pnpm build

check reports content schema, MDX, Astro, and TypeScript errors. build also exercises generated routes, icon loading, embeds, and the search index.

Every docs route returns 404

Confirm all three setup points:

• astro.config.ts includes dahlia() in integrations.
• src/content.config.ts exports a collection named docs using docsLoader() and docsSchema().
• Pages use the .mdx extension and live below the loader base, which defaults to src/content/docs.

Restart the dev server after changing astro.config.ts or src/content.config.ts.

A page exists but is missing from the sidebar

Dahlia does not add every page to navigation automatically. Add its content entry ID to docsNav, or include its directory with autogenerate.

{
  "label": "Guide",
  "items": [
    "index",
    { "autogenerate": { "directory": "guides" } }
  ]
}

Also confirm the page is not draft: true in production and does not use sidebar.hidden: true inside an autogenerated group.

A generated URL is not where expected

Check these values separately:

• docsLoader({ base }) changes where source files are read.
• docsBase changes the public route prefix.
• Locale directory maps a source directory to a locale route.
• Frontmatter slug overrides one page’s public path.

Navigation strings still use the content entry ID, not the public URL. Use configuration/project, not /docs/configuration/project/ or en/configuration/project.

An MDX component is undefined

Install the shared component package and import the component in that MDX file:

pnpm add @prosefly/astro-components

import { Callout } from '@prosefly/astro-components';

<Callout type="tip">Content</Callout>

See Components for exact imports and syntax.

The production build fails while loading icons

Iconify icons are resolved during development or build. An error mentioning api.iconify.design, fetch failed, or ENOTFOUND usually means the build environment has no network access.

Allow access to the configured Iconify API, use an internal compatible endpoint, or remove icons that cannot be resolved. Configure the endpoint and dynamically constructed icon names by registering @prosefly/astro-components/integration explicitly; see Integrations.

Local search works differently after deployment

Run a production build before testing search. With docsBase: '/', the root 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.

Open the expected index URL directly and confirm the host returns JSON with a 200 status.

A component override does not apply

Confirm that the config key exactly matches a supported override name and that the file path is relative to the project root. Changes to theme.config.json are watched during development; changes to astro.config.ts still require a dev-server restart.

A translated page shows default-language content

This is locale fallback. Add the matching file under the locale directory to replace it. A fallback page keeps the target locale URL while source and contributor metadata still refer to the default-language entry.

The problem remains

When opening an issue, include the Dahlia, Astro, and Node versions; the output from pnpm check and pnpm build; and the smallest relevant versions of astro.config.ts, src/content.config.ts, and theme.config.json.