Mkdocs

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

Installation

apt install mkdocs mkdocs-material

Projekt erstellen

Eine 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, 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.

Mittels "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 automatisch die Links für die Navigation, sodass man direkt los schreiben kann. Möchte man allerdings die Reihenfolge der Items ändern, kann man diese explizit in der mkdocs.yml definieren. Eine Navigation lässt sich in dieser Art umsetzen:

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 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 doc/
vi übersicht.md

Vgl. Markdownguide

Praktisch ist, dass man mittels des Befehls

mkdocs serve

Einen Addhoc-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: Unter "site" sind die Dateien, die der Befehl

mkdocs build

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