Methoden-Set

Technische Dokumentation. methoden-set/ (eigener Top-Level-Ordner im Website-Repo) ist ein eigenständiges, rein clientseitiges Werkzeug: Nutzer*innen fügen Links auf Methoden oder Varianten der Website ein, sortieren sie per Drag & Drop und laden das Ergebnis als Ordner (.zip), als eine zusammenhängende Markdown-Datei oder als Word- oder OpenDocument-Dokument (.docx/.odt, per Pandoc, mit eigener Vorlagen-Auswahl inkl. Upload, optionalem Inhaltsverzeichnis und Kapitelnummerierung) herunter. Läuft vollständig im Browser, keine Serverkomponente und keine Datenübertragung nach außen.

Warum ein eigener Top-Level-Ordner, nicht Teil von Hugo

hugo/content wird komplett von module.mounts aus dem externen Content-Repo bestückt – es gibt keinen Mount für eigene, im Website-Repo gepflegte Hugo-Seiten. Genau wie Decap CMS (admin/) läuft methoden-set/ deshalb nicht über Hugo, sondern wird im Deploy-Hook separat per rsync kopiert (siehe Getting Started, Schritt 7).

Wie die Website die Rohdaten liefert

Jede Variante wird zusätzlich zur normalen HTML-Seite unter <variante-url>index.md als selbstbeschreibendes Markdown-Dokument ausgeliefert (z. B. https://ableger.example.org/eine-variante/index.md). Zuständig: [outputFormats.MethodenSetMd] + zwei [[cascade]]-Regeln in hugo/hugo.toml (eine für die Section varianten, eine für Methoden-Seiten selbst) sowie die Templates hugo/layouts/varianten/single.md und hugo/layouts/_default/single.md, die beide dasselbe gemeinsame Partial partials/methoden-set-dokument.html aufrufen.

Hat eine Methode genau eine Variante, bettet ihre HTML-Seite (_default/single.html) den Variantentext direkt ein, ohne einen sichtbaren Link auf die eigentliche Varianten-URL zu zeigen. Nutzer*innen kopieren deshalb naheliegend die Methoden-URL. _default/single.md löst das genauso auf: bei genau einer Variante liefert die Methoden-URL exakt dasselbe Dokument wie die Varianten-URL selbst; bei 0 oder mehreren Varianten ein kurzes Hinweis-Dokument (fehler: "keine_variante" bzw. "mehrere_varianten" im YAML-Header), das methoden-set/app.js erkennt und in eine präzise Fehlermeldung übersetzt statt eines generischen 404.

Das gemeinsame Partial fasst serverseitig zusammen, was sonst über mehrere Partials auf der Varianten-/Methode-Seite verteilt ist (Steckbrief, „Diese Variante“, Inhalt, Anhänge). Hugo hat die Methode-Variante-Relation und alle Feldnamen längst aufgelöst, eine zweite (spätere) Implementierung dieser Verknüpfungslogik in JavaScript wäre unnötige Dopplung. Der Client macht pro eingefügtem Link nur einen fetch() und bekommt ein fertiges Dokument zurück.

Der YAML-Header ist bewusst minimal (titel, quelle, optional fehler). Autor*innen, Lizenz und ein Link zurück zur Ableger-Seite stehen stattdessen als lesbarer Fließtext am Ende jedes Dokuments (automatische Quellenangabe). Es ist keine zweite, im Client zu parsende Metadatenstruktur nötig. Eingebettete Bilder (![]()) werden dabei auf absolute URLs umgeschrieben.

Überschriften-Verschiebung: Der Inhalt (Vorbereitung/Ablauf/Hintergründe) wird von Nutzer*innen als eigenständige H1-Abschnitte verfasst. Im Methoden-Set-Dokument hängen sie aber unter der Dokument-Überschrift (ebenfalls H1) und „## Diese Variante“. partials/methoden-set-shift-headings.html verschiebt deshalb jede ATX-Überschrift im Inhalt um eine Ebene nach unten (H1→H2 usw.), außerhalb eingezäunter Codeblöcke. Das wirkt sich einheitlich auf Einzel-Variante, Zip, Markdown und Word/ODT aus, da alle vier auf demselben .md-Dokument basieren.

Der Client (methoden-set/)

• index.html – Formular/Liste, Kopfbereich wie admin/index.html für optische Konsistenz mit dem Rest der Website. Jede Zeile der Sortierliste ist zweizeilig aufgebaut (Titel+Entfernen-Knopf oben, Seitenumbruch-Regler als große Toggle-Buttons darunter) statt einer einzelnen, umbruchgefährdeten Flex-Zeile.
• app.js – Link-Validierung (Methode oder Variante), Sortierliste (Drag & Drop, Seitenumbruch-Regler, Gliederungsvorschau), die drei Download-Pfade.
• zip-writer.js – minimaler, selbst geschriebener Store-only-ZIP-Writer (keine Kompression).
• vendor/ – Pandoc als WASM-Binary + der offline-fähige Lade-Mechanismus, siehe unten.
• vorlagen/ableger-standard.docx und ableger-standard.odt – neutrale Standard-Vorlagen, siehe unten. Die Vorlagen-Auswahl im Formular wird zur Laufzeit aus vorlagen/vorlagen-manifest.json gebaut (siehe „Vorlagen automatisch erkennen“ unten). Sie wird nach der gerade gewählten Format-Radio (Word/OpenDocument) gefiltert, da die Referenzvorlagen formatgebunden sind. Am Ende der Liste steht immer zusätzlich „Eigene Vorlage hochladen“. Die Funktion bleibt rein clientseitig.
• Inhaltsverzeichnis und Kapitelnummerierung sind eigene Schalter (Standard: TOC an, Nummerierung aus).

Bilder: same-origin ![]()-Referenzen werden für Zip und Word einmalig abgerufen und lokal umbenannt (Pandoc-WASM hat keinen Netzwerkzugriff, ein Zip soll offline browsbar sein). Die reine Markdown-Datei behält dagegen die ursprünglichen absoluten URLs.

Pandoc als WASM-Binary

Liegt in methoden-set/vendor/, bezogen direkt aus den offiziellen npm-Paketen:

Der einzige Unterschied zu den Original-Dateien: core.js importiert im Original vom bare-specifier "@bjorn3/browser_wasi_shim". Das braucht einen Bundler, den es hier bewusst nicht gibt (keine Build-Pipeline, reine statische Dateien). Ersetzt durch zwei Platzhalter (__WASI_SHIM_FS_MEM_URL__, __WASI_SHIM_WASI_URL__), die app.js zur Laufzeit durch echte Blob-URLs ersetzt (loadPandocCoreModule()). Baut aus den fünf Shim-Dateien Blob-URLs und verdrahtet ihre gegenseitigen relativen Imports, bevor import() das fertige, gepatchte core.js-Modul lädt.

Update-Strategie: pandoc-wasm-Version in der obigen Tabelle anheben, npm pack pandoc-wasm@<version> (und bei Bedarf @bjorn3/browser_wasi_shim) neu ziehen, Dateien ersetzen, den Patch am Import-Block in core.js erneut anwenden, kurzer Testlauf (Zip/Markdown/Word mit 1–2 Varianten). Siehe auch Abhängigkeiten & Updates.

Die Vendor-Dateien liegen als normale, separat ladbare statische Dateien vor und werden erst beim Klick auf „Als Word (.docx)“ nachgeladen, nicht beim Seitenaufruf.

Standard-Vorlagen (methoden-set/vorlagen/)

• ableger-standard.docx: erzeugt aus Pandocs eigener Standard-Referenzvorlage (pandoc --print-default-data-file reference.docx), Überschriftenfarbe und Theme-Akzentfarbe eingefärbt passend zum eigenen hugo/static/css/style.css.
• ableger-standard.odt: aus Pandocs Standard-ODT-Referenzvorlage (pandoc --print-default-data-file reference.odt). Anders als bei docx hat die ODT-Vorlage von Haus aus keine Überschriftenfarbe definiert (kein fo:color in styles.xml), deshalb direkt ergänzt statt ersetzt (Heading_20_1 bis Heading_20_6). Beim erneuten Packen muss mimetype als erster Zip-Eintrag unkomprimiert (zip -0) enthalten sein, sonst erkennen manche ODF-Programme die Datei nicht korrekt als ODT.

Bei einer eigenen, hochgeladenen Vorlage (egal welches Format) bleibt diese unangetastet – das Formular reicht die Datei direkt als reference-doc an Pandoc weiter, ohne sie zu verändern oder zu speichern.

Vorlagen automatisch erkennen (scripts/generate-vorlagen-manifest.rb)

Weitere .docx/.odt-Vorlagen landen in der Formular-Auswahl, ohne dass dafür Code geändert oder etwas deployt werden muss. Selbst wenn jemand eine Datei direkt per SCP/SFTP, am Git-Repo vorbei, in DOCROOT/methoden-set/vorlagen/ auf dem Server ablegt. methoden-set/ ist rein statisch, es gibt keinen Serverprozess, der ein Verzeichnis dynamisch aufzählen könnte. Der Deploy-Hook läuft scripts/generate-vorlagen-manifest.rb deshalb bei jedem Durchlauf nach dem rsync von methoden-set/ und gegen das Docroot selbst, nicht gegen den Git-Arbeitsbaum. rsync läuft dort bewusst ohne --delete, manuell hinzugefügte Dateien überleben also ohnehin jeden Deploy und werden vom Skript mit erfasst. Das Ergebnis: vorlagen/vorlagen-manifest.json, eine schlichte Liste aus datei (Dateiname), format (Endung ohne Punkt) und label (aus dem Dateinamen abgeleitet). methoden-set/app.js lädt diese Datei beim Öffnen der Seite, mit Rückfallebene auf die beiden bekannten Standard-Vorlagen, falls die Manifest-Datei fehlt (z. B. in einer lokalen Vorschau ohne Deploy-Hook).

vorlagen-manifest.json selbst ist nicht versioniert, es wird bei jedem Deploy frisch aus dem tatsächlichen Docroot-Inhalt erzeugt.