So funktioniert Ginko Docs

Verstehe, was der Nuxt-Layer bereitstellt und welche Teile unter der Kontrolle deiner Anwendung bleiben.

Ginko Docs verbindet eine Nuxt-Anwendungsoberfläche mit dem Dokumentmodell von Ginko Content. Du schreibst Inhalte und konfigurierst die Website; der Layer erzeugt daraus Seiten für Menschen und maschinenlesbare Ausgaben.

Content-Ablauf

Markdown- und Datendateien
          │
          ▼
Ginko-Content-Collections
  parsen · validieren · lokalisieren
          │
          ▼
Ginko-Docs-Anwendungs-Layer
  Routen · Navigation · Suche · SEO
          │
          ├── gerenderte Dokumentationsseiten
          └── Markdown-, llms.txt- und MCP-Ausgaben

Der Layer liefert die Anwendung

Wenn du @lupinum/ginko-docs zu extends hinzufügst, erhältst du die Standardrouten für Dokumentation und den optionalen Blog, Layouts, Header, Footer, Sidebar, Suche, Prose-Stile, MDC-Komponenten, Lokalisierung, SEO-Integration und Agenten-Routen.

Du brauchst weder eine Catch-all-Seite noch eine zweite Sidebar-Konfiguration. Der Layer liest die kanonische Docs-Collection und rendert ihren generierten Navigationsbaum.

Dein Projekt liefert das Produkt

Das konsumierende Projekt besitzt:

Markdown- und Datendateien unter content/;
Collections und Sprachen in content.config.ts;
Website-Identität und Funktionsoptionen in app/app.config.ts;
öffentliche Assets wie Logos und redaktionelle Bilder;
optionale Nuxt-Overrides für Landingpage, Layouts und Oberflächenkomponenten.

Nutze die normalen Override-Regeln von Nuxt, wenn die Standarddarstellung nicht passt. Eine gleichnamige Datei in der konsumierenden Anwendung kann eine Seite oder Komponente des Layers ersetzen, ohne das Paket zu forken.

Zwei Konfigurationsdateien bedienen zwei Laufzeiten

content.config.ts steuert die Content-Pipeline. defineGinkoDocsConfig() erstellt die Docs-Collection, optionale Blog- und Autoren-Collections, sprachabhängige Routen, Sitemap-Einträge und Agenten-Metadaten.

app/app.config.ts steuert die gerenderte Anwendung. Die Datei enthält lokalisierte Markentexte, Logo-Pfade, die Navigationsdarstellung, das Ankündigungsbanner, Analytics, Feedback, Bildverhalten und Inhalte der Landingpage.

Einige Werte wie Name, Beschreibung und öffentliche URL stehen in beiden Dateien, weil generierte Content-Ausgaben und die gerenderte Nuxt-Anwendung sie unabhängig voneinander verwenden. Importiere sie aus einer kleinen gemeinsamen site.json-Datei, statt veränderliche Literale zu wiederholen. JSON funktioniert einheitlich mit den Loadern für Nuxt-, App- und Content-Konfiguration.

Ein Content-Baum versorgt alle Ausgaben

Numerische Dateireihenfolge und Ordnermetadaten erzeugen den Dokumentationsbaum. Ginko Docs verwendet denselben Baum für Sidebar, Breadcrumbs, Links zur vorherigen und nächsten Seite, Sprachwechsel, Suchergebnisse und Routenerkennung.

Damit bleiben die geschriebenen Markdown-Dateien die einzige Quelle der Wahrheit. Wenn du Titel, Route oder Reihenfolge änderst, musst du kein separates Navigationsarray anpassen.

Öffentliche Paketgrenzen verwenden

Konsumierender Code sollte nur die dokumentierten Exporte verwenden:

@lupinum/ginko-docs für den Nuxt-Layer;
@lupinum/ginko-docs/content für defineGinkoDocsConfig();
@lupinum/ginko-docs/app-config für App-Konfigurationstypen;
@lupinum/ginko-docs/components für die MDC-Tag-Zuordnung und zugehörige Typen.

Dateien hinter Layer-Aliasen und interne Routen-Composables sind Implementierungsdetails. Überschreibe eine Nuxt-Seite oder Komponente, wenn du anderes Verhalten brauchst, statt einen internen Helfer zu importieren.