Dokumentationsinhalte schreiben

Erstelle eine Markdown-Datei für jede Frage oder Aufgabe deiner Leser. Ginko Docs rendert Titel und Beschreibung aus dem Frontmatter über dem Inhalt und baut das Inhaltsverzeichnis aus den Überschriften im Dokument.

Mit Pflichtfeldern beginnen

Dokumentationsseiten benötigen title und description:

---
title: Webhooks konfigurieren
description: Sende signierte Ereignisse von Acme an einen HTTPS-Endpunkt.
---

Erstelle einen Endpunkt für `POST`-Anfragen, bevor du ihn zu Acme hinzufügst.

## Endpunkt hinzufügen

Öffne die Projekteinstellungen und trage die öffentliche HTTPS-URL ein.

## Signatur prüfen

Lies den Signatur-Header, bevor du den Request-Body verarbeitest.

Das Theme verwendet title als Überschrift erster Ebene und description als Seiteneinleitung, SEO-Beschreibung und Text für Social Cards. Wiederhole den Titel nicht mit einer #-Überschrift im Inhalt.

Jede Seite fokussieren

Beginne mit dem Ergebnis, der Definition oder der Einschränkung. Zeige einen funktionierenden Befehl oder ein Beispiel vor ergänzenden Hintergründen. Verwende Überschriften in Satzschreibweise und direkte Anweisungen.

Eine Aufgabenseite sollte zu einem Ergebnis führen. Verschiebe allgemeine Erklärungen auf eine Konzeptseite und vollständige Optionslisten in die Referenz.

Vermeide Füllwörter wie „einfach“, „offensichtlich“ und „abschließend“. Die Seite enthält bereits Links zur vorherigen und nächsten Seite. Beende sie deshalb mit der letzten nützlichen Anweisung oder dem erwarteten Ergebnis.

Dateien ohne URL-Änderung sortieren

Stelle Geschwisterordnern und -dateien Nummern voran:

Die numerischen Segmente bestimmen die Reihenfolge in der Sidebar und zwischen vorheriger und nächster Seite. Ginko entfernt sie aus öffentlichen URLs.

Bilder hinzufügen

Einfache Markdown-Bilder sind der Standard für Screenshots und Illustrationen im Fließtext:

![Arbeitsplatz für eine redaktionelle Planungssitzung](/images/content-demo-workspace.jpg)

Lokale Bilder rendern über Nuxt Image mit Lazy Loading und responsiven Größen und öffnen sich per Klick im Zoom-Dialog, solange images.zoom in der App-Konfiguration aktiviert bleibt. Externe URLs rendern unoptimiert. Verwende stattdessen die figure-Komponente, wenn das Bild eine Bildunterschrift, einen Bleed oder ein festes Seitenverhältnis braucht.

Codebeispiele beschriften

Schreibe den echten Dateinamen hinter die Sprache des Codeblocks, damit Leser wissen, wohin der Code gehört:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ["@lupinum/ginko-docs"],
});
```

Verwende das kleinste Beispiel, das die Anweisung belegt. Zeige erforderliche Importe und umgebende Konfiguration, wenn das Beispiel sonst nicht funktionieren würde.

Lange Beispiele einklappen

Wenn ein vollständiges Beispiel lang bleiben muss, umschließe es mit der Komponente collapse. Der Block wird auf eine feste Höhe gekürzt und erhält die Aktion „Alle Zeilen anzeigen“; nach dem Ausklappen entfällt der innere Scrollbereich und die Seite scrollt normal:

::collapse

```ts [app/app.config.ts]
export default defineAppConfig({
  // …eine vollständige Konfiguration, die zu lang für eine Ansicht ist
});
```

::

Inhalt, der in die eingeklappte Höhe passt, erscheint ohne die Aktion; die Komponente ist daher für jedes Beispiel sicher, das wachsen kann.