How Ginko Docs works

Understand what the Nuxt layer provides and which parts remain under your application's control.

Ginko Docs combines a Nuxt application shell with Ginko Content's document model. You write content and site configuration; the layer turns that input into human-readable pages and machine-readable output.

Content flow

Markdown and data files
          │
          ▼
Ginko Content collections
  parse · validate · localize
          │
          ▼
Ginko Docs application layer
  routes · navigation · search · SEO
          │
          ├── rendered documentation pages
          └── Markdown, llms.txt and MCP surfaces

The layer supplies the application

Adding @lupinum/ginko-docs to extends supplies the standard docs and optional blog routes, layouts, header, footer, sidebar, search interface, prose styles, MDC components, localization, SEO integration, and agent routes.

You do not need a catch-all page or a second sidebar configuration. The layer reads the canonical docs collection and renders the generated navigation tree.

Your project supplies the product

The consuming project owns:

Markdown and data files under content/;
collection and locale choices in content.config.ts;
site identity and feature settings in app/app.config.ts;
public assets such as logos and editorial images;
optional Nuxt overrides for the landing page, layouts, and shell components.

Use Nuxt's normal layer override rules when the default presentation does not fit. A same-named file in the consuming app can replace a layer page or component without forking the package.

Two configuration files serve two runtimes

content.config.ts runs the content pipeline. defineGinkoDocsConfig() creates the docs collection, optional blog and author collections, locale-aware route mounts, sitemap entries, and agent metadata.

app/app.config.ts controls the rendered application. It contains localized brand text, logo paths, navigation presentation, the announcement banner, analytics, feedback, image behavior, and landing-page content.

Some site values, such as the name, description, and public URL, appear in both places because build-time content output and the rendered Nuxt app consume them independently. Import them from a small shared site.json file instead of repeating literals that can drift. JSON is portable across the Nuxt, app-config, and content-config loaders.

One content tree drives every reader surface

Numeric file order and folder metadata create the documentation tree. Ginko Docs uses that same tree for the sidebar, breadcrumbs, previous and next links, locale switching, search results, and route discovery.

This keeps authored Markdown as the source of truth. Changing a title, route, or order does not require updating a separate navigation array.

Use the public package boundaries

Consumer code should use only the documented exports:

@lupinum/ginko-docs for the Nuxt layer;
@lupinum/ginko-docs/content for defineGinkoDocsConfig();
@lupinum/ginko-docs/app-config for app-config types;
@lupinum/ginko-docs/components for the MDC tag map and related types.

Files behind layer aliases and internal route composables are implementation details. Override a Nuxt page or component when you need different behavior instead of importing an internal helper.