Skip to main content

Configure the site shell

Set site identity, navigation, banners, repository links, feedback, and reader controls in app.config.ts.

Put presentation settings under ginkoDocs in app/app.config.ts. The layer provides defaults, so add only values that belong to your site.

app/app.config.ts
export default defineAppConfig({
  ginkoDocs: {
    site: {
      url: "https://docs.example.com",
      name: { en: "Acme Docs", de: "Acme-Dokumentation" },
      description: {
        en: "Documentation for Acme.",
        de: "Dokumentation für Acme.",
      },
      logo: {
        light: "/logo.svg",
        dark: "/logo-dark.svg",
      },
      docsSidebarSwitcher: "tabs",
      lupinumAttribution: true,
    },
    nav: { links: "auto" },
    social: {
      github: "https://github.com/acme/docs",
      discord: "https://discord.gg/acme",
      linkedin: "https://www.linkedin.com/company/acme",
    },
    feedback: { enabled: true },
    analytics: {
      plausible: { scriptId: "ExampleSiteScriptId" },
    },
    images: { zoom: true },
    toc: { depth: 3 },
    repository: {
      url: "https://github.com/acme/docs",
      branch: "main",
      contentDirectory: "content",
    },
  },
});

Localized values always use the { en, de? } shape. An English-only site still uses { en: '…' }; this keeps layer merging and hot reload deterministic.

site.url is the runtime origin for canonical links and page actions. Use the same production origin in Content config, Nuxt Site Config, and i18n.baseUrl; SEO and social cards shows the complete wiring.

Choose the sidebar section control

site.docsSidebarSwitcher controls only how readers choose a top-level documentation section:

ValueResult
tabsHorizontal section tabs
dropdownOne compact section menu
listA visible list of sections

Section and group titles still come from .navigation.yml. Changing this setting does not create or reorder navigation entries.

Use automatic navigation

Keep nav.links: 'auto' when the header should show Documentation and, if blog: true exists in content.config.ts, Blog. The router is the source of truth for blog availability.

Provide an array only when the header needs different destinations:

app/app.config.ts
export default defineAppConfig({
  ginkoDocs: {
    nav: {
      links: [
        {
          label: { en: "Documentation", de: "Dokumentation" },
          to: { en: "/docs/getting-started", de: "/de/dokumentation/erste-schritte" },
          icon: "lucide:book-open",
          description: {
            en: "Install and configure Acme.",
            de: "Acme installieren und konfigurieren.",
          },
        },
      ],
    },
  },
});

An explicit array replaces automatic links; it does not extend them.

Add an announcement banner

The banner is disabled by default. Enable it with localized copy and an optional explicit destination. The dismissal is stored by id, so change the ID when the message must appear again.

app/app.config.ts
export default defineAppConfig({
  ginkoDocs: {
    banner: {
      enabled: true,
      id: "acme-2",
      text: {
        en: "Acme 2 is available.",
        de: "Acme 2 ist verfügbar.",
      },
      link: {
        label: { en: "Read the release notes", de: "Versionshinweise lesen" },
        to: { en: "/blog/acme-2", de: "/de/blog/acme-2" },
      },
      showOnLanding: true,
    },
  },
});

repository enables edit and issue links. feedback.enabled adds the page-feedback control when Plausible is also configured. Feedback votes emit the docs-feedback event. See the app configuration reference for every field and default.