Administrationsseite

Mitglieder, Rollen, Statusanzeigen und responsive Datentabelle.

Erste Schritte

Theme installieren, erforderliche Hugo-Konfiguration ergänzen und lokal starten.

Voraussetzungen#

Hugo ab 0.128.0, Go für Hugo Modules, Node.js mit npm für Tailwind sowie Git.

Installation#

[module]
  [[module.imports]]
    path = "github.com/projectious-work/brand-theme-hugo-vanilla"

[build.buildStats]
  enable = true

hugo mod init example.com/docs
npm install
hugo mod get github.com/projectious-work/brand-theme-hugo-vanilla@v0.3.3

Kopieren Sie [outputFormats], [outputs] und [markup] aus der Beispielkonfiguration. Sie aktivieren Suche, Druck, Markdown, llms.txt, Syntaxhervorhebung und Mathematik.

Erste Seite und lokaler Server#

Legen Sie content/docs/_index.md sowie eine Markdown-Seite mit title, description und weight an. Starten Sie anschließend:

hugo server --disableFastRender

Weiter geht es mit Konfiguration, Features und dem Autorenleitfaden.

Versionierte Dokumentation

Getrennte Builds veröffentlichen und über das Versionsmenü verbinden.

Jede Version ist ein eigener Hugo-Build. Die aktuelle Dokumentation bleibt am stabilen Root, ältere Versionen liegen beispielsweise unter /v0.2/. Tragen Sie nur bereits veröffentlichte URLs in params.versions ein. Mit probe = false landet ein Eintrag auf der Versionsstartseite statt beim gleichen Seitenpfad.

Website-weite Konfiguration

Hugo, Ausgaben, Menüs, Sprachen und Theme-Parameter konfigurieren.

Dateien und Zuständigkeiten#

src/content/hugo.toml ist die vollständige lauffähige Referenz. Übernehmen Sie die benötigten Tabellen in die Konfiguration Ihrer Website.

Mindestkonfiguration und Ausgabeformate#

Setzen Sie baseURL, title, das Hugo-Modul und build.buildStats.enable = true. Die zusätzlichen Ausgabeformate erzeugen:

Theme-Parameter#

Parameter stehen unter [params]. Häufig benötigt werden github, editURL, version, versions, sidebarSections, codeTheme, announcement, feedbackEndpoint und selfHostAssets. Die Schalter search, feedback, accessibilityMenu, sidebarFilter und commandPalette lassen sich mit false abschalten.

Notebook-Konvertierung#

python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
./scripts/notebooks.sh

Das Ergebnis liegt unter content/_notebooks/ und static/notebooks/.

Suchmaschinen und llms.txt#

robots.txt schließt doppelte Such- und Druckansichten aus. Die Sitemap enthält Sprachalternativen. llms.txt ist davon unabhängig: Es listet kanonische Titel, Beschreibungen und Markdown-Links für Werkzeuge auf; es ist keine Zugriffskontrolle.

Prüfen Sie jede Änderung mit ./scripts/verify.sh.

Dashboard

Betriebsmetriken, Aktivitätstrends und Pipeline-Status.

Leitfaden zur Template-Erstellung

Upgrade-sichere Hugo-Layouts und Shortcodes mit Theme-Tokens und Tailwind erstellen.

Erweiterungen gehören in die konsumierende Website, weil lokale Hugo-Layouts vor dem Theme-Modul aufgelöst werden. Wählen Sie den kleinsten Erweiterungspunkt: Shortcode für Inhaltskomponenten, Partial für wiederverwendbares Template-Markup oder ein Bereichslayout für eine abweichende Seitenstruktur.

1. Aktivieren Sie [build.buildStats] enable = true in hugo.toml.
2. Installieren Sie @tailwindcss/cli und versionieren Sie den Lockfile.
3. Legen Sie beispielsweise layouts/shortcodes/status-panel.html an.
4. Verwenden Sie vollständige Klassen wie bg-surface, text-hi, border-default, rounded-lg und p-6; dynamisch zusammengesetzte Klassen werden von Tailwind nicht zuverlässig erkannt.
5. Bevorzugen Sie semantische Variablen wie --color-surface, --space-5 und --radius-lg.
6. Ergänzen Sie Tabler-SVGs unter assets/icons/ und vergeben Sie für bedeutungstragende Symbole einen zugänglichen Namen.
7. Prüfen Sie Produktion, Farbmodi, 200 Prozent Textgröße, Tastatur, Mobilansicht, Druck und alle Sprachen.
8. Vergleichen Sie lokale Overrides bei jedem Theme-Upgrade mit dem neuen Upstream-Template.

Die vollständigen Klassen und Tokens beschreibt Tailwind und Design-Tokens.

Seitenkonfiguration (Frontmatter)

Navigation und optionale Funktionen einer Seite steuern.

Frontmatter ist der TOML-Block zwischen +++ am Anfang einer Markdown-Datei.

+++
title = "API-Referenz"       # Erforderlicher Seitentitel.
linkTitle = "API"            # Kurzer Navigationstitel.
description = "HTTP API."   # Zusammenfassung und Suchtext.
weight = 20                  # Reihenfolge in der Navigation.
icon = "code"               # Icon der Übersichtskarte.
toc = true                   # Rechte Inhaltsnavigation anzeigen.
cards = true                 # Karten für Unterseiten erzeugen.
hidden = false               # Seite in Karten anzeigen.
math = false                 # KaTeX auf dieser Seite laden.
private = false              # Seite in Suche und Sitemap aufnehmen.
+++

Tokens und öffentliche API

Stabile semantische CSS-Tokens und Tailwind-Namensräume aus dem Theme-Quelltext.

Die Tabellen werden während des Hugo-Builds direkt aus dem CSS des Themes erzeugt. Eigene Templates sollten semantische Tokens und dokumentierte Tailwind-Namensräume verwenden, nicht interne Palettenstufen oder Selektoren.

Einstellungen

Formulargruppen, Validierung, Schalter und Speicheraktionen.

Terminal-Aufzeichnungen

Kopierbare Terminalsitzungen mit asciinema einbetten.

asciinema speichert Text und Zeitinformationen statt Video. Legen Sie die .cast-Datei im Seiten-Bundle oder unter static/casts/ ab.

{{< asciinema src="/casts/theme-tour.cast" rows="8" cols="80"
     idleTimeLimit="1.5" >}}

Preisseite

Drei klare Angebote mit hervorgehobener Empfehlung.

Tailwind und Design-Tokens

Tailwind-Integration und projectious.work Design-Tokens verwenden.

Markdown-Autoren benötigen Tailwind nicht. Template-Entwickler können die in assets/css/theme-layer.css definierten Klassen verwenden: font-display, font-sans, font-mono, bg-page, bg-surface, bg-subtle, bg-terminal, text-hi, text-lo, text-accent, border-default und border-accent. build.buildStats.enable = true muss aktiviert sein. Alle CSS-Variablen stehen in assets/css/brand-tokens.css; Grundlage ist das projectious.work Brand-Design-System.

Ausführungsstatus

Zustände für leere, laufende, erfolgreiche und fehlerhafte Läufe.

Tags

Hugo-Taxonomien für Metadaten und thematische Verknüpfungen.

Tags stehen im Frontmatter: tags = ["release", "barrierefreiheit"]. Das Theme zeigt sie in Metadaten, indiziert sie für die Suche und rendert Taxonomie-Seiten. Die Beispielseite führt Tags bewusst nicht in der primären Navigation auf.

Artikelseite

Ein fokussierter Langtext mit Metadaten und Leseführung.

Entwicklerleitfaden

Theme anpassen, gebündelte Assets tauschen und Änderungen testen.

Überschreiben Sie als Nutzer einzelne Hugo-Templates im eigenen layouts/- Verzeichnis, statt den Modul-Cache zu verändern. Nutzen Sie CSS-Variablen aus brand-tokens.css als stabile Anpassungsoberfläche.

Symbole#

Die vollständige Liste liegt unter src/assets/icons/. Gebündelt sind unter anderem accessible, book, brand-github, file, folder, language, menu-2, printer, search, tag und versions. Ersatz-SVGs müssen currentColor, ein kompatibles viewBox und passende Lizenzhinweise verwenden.

Build und Tests#

npm install
./scripts/build.sh
./scripts/verify.sh
./scripts/serve-watch.sh start

Visuelle Baselines werden erst nach Prüfung der Diff-Bilder aktualisiert. Beiträge verwenden kurzlebige Branches, Conventional Commits und Pull Requests.

Suche

Generierter Suchindex, Kopfleisten-Suche und Befehlspalette.

Hugo erzeugt /index.json mit Titel, Beschreibung, Tags, Inhalt sowie H2/H3- Überschriften. FlexSearch läuft lokal im Browser; ein externer Suchdienst ist nicht nötig. / fokussiert die Suche, Strg/Cmd+K öffnet die Befehlspalette.

Aktivieren Sie SearchIndex in outputs.home und legen Sie eine Seite mit layout = "search" an. params.search = false deaktiviert die Funktion.

Änderungsprotokoll

Chronologische Produkthistorie mit semantischen Änderungstypen.

Mathematik

Formeln mit KaTeX inline und als Block rendern.

Setzen Sie math = true im Frontmatter. Inline-Formeln verwenden \\( ... \\); Blöcke werden von $$ eingeschlossen.

\( t_{build} < 1s \)

Wartung und Upgrades

Theme, Abhängigkeiten, Übersetzungen und veröffentlichte Versionen pflegen.

Lesen Sie vor einem Upgrade die Versionshinweise, aktualisieren Sie die fixierte Modulversion mit hugo mod get ...@vX.Y.Z, vergleichen Sie lokale Template- Overrides und führen Sie ./scripts/verify.sh mit der produktiven baseURL aus.

Prüfen Sie regelmäßig npm-Advisories, externe Links, Übersetzungsparität, CDN-Versionen, Barrierefreiheit und veröffentlichte Versionsziele. Releases dieses Repositories laufen lokal über ./scripts/release.sh vX.Y.Z; Tags und Release- Archive sind unveränderliche Wiederherstellungspunkte.

Abhängigkeiten und SBOM

Build-Werkzeuge, Browserbibliotheken, Versionen und Lizenzen.

Exakte npm-Transitive stehen in package-lock.json, Browser-Pins in data/cdn.yaml, Python-Pins in scripts/requirements.txt. IBM Plex Mono enthält normale und kursive Schnitte in 400, 500, 600 und 700. Dadurch verwendet die Syntaxhervorhebung echte Schriftschnitte statt vom Browser synthetisierter Varianten. Schrift- und FlexSearch-Lizenzen werden mit den Assets ausgeliefert.

Jupyter Notebooks

Reproduzierbar konvertierte Notebook-Ausgaben veröffentlichen.

Jupyter Notebooks verbinden Text, Code und Ausgaben. Das Theme konvertiert .ipynb vor dem Hugo-Build in Markdown.

pages = 98
languages = ["English", "Deutsch", "Français"]
pages_per_language = pages / len(languages)
pages_per_language

32.67

{{< notebook "theme-demo" >}}

python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
./scripts/notebooks.sh

Der Shortcode bettet nur konvertierte Dateien ein und führt keinen Code aus.

Internationalisierung

Übersetzte Inhalte, Navigation, Metadaten und RTL konfigurieren.

Definieren Sie Sprachen unter [languages.<code>] mit label und weight und legen Sie Inhalte in Sprachverzeichnissen ab. Suche, Bearbeitungslinks, RSS, Sitemap, hreflang und llms.txt bleiben sprachabhängig. Interface-Texte stehen in i18n/<lang>.toml. languagedirection = "rtl" spiegelt die Struktur.

Kopfleiste und Navigation

Primäre Links, Suche, Sprach- und Versionsmenü konfigurieren.

menus.main definiert primäre Links; verwenden Sie pageRef für interne Seiten und url für externe Ziele. params.github ergänzt das GitHub-Symbol.

Weitere Symbole werden als SVG unter assets/icons/ abgelegt und über partials/icon.html eingebunden. Links mit Symbol benötigen ein aria-label und eine ausreichend große Zielfläche.

Gruppen in der Seitenleiste#

Beim ersten Besuch sind alle Gruppen geschlossen. Unter [params] steuert sidebarOpenDepth, wie viele Ebenen anfänglich geöffnet sind; 0 ist der Standard, 1 öffnet die oberste Ebene. Alle öffnen beziehungsweise Alle schließen ändert den gesamten Baum. Einzelne Änderungen werden je Website und Sprache im lokalen Browserspeicher gesichert und bleiben beim Seitenwechsel erhalten. Die Suche öffnet Treffer nur vorübergehend.

Bearbeiten und Feedback

Quellseiten verlinken und optional Leserfeedback erfassen.

params.editURL zeigt auf das Verzeichnis mit den Markdown-Quellen. Das Theme hängt den relativen Seitenpfad an. Für getrennte Sprachverzeichnisse kann der Wert als Tabelle mit default, de und fr angegeben werden.

params.feedbackEndpoint ist optional. Der Browser sendet Pfad, Bewertung, Titel und Sprache. Die Begrenzung im Browser verbessert nur die Bedienung; der Server muss Herkunft und Felder prüfen, Körpergrößen begrenzen und eine eigene Ratenbegrenzung durchsetzen.

Diagramme und Charts

Responsive Diagramme, datenbasierte Charts sowie hochwertige Vektor- und Bitmap-Grafiken erstellen.

Die Theme bietet drei Hugo-typische Wege: Mermaid direkt in Markdown, den Shortcode chart für CSV-Daten und graphic für SVG- oder Bitmap-Ausgaben von D2, Graphviz, Typst/CeTZ und anderen Generatoren.

Mermaid in Markdown#

Ein mermaid-Codeblock lädt die fest definierte Laufzeit nur auf Seiten, die sie benötigen.

flowchart LR
  M[Markdown] --> H[Hugo]
  H --> P[HTML und Druck]

```mermaid
flowchart LR
  M[Markdown] --> H[Hugo]
  H --> P[HTML und Druck]
```

Diagramme aus CSV#

chart erzeugt beim Hugo-Build ein zugängliches Inline-SVG ohne Browser-JavaScript.

{{< chart src="data/graphics-adoption.csv" type="bar"
    title="Projekte mit generierten Grafiken" >}}

Die erste CSV-Zeile ist die Kopfzeile. Spalte eins enthält Beschriftungen, Spalte zwei positive Zahlen. type akzeptiert bar, line und dot.

Generierte Vektorgrafiken#

D2 eignet sich für Architektur, Graphviz für Graphen und Typst/CeTZ für präzise technische Abbildungen. Die Werkzeuge erzeugen SVG; graphic übernimmt die einheitliche, zugängliche Darstellung.

{{< graphic src="system.svg" alt="Architektur der Anfrageverarbeitung"
    caption="Systemarchitektur" source="system.d2" backend="d2" >}}

Inline-SVG und Bitmap#

Externes SVG über <img> ist der sichere Standard. Vertrauenswürdige SVG-Ressourcen aus assets/ oder einem Page Bundle können mit inline="true" eingebettet werden. PNG, WebP und JPEG funktionieren über denselben Shortcode; sie sind für Screenshots, Fotos und rasterintensive Darstellungen geeignet.

{{< graphic src="diagram.svg" inline="true" alt="Datenfluss" >}}
{{< graphic src="screenshot.webp" alt="Anwendung auf einem Desktop"
    caption="Desktop-Ansicht" >}}

Immer aussagekräftigen Alternativtext und bei Bedarf eine Bildunterschrift angeben. Bedeutung darf nicht ausschließlich durch Farbe vermittelt werden.

Codeblöcke

Syntaxhervorhebung, Dateinamen, Zeilennummern und markierte Zeilen konfigurieren.

Das Theme rendert eingezäunte Markdown-Codeblöcke mit Hugos Chroma-Syntaxhervorhebung. Es ergänzt eine Kopfzeile mit Sprache oder Dateiname und einer Kopierschaltfläche.

Einfaches Beispiel#

```python {filename="report.py"}
print("bereit")
```

Optionen pro Codeblock#

Website-weite Standards#

[markup.highlight]
  lineNos = false
  lineNumbersInTable = true
  noClasses = false
  tabWidth = 4

Attribute am Codeblock überschreiben diese Werte. noClasses = false erlaubt dem Theme, die Farben an den hellen und dunklen Modus anzupassen. Die vollständige Liste steht in Hugos Dokumentation zur Syntaxhervorhebung.

Barrierefreiheit

Tastaturbedienung, Leserpräferenzen und Pflichten für Autoren.

Das Theme bietet Sprunglink, sichtbaren Fokus, semantische Bereiche, skalierbare Schrift, reduzierte Bewegung und kontrastreiche Bedienelemente. Das Menü speichert Textgröße, hohen Kontrast, einen besonders starken Drei-Pixel-Fokusring, Link-Unterstreichung, reduzierte Bewegung und Textabstände lokal.

Autoren benötigen sinnvolle Alternativtexte, geordnete Überschriften und Labels für alleinstehende Symbole.

Aufklappbare Details

Optionale Informationen zugänglich ein- und ausblenden.

{{< details title="Was enthält der Suchindex?" >}}
Titel, Beschreibungen, Tags und Seitentext.
{{< /details >}}

Mit open="true" startet der Abschnitt geöffnet.

Bilder

Abbildungen, Beschriftungen, dunkle Varianten und Lightboxen.

{{< image src="/img/sunrise-brand.svg" alt="Sonnenaufgang über Bergen"
     caption="Markenfarben" >}}

Nutzen Sie bevorzugt Page Bundles. src-dark setzt eine Variante für dunkle Farbmodi. Auch Markdown-Bilder erhalten Abbildung und Lightbox.

Buttons und Badges

Verlinkte Aktionen und kompakte Statuskennzeichnungen.

Buttons#

{{< button label="Dokumentation lesen" href="/de/docs/" >}}

Badges#

v0.3 aktuell

{{< badge "v0.3" >}}
{{< badge label="aktuell" variant="accent" >}}

Dateibäume

Projektstrukturen mit verschachtelten Ordnern und Dateien erklären.

{{< filetree >}}
  {{< folder name="content" >}}
    {{< file name="_index.md" note="Startseite" >}}
  {{< /folder >}}
{{< /filetree >}}

folder unterstützt closed="true"; file unterstützt note und icon.

Hinweisboxen

Ergänzende, warnende oder kritische Hinweise hervorheben.

{{< callout type="warning" title="Achtung" >}}
Prüfen Sie Änderungen vor der Veröffentlichung.
{{< /callout >}}

type akzeptiert info, note, success, warning, error und important.

Icons

Fallback-Icons und die eingebundene Tabler-Bibliothek verwenden.

{{< icon "brand-github" >}}
{{< icon name="printer" class="ico--lg" label="Drucken" >}}

Alle Namen finden Sie in der Tabler-Iconbibliothek. label liefert eine Textalternative für bedeutungstragende Icons.

Karten

Verwandte Seiten, Ressourcen oder Auswahlmöglichkeiten darstellen.

{{< cards cols="2" >}}
  {{< card title="Autorenleitfaden" subtitle="Markdown schreiben."
      link="/de/docs/guides/" icon="file-code" >}}
{{< /cards >}}

cols ist 2, 3 oder 4; card unterstützt außerdem image und alt.

Links

Basispfad-sichere Verweise innerhalb und zwischen Hugo-Seiten.

[Konfiguration](../configuration/_index.md)
[Ausgabeformate](../configuration/site-wide.md#ausgabeformate)
[Abschnitt auf dieser Seite](#links)

Inhaltsbezogene Pfade lassen den Build fehlschlagen, wenn das Ziel verschoben wurde. Externe Links erhalten automatisch sichere Attribute und ein Icon.

Schritte

Geordnete Abläufe mit Markdown oder Komponenten darstellen.

{{< steps >}}
  {{% step title="Installieren" %}}Hugo installieren.{{% /step %}}
  {{% step title="Prüfen" %}}Build starten.{{% /step %}}
{{< /steps >}}

Für Markdown-Inhalt verwenden Sie %; bei verschachtelten Shortcodes <.

Tabs

Gleichwertige Alternativen tastaturzugänglich gruppieren.

{{< tabs items="npm, pnpm" >}}
  {{< tab >}}`npm install`{{< /tab >}}
  {{< tab >}}`pnpm install`{{< /tab >}}
{{< /tabs >}}

Anzahl und Reihenfolge der Beschriftungen müssen zu den tab-Kindern passen.

Terminalausgabe

Statische Befehlsabläufe mit adaptiver Terminaldarstellung zeigen.

$ hugo server
Watching for changes
Built in 284 ms

{{< terminal title="Vorschau" >}}
$ hugo server
Built in 284 ms
{{< /terminal >}}

Für abspielbare Sitzungen verwenden Sie Terminalaufzeichnungen.

Terminologie

Wiederkehrende Begriffe über ein gemeinsames Glossar definieren.

Ein module installiert das Theme. Ein page bundle hält zusammengehörige Ressourcen zusammen.

Ein {{< term "module" >}} installiert das Theme.
{{< term key="page-bundle" label="Page Bundles" >}}

Definitionen liegen in data/glossary.yaml; label überschreibt nur den Text.