Bearbeiten und Erzeugen¶
Für das Bearbeiten der Anleitungen selbst sei zunächst auf die Dokumentation von MkDocs verwiesen, insbesondere den Abschnitt Writing with Markdown.
Der Umgang mit dem Projekt als Ganzem wird in der noch nicht existierenden Dokumentation zu mkdocs-library beschrieben, daher hier lediglich einige spärliche Hinweise - nähere Auskünfte werden gern erteilt.
Initialisieren¶
Als ersten Schritt initialisieren Sie bitte das Projekt, indem Sei einmal
das Programm mkdocs-library aus dem Projektverzeichnis heraus aufrufen:
cd ~/pfad/zu/glarean-books
mkdocs-library
Nun stehen Ihnen die Dateien zur Verfügung, in denen Sie die einzelnen Seiten bearbeiten können, und Sie können den Ausgangszustand der Anleitungen in einem beliebigen Webbrowser ansehen.
Ansicht der Seite¶
Die Anleitungen werden im Verzeichnis site des Projektverzeichnisses erzeugt,
und als Einstiegsseite kann die Datei site/index.html in jedem Browser
geöffnet werden.
Wenn Sie eine Datei verändert und gespeichert haben, können Sie mkdocs-library
erneut aufrufen, um die erzeugte Webseite zu aktualisieren.
Bearbeiten existierender Seiten¶
Jede Seite der Anleitungen befindet sich in einer Markdown-Datei mit der
Dateierweiterung .md. Diese finden Sie unterhalb des Verzeichnisses
books/<teilbuch>/docs gespeichert. Der Ort innerhalb dieser
Verzeichnisstruktur entspricht dabei dem Pfad in der Adresszeile des Browsers.
Hinweis
Die Zuordnung von Navigationstiteln zu Quelldateien ist in den Dateien
books/<teilbuch>/_config/navigation.yml definiert, der die zu bearbeitende
.md-Datei für die Bearbeitung einer Seite zu entnehmen ist.
mkdocs serve¶
Server mit Live-Reload¶
Wenn Sie vorhaben, nur Seiten innerhalb eines der Teilbücher zu bearbeiten und keine Veränderungen an der Navigationsstruktur vorzunehmen, können Sie auch den praktischen Servermodus von MkDocs nutzen.
Nachdem Sie einmal die Website manuell mit mkdocs-library erzeugt haben, können Sie mit
cd books/<teilbuch>
mkdocs serve
in das Teilbuch wechseln und den »Live-Reload-Modus« starten. Nun können Sie im
Browser die Seite localhost:8000 aufrufen. Sobald nun eine Quelldatei
verändert gespeichert wurde, wird das Teilbuch automatisch neu erzeugt und
direkt im Browser aktualisiert.
Achtung
Das Teil-/Haupt-Buch der »Einführung« ist im Verzeichnis
books/main gespeichert, neben den eigentlichen Unter-Büchern.
Dies ist eine Eigenheit von mkdocs-library.
Einschränkungen des Live-Reload-Servers¶
Beachten Sie bitte folgende Einschränkungen:
- Änderungen an der Navigationsstruktur werden nicht automatisch
berücksichtigt.
- Nach Änderungen an Dateien im
_config-Unterverzeichnis des Projektes oder eines Teilbuchs mussmkdocs-libraryerneut ausgeführt werden, um die Struktur zu aktualisieren. - Dies kann jedoch in einem separaten Terminal erfolgen, während der Server läuft. Die dadurch veränderten Dateien werden i.d.R. automatisch bemerkt.
- Nach Änderungen an Dateien im
- Links zwischen Teilbüchern funktionieren nicht, da das gerade ausgelieferte Teilbuch als »oberste Ebene« betrachtet wird.
Upload¶
Die Veröffentlichung geänderter Dateien auf https://glarean.mh-freiburg.de/anleitungen erfolgt durch Pushen der erzeugten HTML-Site auf ein Repository auf dem Hochschul-Git-Server. Alle fünf Minuten wird der Stand dieses Repositorys überprüft und automatisch auf den Webserver übertragen.
Achtung
Die echte Website können Sie natürlich nur verändern, wenn Sie zuvor von den Administratoren die entsprechenden Zugriffsrechte erhalten haben
Dieser Vorgang ist automatisiert durch das Skript deploy, das sich im
Hauptverzeichnis des Anleitungen-Repositorys befindet. Es kann entweder - ohne
Optionen - durch ./deploy aufgerufen werden oder mit dem Befehl
mkdocs-library --recipe all
automatisch im direkten Anschluss an den Build ausgeführt werden.
Achtung
Das Skript fordert Sie im Verlauf der Ausführung zur Eingabe Ihrer Zugangsdaten für den Git-Server auf. Diese entsprechen Ihrem Hochschulaccount.