MkDocs - Webseiten einfach generieren (in Arbeit)

Vor- und Nachteile

Ich habe MkDocs für meinen Blog entdeckt, das im Gegensatz zu Tiddlywiki schöner aussieht, sich einfacher bedienen lässt und auch auf einem Handy sehr gut dargestellt wird. Sicher ist das ganze auch noch, den die Artikel werden mit der Umschreibungssprache markdown in einzelnen Dateien verfasst und anschließend in HTML konvertiert. Der Vorteil hierbei ist, das ein statisches HTML dabei herauskommt und der Seitenaufbau dadurch sehr schnell ist. Ebenfalls bietet es keine Angriffsfläche für Hacker. Auch das Googleranking wird dadurch viel besser, da die Suchmaschine die Seite endlich indexieren kann, was bei Tiddlywiki überhaupt nicht möglich war. Auch das schelle laden der Seite kommt dem Ranking zu gute. MkDocs kommt ebenfalls ohne PHP aus, was für mich eine wichtige Entscheidungsgrundlage war.

Leider fehlen hier die Möglichkeit unterwegs Artikel zu verfassen und auch ein Kommentieren ist leider nicht möglich. Durch das fehlen einer Datenbank, kann kein dynamisch generierter Inhalt erzeugt werden.

Vorrausetzungen

MkDocs wurde in Python programmiert und ist somit auf allen Betriebssystemen lauffähig. Es werden die Versionen 2.7, 3.3, 3.4, 3.5 und pypy unterstützt. Da Python auf allen Linuxsystemen meist vorinstalliert ist, ist die Installation dort besonders einfach.

Installation

MkDocs kann auf einem Debian basierten Linuxsystem sehr einfach installiert werden. Ich gehe hier davon aus, das Python bereits installiert ist. Mit dem Befehl python --version lässt sich anzeigen, ob eine passende Version vorhanden ist. Sollte das nicht der Fall sein, kann dies mit sudo apt install python nachgeholt werden.

Für die Installation ist folgendermaßen vorzugehen:

          sudo apt install python-pip
          sudo pip install --upgrade pip
          sudo pip install setuptools
          sudo pip install mkdocs

Neue Webseite erstellen

In der Konsole kann nun mit MkDocs eine neue Seite angelegt werden. Hierzu navigieren wir mittels cd zu einem Verzeichnis, in dem wir unser Projekt speichern möchten. Dort wird mit mkdocs new <Projektname> unsere neue Webseite angelegt. Anschließend wechseln wir mittels cd <Projektname> in das Verzeichnis. Wer möchte kann zusätzlich noch ein Theme installieren. Viele Themes lassen sich per pip installieren wie im nachstehenden Beispiel Cinder.

          pip install mkdocs-cinder
          pip install --upgrade mkdocs-cinder

Man kann auch sein eigenes Theme erstellen. Wie das im einzelnen funktioniert, lest am besten auf der orgiginalen Dokumentation nach.

Ohne Theme unser Verzeichnis folgenden Aufbau haben:

          .
          ├── docs
          │   └── index.md
          └── mkdocs.yml

Entwurf live ansehen

Mit cd <Projektname> wechseln wir in das Projekt-Verzeichnis und stareten mit mkdocs serve den Webserver der Entwicklungsumgebung. Dieser stellt die erstelle Webseite jetzt live zur Verfügung und Änderungen im Projekt werden sofort dargestellt. Um das Ergebnis ansehen zu können, starten wir einen Webbrowser und rufen die Seite http://127.0.0.1:8000 auf.

Änderungen am Projekt werden im Browser direkt dargestellt und der refesh erfolgt automatisch sobald das notwendig ist, so das man sich sehr gut auf die eigendliche Arbeit konzentiern kann. MkDocs

Allerdings kann der Server mit einem Fehler abbrechen, wenn z.B. eine Seite dargestellt werden soll, die noch gar nicht existiert. In diesem fall einfach den Server mit Strg + c abbrechen, den Fehler korrigieren und den server nochmals mit mkdocs servestrten.

Bald gehts weiter ...