Teilbücher¶
Achtung
Verändern an der Teilbücher-Struktur gehören nicht zur regelmäßigen Arbeit an den GLAREAN-Anleitungen und sollten nur von Administratoren vorgenommen werden.
Hinweis
Nach jeder Veränderung auf dieser Ebene müssen die GLAREAN-Anleitungen neu initialisiert werden, wie in Bearbeiten beschrieben.
Grundlagen¶
Die Teilbuch-Struktur der GLAREAN-Anleitungen ist in der Datei /_config/outline.yml in einer YAML-Liste definiert, welche die Pfadsegmente zu den Teilbüchern enthält:
# Hauptbuch
- main
# Teilbücher
- plattform
- organisation
- elearning
Grundsätzlich ist der erste Eintrag in dieser Liste das Hauptbuch und wird (wie im Folgenden beschrieben) unterschiedlich behandelt.
Pfadsegmente in URLs und im Projektrepository¶
Zunächst einmal entsprechen diese Pfadsegmente den Unterverzeichnissen
/books/<teilbuch> im Projektrepository, d.h. jedem Eintrag in der
outline.yml muss ein Teilbuch-Unterverzeichnis entsprechen.
Die Verzeichnisnamen werden automatisch auf das erste Pfadsegment in der URL
abgebildet, d.h. eine URL
https://glarean.mh-freiburg.de/anleitungen/<teilbuch>/datei.html wird auf die
Seite zeigen, die aus der Datei /books/<teilbuch>/docs/datei.md erzeugt wird.
Achtung
Der Verzeichnispfad des Hauptbuchs wird nicht in ein Pfadsegment überführt
– Die Datei /books/main/docs/test.md entspricht der URL
https://glarean.mh-freiburg.de/anleitungen/test.html.
Beachten Sie, dass als Konsequenz hieraus Unterverzeichnisse von
/books/main/docs keinen Namenskonflikt mit Unterverzeichnissen von /books
haben dürfen.
Verzeichnisstruktur der Teilbücher¶
Jedes Teilbuch muss bestimmten Konventionen folgen, um als gültiges Teilbuch zu fungieren. Andernfalls droht das Scheitern des Übersetzungsvorgangs oder (vermutlich schlimmer) ein unbestimmtes Ergebnis.
Das Teilbuchverzeichns enthält die beiden Ordner _config und docs sowie die
Datei mkdocs.yml. Letztere wird automatisch generiert und sollte nicht manuell
bearbeitet werden.
Das docs-Verzeichnis¶
Im Verzeichns docs sind die Markdown-Dateien abgelegt, aus denen die Webseiten
erzeugt werden. Unterverzeichnisse sollten der Struktur der Pfadsegmente der
resultierenden Website entsprechen. Per Konvention kann das docs-Verzeichnis
ein Unterverzeichnis media enthalten, das Mediendateien wie Bilder oder Videos
enthält.
_config/book-config.yml¶
Die Datei _config/book-config.yml in jedem Teilbuch enthält eine Reihe von
Konfigurationsvariablen, die die Seitenvorlage für die jeweiligen Seiten
bestimmen. Werden sie gesetzt, überschreiben sie die Vorgabewerte aus der Datei
/_config/defaults.yml:
book_title: Siehe nächster Abschnittlink_to_siblings: Füge die Teilbuch-Navigation hinzu. Ist in allen Unterbüchern, nicht aber im Hauptbuch aktiviert.primary_color,accent_color: Farbschema des Buches. Unterstützt werden die Farbnamen des Material-Themas: https://squidfunk.github.io/mkdocs-material/getting-started/#color-palettetabs: Verwende die erweiterte Tabs-Navigation. Ist per Vorgabe in jedem Buch aktiviert.
_config/navigation.yml¶
Diese Datei enthält die Navigationsstruktur des Teilbuchs. TODO: Verweis auf mkdocs-library-Dokumentation, wenn diese fertig ist.
Markdown-Dateien, die nicht explizit in der Navigation aufgeführt sind, werden nicht gerendert.
Hauptnavigation des Übersichtsbuches¶
In den Teilbüchern ist per Vorgabe die Option tabs aktiviert, so dass die oberste Navigationsebene in den »Tabs« der Titelzeile abgebildet wird.
Das Übersichtsbuch ist hier insofern eine Ausnahme, als die Links in den Tabs
keine echte Navigationsebene darstellen, sondern auf die jeweiligen Teilbücher
verweisen. Die Tab-Links, die im Hauptbuch der GLAREAN-Anleitungen sichtbar
sind, werden am Ende der Datei /books/main/_config/navigation.yml als Elemente
der ersten Navigationsebene manuell kodiert.
Hinweis
Diese Besonderheit hat die Implikation, dass die Titel der Teilbücher nicht nur in den Konfigurationsdateien des jeweiligen Teilbuchs, sondern redundant auch in der Navigation des Hauptbuchs kodiert sind. Bei Veränderungen ist hier auf Konsistenz zu achten.