Installation von MkDocs

Diese Site benutzt MkDocs mit dem Material -Design für die Seitengestaltung. Nachfolgend wird kurz zusammengefasst, wie dieses Tool für die vorliegende Anwendung konfiguriert wurde.

Die Installation der Packages erfolgt mithilfe von Python und Pip. Zur Eingabe der zugehörigen Kommandozeilen-Befehle ist das Terminal als Administrator zu öffnen. Weitere Details sind im MkDocs Installation Guide zu finden.

Installation von Python

MkDocs benötigt Python. Sofern noch nicht vorhanden, muss dieses von der Python Homepage heruntergeladen und installiert werden. Die aktuelle Python-Version enthält auch bereits den Package Manager Pip. Dies kann bei Auswahl der Customize-Option im Installationsdialog geprüft werden. Hier besteht auch die Möglichkeit, Python für alle Benutzer des PCs zu installieren und das Installationsverzeichnis auszuwählen.

Mit dem nachfolgenden Kommandozeilen-Befehl, wird der Package Manager auf Aktualität geprüft und ggf. upgedatet.

pip install --upgrade pip

Installation des MkDocs-Pakets

Die Installation von MkDocs erfolgt mittels des folgenden Befehls:

pip install mkdocs

Installation des Material-Themes für MkDocs

Die Installation von Material für MkDocs erfolgt ebenfalls mit Pip. Details hierzu gibt es im Getting Started.

pip install mkdocs-material

Konfiguration einer Site mit MkDocs und Material

Durch Aufruf von mkdocs mit dem Parameter "new" wird ein Verzeichnis für die Aufnahme der Quell- und Konfigurationsdateien einer neuen Website vorbereitet.

mkdocs new test.dir

In dem obigen Beispiel wird ein Verzeichnis "test.dir" erzeugt, in dem sich eine Datei "mkdocs.yml" und ein Unterverzeichnis "doc" befinden.

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        22.12.2021     10:32                docs
-a----        22.12.2021     09:12            763 mkdocs.yml

Die Datei "mkdocs.yml" wird durch ein gleichnamiges File mit nachfolgendem Inhalt ersetzt, welches bereits die Verwendung von Icons und Latex-Formeln erlaubt. In diesem File sind "site_name" und der "nav:"-Bereich an die jeweilige Site anzupassen.

site_name: Netzler Site
use_directory_urls: false
nav:
    - index.md
    - mkdocs/mkdocs.md
    - Administration:
        - legal/imprint.md
extra_css:
    - _config/extra.css
markdown_extensions:
    - admonition
    - pymdownx.superfences
    - pymdownx.details
    - attr_list
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
    - pymdownx.arithmatex:
        generic: true
extra_javascript:
    - _config/config.js
    - https://polyfill.io/v3/polyfill.min.js?features=es6
    - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
theme: 
    name: material
    language: de
    font: false
    favicon: pics/dirkfavicon.png
    logo: pics/dirklogo.png

Ferner sind die Bilder für das "favicon" und das "logo" durch eigene zu ersetzen. Das Logo ist eine Bilddatei, hier mit ca. 300x300 Pixeln, und findet sich als Bild-Icon oben links auf der Seite wieder. Das Favicon ist üblicherweise die verkleinerte Version des Logos in einer Größe von rund 32 x 32 Pixeln.

Die Bilder sowie alle weiteren Quell- und Konfigurationsdateien werden im "docs"-Ordner abgelegt. In der obigen Konfiguration wird folgende Struktur vorausgesetzt.

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        22.12.2021     10:31                _config
d-----        22.12.2021     09:03                legal
d-----        22.12.2021     09:11                mkdocs
d-----        22.12.2021     09:01                pics
-a----        22.12.2021     10:17            476 index.md

Die Datei "index.md" beschreibt die Titel- bzw. Einstiegsseite der Site.

Logo und Favicon befinden sich im Ordner "pics".

Das Verzeichnis "_config" enthält Konfigurationsdateien. Die Datei "extra.css" ermöglicht individuelle Anpassungen des Seitenstils. Im angegebenen Beispiel wird lediglich die Farbe des Titelbalkens verändert.

:root {
    --md-primary-fg-color:#329;
}

Die zweite Datei "config.js" enthält Definitionen für die Erzeugung und Darstellung von Latex-Formeln.

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

Editieren einer Site

Zum Editieren einer Seite wird in der Konsole in dem Verzeichnis der Site, in dem sich "mkdocs.yml" befindet (im obigen Beispiel der Ordner "test.dir") folgender Befehl aufgerufen:

mkdocs serve

Der aktuelle Stand der Site kann dann im Browser unter folgender Adresse betrachtet werden:

http:\\127.0.0.1:8000

Werden in "mkdocs.yml" oder in den Markdown-Files (.md) der Site Änderungen vorgenommen, werden diese direkt umgesetzt und können im Browser begutachtet werden.

Mit nachfolgendem Befehl

mkdocs build

wird die gesamte Website als statische Website generiert und im parallel zu "docs" liegenden Ordner "site" abgelegt. Zur Veröffentlichung ist der gesamte Inhalt von "site" auf den Webserver zu kopieren.

Einige Icons

Einige Icons:

:material-gesture-tap-hold:
:material-arrow-right:
:material-arrow-left:
:material-account-circle:
:fontawesome-regular-laugh-wink:
:fontawesome-regular-laugh:
:fontawesome-regular-comment:
:octicons-heart-fill-24:

Highlight-Felder

(Admonitions) für das Hervorheben von Text und Aussagen.

!!! info

Zusätzlicher Text wird in der nachfolgenden Zeile eingerückt

!!! info "Titeltext"
    Zusätzlicher Text ...

!!! note

!!! abstract

!!! tip

!!! success

!!! question

!!! warning

!!! failure

!!! danger

!!! bug

!!! example

!!! quote