Fehlerbehebung

Beginne bei der fehlerhaften öffentlichen Oberfläche und verfolge sie zu ihrem Besitzer: content.config.ts besitzt Collections und Routen, app/app.config.ts die Darstellung und das Deployment die Laufzeitfunktionen.

Eine Dokumentationsseite liefert 404

Prüfe zuerst den Content-Modus.

Prüfe anschließend:

1. Die Datei entspricht der generierten Quelle der Collection docs.
2. Das Frontmatter enthält die Pflichtfelder title und description als Strings.
3. Das Dokument ist weder Partial noch Produktionsentwurf.
4. locales ist exakt ["en"] oder ["en", "de"] und stimmt mit Nuxt I18n überein.
5. Die angefragte Route beginnt auf Englisch mit /docs oder auf Deutsch mit /de/dokumentation.

Die reine Docs-Root leitet zur ersten navigierbaren Seite weiter. Bei einer leeren Collection oder ausschließlich ausgeblendeten Seiten ist keine Weiterleitung möglich.

Content-Validierung stoppt den Build

Die generierten Collections verwenden strict: true. Lies die gemeldete Collection, Datei, den Feldpfad und das Zod-Problem zusammen. Korrigiere den Quellwert, statt ihn in einer Seitenkomponente zu normalisieren.

Häufige Ursachen:

• Eine Docs-Seite ohne description.
• Ein Blogbeitrag ohne date, readingTime oder author.
• Eine Autor-Referenz ohne passendes Dokument in authors.
• Ein numerisches YAML-Datum, obwohl das Schema einen String erwartet.
• Ein gepunkteter Schlüssel wie navigation.title statt eines verschachtelten navigation-Objekts.

Ein Sidebar-Bereich oder eine Gruppe fehlt

Strukturelle Metadaten gehören in .navigation.yml des Verzeichnisses:

title: Referenz
icon: lucide:braces
sidebar: section

Verwende sidebar: group für eine beschriftete Gruppe im aktiven Bereich. Navigationsmetadaten einer Seite gehören unter den verschachtelten Schlüssel navigation:

navigation:
  title: Konfiguration
  icon: lucide:settings
  badge: Neu

Schreibe nicht navigation.title: Konfiguration. Ginko liest dies als wörtlichen gepunkteten Schlüssel und nicht als verschachtelte Navigationsmetadaten.

Die Blogroute fehlt

Setze blog: true in defineGinkoDocsConfig(). Dadurch entstehen die Collections blog und authors, und die Blogrouten des Layers bleiben aktiv.

Prüfe bei jedem Beitrag die Pflichtfelder title, description, date, readingTime und author. Die Referenz verwendet den Datensatzpfad ohne Dateiendung:

author: authors/ginko-docs-team

Die Referenz muss zu einem Autor-Datensatz aufgelöst werden. Im üblichen lokalisierten Baum liegt er unter dem entsprechenden Sprachpfad, etwa content/de/authors/ginko-docs-team.json.

Suche oder Navigation ist leer

Beide Funktionen lesen die kanonischen Collections docs und optional blog. Prüfe, ob die Seiten über ihre öffentlichen Routen erreichbar sind, bevor du UI-Code änderst.

• Navigation lässt Partials und aus der Navigation ausgeblendete Dokumente aus.
• Produktionsausgabe lässt Entwürfe aus.
• Suche ist sprachabhängig; teste die aktive Sprache.
• Ein statisches Deployment muss alle generierten Anwendungs-Assets enthalten.
• Ein externer Provider muss die angeforderte Operation ankündigen und implementieren.

Canonical- oder Alternate-URLs sind falsch

Setze dieselbe Produktions-Origin in defineGinkoDocsConfig().site.url und ginkoDocs.site.url. Gleiche Nuxt Site und baseUrl von Nuxt I18n an, falls vorhanden. Lösche nach Änderungen an Routen oder Sprachen die generierte Ausgabe und baue neu.

Raw-Markdown oder LLM-Kataloge fehlen

Die Factory aktiviert Agent-Markdown für Docs- und Blogseiten. Prüfe, ob der Layer mit content.agent: false oder content.agent.routes: false überschrieben wurde.

Kontrolliere bei einem statischen Deployment die generierten Dateien direkt:

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

Prüfe außerdem .output/public/llms.txt und .output/public/llms-full.txt. Die statische Generierung erzeugt keine index.md-Dateien unter den normalen Seiten-URLs; Clients müssen die expliziten /raw/**.md-Pfade verwenden.

Markdown-Aushandlung oder MCP funktioniert lokal, aber nicht im Deployment

Auf einem rein statischen Host ist das erwartetes Verhalten. Accept: text/markdown, Response-Link-Header und /mcp sind Nitro-Funktionen zur Request-Zeit. Verwende ein Nitro-Ziel, wenn sie Anforderungen sind, oder stelle die generierten Raw- und LLM-Dateien statisch bereit.

Analytics und Feedback reagieren nicht

Plausible bleibt vollständig deaktiviert, bis ginkoDocs.analytics.plausible.scriptId gesetzt ist. Kopiere nur die ID zwischen pa- und .js aus der Site-spezifischen Skript-URL. Die Feedback-Abfrage bleibt verborgen, bis Analytics und feedback.enabled aktiv sind. Eine negative Antwort bietet nur dann einen GitHub-Issue-Link an, wenn ginkoDocs.repository konfiguriert ist.

Installiertes Verhalten wirkt veraltet

Prüfe die in der konsumierenden Anwendung aufgelösten Versionen:

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

Entferne veraltete generierte Verzeichnisse, installiere die beabsichtigte Registry-Version und führe Nuxt Prepare erneut aus. Vermeide doppelte Installationen beider Pakete im Abhängigkeitsgraphen.

Ein reproduzierbarer Fehlerbericht enthält die aufgelösten Versionen von Ginko Docs, Ginko Content, Nuxt, Vue, Vue Router und Node, das Deployment-Ziel, den kleinsten Content-Baum, beide Konfigurationsdateien, die fehlerhafte URL sowie die vollständige Build- oder Serverausgabe.