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.2

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.

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.

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" >}}

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.

Shortcodes

Alle Komponenten des Themes, mit dem Markdown, das sie erzeugt.

Hinweisboxen#

Karten#

Tabs#

npm install

pnpm install

go mod download

Aufklappbare Abschnitte#

Terminal#

$ hugo server --disableFastRender
Watching for changes in content and layouts
Built in 284 ms
Web Server is available at http://localhost:1313/

Dateibaum#

Diagramme#

flowchart LR
  A[Auslöser] --> B[Prüfung]
  B --> C[HTML]
  C -->|erfüllt| D[Staging]
  C -->|verletzt| E[Abbruch und Meldung]

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.

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.

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

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.

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

Responsive Mermaid-Diagramme aus Markdown rendern.

Mermaid erzeugt Diagramme aus Text. Ein mermaid-Codeblock lädt die 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]
```

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.