Zum Inhalt

Verändern der Navigationsstruktur

Neben dem Inhalt einzelner Seiten können Sie auch die Navigationsstruktur der Bücher verändern, also Seiten umbenennen, ergänzen oder löschen. Dies erfordert allerdings einen zusätzlichen Arbeitsschritt, dessen Grundlagen in der Dokumentation zu mkdocs-library beschrieben sind.

Hinweis

Die folgenden Erläuterungen betreffen die etwas komplexeren Eingriffe in die Website und sind für viele Mitwirkende vermutlich irrelevant. Wir haben uns daher auch weniger Mühe gegeben, sie leicht verständlich abzufassen.

Lassen Sie sich also bitte weder vom weniger bekömmlichen Tonfall nicht irritieren oder gar verunsichern.

Speicherung der Navigationsstruktur

Unterschiede zwischen MkDocs und mkdocs-library

mkdocs-library weicht hinsichtlich der Speicherung und Verwaltung der Navigationsstruktur von MkDocs ab. Anstelle einer zentralen YAML-Steuerdatei mkdocs.yml wird die Navigationsstruktur jedes Teilbuchs in einer Datei books/<buch>/_config/navigation.yml als Liste definiert, die dem Inhalt des nav:-Elements einer regulären MkDocs-Steuerdatei entspricht.

MkDocs:

# /mkdocs.yml
# ...
nav:
  - Home: index.md

mkdocs-library:

# /books/<book>/_config/navigation.yml
- Home: index.md

Zur YAML-Struktur der Navigation allgemein siehe auch die entsprechende Dokumentation bei MkDocs direkt.

Die Links in der Navigationsdatei sind in der Regel als Links auf die .md-Dateien zu notieren (siehe obige Beispiele) und sind relativ zum Wurzelverzeichnis des Teilbuches. Der Link auf die Seite im Buch »Die GLAREAN-Plattform« mit der Web-URL plattform/magazin/glarean.html hat in der Navigationsdatei books/plattform/_config/navigation.yml demnach die Adresse magazin/glarean.md.

Die Architektur von mkdocs-library macht es unmöglich, auf Seiten in anderen Teilbüchern ebenso nativ zu verweisen, diese müssen als externe Links behandelt werden. Im gerenderten ist das »main«-Buch im Hauptverzeichnis zu finden, die Teilbücher in entsprechenden Unterverzeichnissen. Das heißt, dass Links aus Teilbüchern ein ../ vorangestellt werden muss, Links in Teilbücher darüber hinaus deren Hauptverzeichnis. Das Ziel solcher Links ist die generierte HTML-Datei

Seiten anlegen und löschen

Neue Seite

Eine neue Seite anzulegen, erfordert drei Schritte (abgesehen von sorgfältiger Überlegung):

  • Ergänzung eines Eintrags in der _config/navigation.yml des betroffenen Teilbuchs (Link auf .md-Datei)
  • Erstellen der zugehörigen Markdown-Datei
  • Generieren der Navigation durch das mkdocs-library-Script.

Es empfiehlt sich, nach Erstellen der - leeren - Seite einen Git Commit zu erstellen.

Seite entfernen

Umgekehrt ist für das Entfernen von Seiten theoretisch nur das Entfernen des Eintrags aus der navigation.yml erforderlich. Doch gebietet es die Code-Hygiene, auch die zugehörige .md-Datei aus dem Verzeichnis zu löschen.

Auch hier sollte unmittelbar ein Commit erfolgen und die Struktur durch mkdocs-library aktualisiert werden.

Letztes Update: 9. März 2020