8.2 – Eine Doku-Site

Eine Dokumentation mit einigen Bereichen, jeder mit ein paar Kapiteln:

index.md
einstieg/    index.md, installation.md, erste-schritte.md
anleitungen/ index.md, import/…, export/…
referenz/    index.md, cli.md, konfiguration.md

Die vier Einträge

plugins:
  # 1 · Kopf: die Bereiche, ihre Seiten im Menü, mobil hinter dem Burger-Button
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: dropdown
      depth: 2
      trigger: hover
      folderClick: link
      mobile: offcanvas
      ariaLabel: Bereiche
      id: kopf
    layout:
      position: header
      priority: 20
 
  # 2 · Seitenspalte: nur der Bereich, in dem man liest
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: accordion
      scope: section
      showScopeRoot: true
      persistState: true
      mobile: hidden
      ariaLabel: Dieser Bereich
      id: bereich
    layout:
      position: left
      priority: 20
 
  # 3 · Unter dem Text: blättern, aber nicht über den Bereich hinaus
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: pager
      scope: section
      id: blaettern
    layout:
      position: afterBody
      priority: 10
 
  # 4 · Fußzeile: die ganze Site in Spalten
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: columns
      depth: 2
      mobile: accordion
      ariaLabel: Sitemap
      id: sitemap
    layout:
      position: footer
      priority: 10

Warum so

Jede Navigation hat eine Aufgabe. Der Kopf sagt, welche Bereiche es gibt. Die Spalte sagt, wo man innerhalb eines Bereichs steht. Der Pager sagt, was als Nächstes kommt. Die Fußzeile ist der Ort, an dem man nachsieht, wenn man sich verlaufen hat.

Kopf: depth: 2 hält das Menü flach — Bereiche und ihr Inhalt. Unterordner wie import stehen darin als Zeile mit Link auf ihre Ordnerseite, ihre Seiten nicht. hover mit link öffnet beim Überfahren und führt beim Klick auf die Bereichsseite (5.2). Auf dem Smartphone wird die ganze Leiste zum Burger-Menü.

Spalte: scope: section zeigt nur anleitungen, wenn man in den Anleitungen liest. Auf der Startseite gibt es keinen Bereich; dort bleibt die Spalte leer, und das ist richtig — der Kopf zeigt alle Bereiche. mobile: hidden, weil das Burger-Menü auf dem Smartphone dieselbe Aufgabe übernimmt.

Pager: Mit scope: section endet das Blättern am letzten Kapitel des Bereichs, statt kommentarlos in den nächsten zu springen.

Fußzeile: mobile: accordion klappt die Spalten auf dem Smartphone zu einer Liste zusammen, deren Bereiche sich öffnen lassen.

ariaLabel überall außer beim Pager, weil drei der vier <nav> sonst „Hauptnavigation“ hießen; der Pager heißt von sich aus „Vorherige und nächste Seite“ (7.3).

Und der Explorer?

Schaltet man ab — enabled: false beim Eintrag @quartz-community/explorer. Die Spalte übernimmt seine Aufgabe für den aktuellen Bereich, der Kopf für den Rest.

Varianten davon

Wenn …	dann …
die Bereiche viele Unterordner haben	Kopf als mega mit depth: 3
es nur drei, vier Bereiche gibt, und man sehen soll, in welchem man ist	Kopf als tabs, dann entfällt das Menü
die Reihenfolge der Bereiche nicht alphabetisch sein soll	order: { "": [einstieg, anleitungen, referenz] } in allen Einträgen, oder navOrder in den index.md
der Pager durch die ganze Dokumentation führen soll	scope beim Pager weglassen