app.config.ts

app/app.config.ts owns public identity, navigation, optional UI, analytics, and landing-page copy. Nuxt merges consumer values over the layer defaults, so set only fields you intend to change.

export default defineAppConfig({
  ginkoDocs: {
    site: {
      name: { en: "Example Docs", de: "Example-Dokumentation" },
      description: {
        en: "Documentation for Example.",
        de: "Dokumentation für Example.",
      },
      url: "https://docs.example.com",
      logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
    },
  },
});

Localized values use { en: string, de?: string }. When de is absent, the layer falls back to en.

Theme palettes

Neutral palettes are slate, gray, zinc, neutral, stone, taupe, mauve, mist, and olive. Primary palettes are neutral, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, and rose. Both fields also accept custom for a consumer-defined palette.

export default defineAppConfig({
  ginkoDocs: {
    theme: {
      neutral: "stone",
      primary: "blue",
    },
  },
});

primary: 'neutral' follows the selected neutral ramp and keeps the default monochrome appearance. See Theme and override the layer for custom-palette variables and direct token overrides.

Prose appearance

An authored component appearance prop overrides its family value; the family value overrides prose.appearance. Families are callout, aside, excerpt, cards, readMore, accordion, tabs, code, files, api, figure, quiz, steps, and timeline.

Site

Use a production site.url; local defaults would produce incorrect canonical and agent links after deployment.

Main navigation

'auto' adds Documentation and adds Blog only when blog routes exist. An array replaces the generated links completely.

nav.socialIcons renders the configured social links as icon buttons in the header bar, and switches the mobile menu from labelled pills to the same icons. It stays off by default so upgrading never adds links to an existing header.

export default defineAppConfig({
  ginkoDocs: {
    nav: {
      links: [
        {
          label: { en: "Guides", de: "Anleitungen" },
          to: { en: "/docs", de: "/de/dokumentation" },
          icon: "lucide:book-open",
          description: {
            en: "Learn to use Example.",
            de: "Example kennenlernen.",
          },
        },
      ],
    },
  },
});

A link requires localized label and to; icon and localized description are optional. URLs beginning with http:// or https:// are treated as external.

Announcement banner

Change banner.id when an updated announcement should reappear after a reader dismissed an earlier one.

Analytics and social links

Analytics is disabled until a Plausible site script ID is set.

Social entries render in the order they are configured, so listing Discord first puts it first in the header. A plain URL uses the platform's built-in label and icon; an object overrides either:

export default defineAppConfig({
  ginkoDocs: {
    nav: { socialIcons: true },
    social: {
      discord: { href: "https://discord.gg/example", icon: "brand:discord" },
      github: "https://github.com/example/repo",
    },
  },
});

icon accepts any Iconify name the application has registered. The layer bundles a closed icon set with no API fallback, so a site that wants true brand marks registers them through Nuxt Icon's customCollections and names them here. Lucide has no Discord mark; the built-in default is a generic chat icon.

Copy scriptId from the site-specific script URL in Plausible. For https://plausible.io/js/pa-ExampleSiteScriptId.js, use only ExampleSiteScriptId. The ID is public and safe to commit. Do not put it in an environment variable or secret.

Plausible owns enhanced measurements such as outbound links, file downloads, and 404 pages. Configure them in the Plausible Site Installation settings. Ginko Docs loads no analytics script when scriptId is unset.

Page features

The feedback control appears only when feedback.enabled is true and a Plausible script ID is set. Feedback events use the name docs-feedback with path, helpful, and locale properties. Add the matching custom-event goal and properties in Plausible. A negative answer can link to a prefilled issue when repository is set.

The Markdown action fields affect only the menu. Agent routes, Markdown negotiation, link headers, and MCP registration are controlled by Nuxt module configuration and the deployment target.

Repository links

repository is unset by default.

The URL must be the repository base URL. Ginko Docs derives edit links and new-issue links from it.

Landing page

The layer provides localized title, description, and primary action copy. Its initial landing configuration is:

The full landing shape is:

Hero media is a union discriminated by type; each tab of the panel below documents one accepted form: