Troubleshooting

Start with the public surface that failed, then trace it to its owner: content.config.ts owns collections and routes, app/app.config.ts owns presentation, and the deployment owns request-time capabilities.

A documentation page returns 404

Check the content mode first.

Then confirm that:

1. the file matches the generated docs collection source;
2. frontmatter contains the required string fields title and description;
3. the document is not a partial or a production draft;
4. locales is exactly ["en"] or ["en", "de"] and agrees with Nuxt I18n;
5. the requested route starts with /docs in English or /de/dokumentation in German.

The bare docs root redirects to the first navigable page. It cannot redirect when the collection is empty or every page is hidden from navigation.

Content validation stops the build

The generated collections use strict: true. Read the reported collection, file, field path, and Zod issue together. Fix the source value instead of normalizing it in a page component.

Common failures include:

• a missing docs description;
• a blog post without date, readingTime, or author;
• an author reference that does not resolve to an authors record;
• a numeric YAML date where the schema expects a string;
• a dotted key such as navigation.title instead of a nested navigation object.

A sidebar section or group is missing

Put structural metadata in the directory's .navigation.yml:

title: Reference
icon: lucide:braces
sidebar: section

Use sidebar: group for a labeled group inside the active section. Page-level navigation metadata belongs under a nested navigation key:

navigation:
  title: Configuration
  icon: lucide:settings
  badge: New

Do not write navigation.title: Configuration. Ginko reads that as a literal dotted key, not as nested navigation metadata.

The blog route is missing

Set blog: true in defineGinkoDocsConfig(). This creates the blog and authors collections and keeps the layer's blog routes enabled.

For each post, verify the required title, description, date, readingTime, and author fields. The authored reference uses the record path without an extension:

author: authors/ginko-docs-team

The reference must resolve to an author record. In the usual localized tree, that record lives at the corresponding locale path, for example content/en/authors/ginko-docs-team.json.

Search or navigation is empty

Both features read the canonical docs and optional blog collections. Confirm that the pages appear through their public routes before changing UI code.

• Navigation omits partials and documents hidden from navigation.
• Production output omits drafts.
• Search is locale-aware; test the active locale.
• A static deployment must include all generated application assets.
• An external provider must advertise and implement the operation it is asked to perform.

Canonical or alternate URLs are wrong

Set the same production origin in defineGinkoDocsConfig().site.url and ginkoDocs.site.url. Align Nuxt Site configuration and Nuxt I18n's baseUrl when present. Clear generated output after changing route or locale configuration, then rebuild.

Raw Markdown or LLM catalogs are missing

The factory enables agent Markdown for docs and blog pages. Confirm that the layer has not been overridden with content.agent: false or content.agent.routes: false.

For a static deployment, inspect the generated files directly:

find .output/public/raw -type f -name '*.md'

Also check .output/public/llms.txt and .output/public/llms-full.txt. Static generation does not create same-URL index.md files; clients must use the explicit /raw/**.md paths.

Markdown negotiation or MCP works locally but not after deployment

This is expected on a plain static host. Accept: text/markdown, response link headers, and /mcp are request-time Nitro features. Deploy a Nitro target when those features are requirements, or expose the generated raw and LLM files on the static host.

Analytics and feedback do nothing

Plausible is fully disabled until ginkoDocs.analytics.plausible.scriptId is set. Copy only the ID between pa- and .js from the site-specific script URL. The feedback control remains hidden until analytics and feedback.enabled are both active. A negative response offers a GitHub issue link only when ginkoDocs.repository is configured.

Installed behavior looks stale

Confirm the versions resolved by the consuming application:

pnpm why @lupinum/ginko-docs
pnpm why @lupinum/ginko-content

Remove stale generated directories, reinstall from the intended registry version, and run Nuxt preparation again. Do not keep two copies of either package in the dependency graph.

When reporting a reproducible defect, include the resolved Ginko Docs, Ginko Content, Nuxt, Vue, Vue Router, and Node versions; the deployment target; the smallest content tree; both configuration files; the failing URL; and complete build or server output.