Aussehen anpassen

Farben, Schriften und Maße der Doku-Ebene über Tokens, die zwei Farb-Presets, hell und dunkel, eigene Teile über Override-Stellen und eigene Seiten im Rahmen der Doku.

Ändere zuerst Tokens. Ersetze ein Teil erst, wenn die Tokens das Ergebnis nicht hergeben. Alles auf dieser Seite ist öffentlich und bleibt zwischen Releases stabil.

Ein Preset wählen

theme in der app.config.ts wählt eines von zwei Farb-Presets:

// app/app.config.ts
export default defineAppConfig({
  docs: { theme: 'green' },
})

Preset	Farben
`default`	Smaragd auf Zink
`green`	Grün auf Schiefer

Das Preset setzt nur Vorgaben. Jedes Token, das deine Seite setzt, gewinnt über beide.

Farben und Schriften

Die Ebene ist reines CSS. Farben, Radius und Schriften sind Tokens im Stil von shadcn, dieselben, die @lupinum/ginko-components liest:

--background, --foreground, --muted, --muted-foreground, --accent, --border, --primary, --primary-foreground, --card, --popover, --ring, --radius, --font-sans und --font-mono.

Die Vorgaben der Ebene liegen in @layer theme und haben keine Spezifität. Also gewinnt jeder Wert, den deine Seite setzt, ohne Layer oder über @theme von Tailwind 4:

css

/* app/assets/site.css */
:root {
  --primary: light-dark(#2f6f4f, #7cc59d);
  --primary-foreground: light-dark(#fff, #0c1f15);
  --font-sans: 'Inter', system-ui, sans-serif;
}

Setze --primary-foreground mit --primary. Eine helle Farbe wie Gelb braucht dunklen Text; prüfe den Kontrast in beiden Modi.
Eine eigene Schrift lädt deine Seite selbst, bevor ein Token sie nennt. Die Ebene bringt Inter und JetBrains Mono mit.
Auf einer Tailwind-4-Seite ohne eigenes --font-sans und --font-mono gewinnen die Schriften von Tailwind.
Die Code-Blöcke haben eigene Tokens (--ginko-code-bg und weitere), siehe Komponenten.

Hell und dunkel

Die Vorgaben sind light-dark(hell, dunkel)-Paare. Ohne Wahl folgt die Seite dem System. Der Schalter in der Kopfzeile speichert die Wahl des Lesers in localStorage (Schlüssel docs-color-mode) und setzt data-theme="light" oder data-theme="dark" auf <html>. Ein kleines Skript im Kopf setzt das vor dem ersten Zeichnen, also flackert nichts.

Eine Klasse .dark auf <html>, zum Beispiel von @nuxtjs/color-mode, geht auch. Wenn deine Seite eigene Werte für beide Modi setzt, schreibe sie ebenfalls als light-dark()-Paare.

Maße

Auch die Maße des Layouts sind Tokens:

Token	Vorgabe	Was es setzt
`--docs-max`	`90rem`	Breite der Doku samt Rändern
`--docs-gutter`	`1rem`	Abstand zwischen Fensterrand und Doku
`--docs-top`	`0px` (allein: die Kopfzeile)	Höhe dessen, was über der Doku klebt
`--docs-sidebar`	`17rem`	Breite der Navigation
`--docs-toc`	`13.5rem`	Breite von „Auf dieser Seite“ neben dem Text (ab 80rem Fensterbreite)
`--docs-measure`	`38rem`	Lesebreite des Fließtexts
`--docs-h1`	`clamp(1.75rem, …, 2.25rem)`	Größe der Seitentitel
`--docs-header`	`4rem`	Höhe der Kopfzeile der eigenständigen Doku

In einer bestehenden Seite richten --docs-max und --docs-top die Doku am Rest der Seite aus; mehr dazu auf Doku-Seiten.

Override-Stellen

Die Ebene bringt zwei leere Komponenten mit. Deine Seite ersetzt sie mit einer eigenen Datei gleichen Namens in app/components/:

DocsPageEnd (Prop doc, der Eintrag der Seite): nach dem Text jeder Seite, vor „Diese Seite bearbeiten“ und Zurück/Weiter. Für einen Hilfe-Kasten oder einen Aufruf zum Handeln.
DocsSidebarEnd: unter der Navigation, in der Seitenleiste und im Menü auf dem Handy. Für ein paar Links oder eine Kontaktzeile.

vue

<!-- app/components/DocsPageEnd.vue -->
<script setup lang="ts">
defineProps<{ doc: { id: string } }>()
</script>

<template>
  <aside class="support">Fragen? <a href="mailto:hilfe@example.com">Schreib uns</a>.</aside>
</template>

Andere Docs*-Komponenten ersetzt du nicht: sie sind intern und können sich in jedem Release ändern. Auch die CSS-Klassen der Ebene sind kein Vertrag. Gestalte über die Tokens oben.

Eigene Seiten und eigenes Layout

Eine Seite gewinnt. Legt deine Seite eine Seite an derselben Adresse an, zum Beispiel app/pages/index.vue, fügt die Ebene dort keine eigene hinzu.
Eigene Seite im Rahmen der Doku. <DocsShell> ist der Körper der Doku: Navigation, Suche und die Leiste auf dem Handy. Der Standard-Slot nimmt die Seite auf, der Slot bar Bedienelemente für die Leiste auf dem Handy:

vue

<!-- app/pages/help/index.vue; die Doku liegt unter /help (docsCollection({ locales, base: '/help' })) -->
<script setup lang="ts">
const docs = useGinko('docs')
</script>

<template>
  <DocsShell>
    <h1>Wie können wir helfen?</h1>
    <ul>
      <li v-for="item in docs.items" :key="item.id"><NuxtLink :to="item.url">{{ item.data.title }}</NuxtLink></li>
    </ul>
  </DocsShell>
</template>

Eigenes Layout. Mit einer eigenen app/layouts/default.vue behält deine Seite ihren Kopf und Fuß, und die Doku sitzt darin. Die Suche bringt <DocsShell> mit, über der Navigation. Suche, Sprachen und Hell-Dunkel-Schalter kannst du auch in deinen eigenen Kopf setzen: <DocsSearch />, <DocsLanguage />, <DocsThemeToggle />. Mit docs: { search: false } in der app.config.ts lässt die Ebene dann ihre eigene Suche weg.
Texte. Jeder Text der Ebene ist eine Meldung unter docs.*, und die Meldungen deiner Seite gewinnen Schlüssel für Schlüssel. Ein Hilfe-Center formuliert die Suche zum Beispiel so, in i18n/de.json: { "docs": { "searchPlaceholder": "Hilfe durchsuchen …" } }.

Kopiere die Ebene nicht in deine Seite. Eine Kopie bekommt keine Fehlerbehebungen mehr, und es ist dann unklar, ob Tokens, Konfiguration oder dein Code eine Entscheidung treffen.