Mkdocs

Zur Erstellung dieser Website wird mkdocs verwendet. Vorkenntnisse in der Sprache Markdown sind von Vorteil.

Installation

apt install mkdocs mkdocs-material

Projekt erstellen

Ein neues Projekt erstellt man z. B. mit:

mkdocs new mathispaffrath.de

Es wird ein neuer Projekt-Ordner erstellt, in dem sich eine mkdocs.yml-Datei befindet. In ihr wird die hauptsächliche Konfiguration vorgenommen. Um beispielsweise das Theme, also das Aussehen der Website, zu verändern, werden für diese Seite folgende Einstellungen vorgenommen:

$ cat mkdocs.yml 

site_name: mathispaffrath.de

theme:
  language: de
  name: material 
  palette:
    primary: teal

Der language-Parameter sorgt dafür, dass einzelne Elemente der Website, z. B. Pfeile zur Navigation, nicht mit "Next" sondern mit "Weiter" betitelt werden.

Durch "name: material" wird das Design vom MkDocs-Standard-Theme auf das Theme von mkdocs-material umgestellt.

In der Sektion "palette" kann die Farbgebung verändert werden. Neben "teal", einem blaugrünen Farbton, gibt es noch red, pink, purple, indigo und viele weitere... (vgl. hier).

Das Projekt erstellt die Navigationslinks automatisch, sodass man direkt losschreiben kann. Möchte man allerdings die Reihenfolge der Items ändern, kann man diese explizit in der mkdocs.yml definieren. Die Navigation kann folgendermaßen definiert werden:

site_name: mathispaffrath.de

theme:
  language: de
  name: material

nav:
  - Home: 'index.md'
  - Kontakt: 'kontakt.md'
  - Texte: 
    - 'texte/übersicht.md'
    - Linux: 
      - 'texte/linux/mkdocs.md'

Vermutlich wird sich die Sortierung noch ändern, doch gewinnt man einen Eindruck, wie die Navigation eingestellt werden kann.

Ordnerstruktur

Das Projekt kann von da an wachsen.

/mathispaffrath.de/
├── docs
│   ├── img
│   │   └── bee.jpg
│   ├── index.md
│   ├── kontakt.md
│   └── texte
│       ├── mkdocs.md
│       └── übersicht.md
├── mkdocs.yml
├── nextcloud
└── site

Erstellen von Inhalten und Schreiben

Eine neue Seite erstellt man einfach, indem man eine Markdown-Datei erzeugt und mit Inhalt füllt, z.B.:

cd docs/
vi übersicht.md

Vgl. Markdownguide

Praktisch ist, dass man mittels des Befehls

mkdocs serve

Einen Ad-hoc-Server starten kann, der die Website darstellt. So kann der Inhalt der Markdown-Datei im Browser betrachtet werden, sobald die Datei gespeichert wird.

Publizieren

Hinweis: Im Ordner "site" sind die Dateien, die der Befehl

mkdocs build

erstellt. Der Inhalt dieses Ordners muss dann auf den Webserver geladen werden.