Pelican unter Debian Wheezy nutzen -- Teil-2

Im zweiten Teil meiner kleinen Serie über Pelican wird ein erstes Blog erstellt. Dieses Beispiel wird dann mit Leben gefüllt und sukzessive erweitert werden. Alle diese Stufen werden auf Github archiviert.

Wie alles beginnt

Der erste Teil gab einen Überblick über die Installation von Pelican und die virtuelle Umgebung, die mit virtualenv realisiert wurde. Ich hatte angedeutet, dass man mit pelican-quickstart ein erstes Gerüst eines Blogs erzeugt. Das möchte ich nun im Folgenden vertiefen.

Will man die Umgebung betreten oder verlassen, dann macht man das mit den folgenden Befehlen. Hierbei kann man nach dem workon die Autovervollständigung der Shell nutzen.

$ workon blog-tests
(blog-tests) $ ...
(blog-tests) $ deactivate
$ ...

Wie man sieht, verändert sich der Prompt der Arbeitsshell. Der Name der virtuellen Umgebung erscheint in runden Klammern vor dem eigentlichen Prompt.

Das Erstellen eines Gerüstes mit pelican-quickstart ist denkbar einfach. Man erzeugt ein leeres Verzeichnis und wechselt hinein. Danach wird einfach pelican-quickstart aufgerufen. Dieses Script erfragt alle notwendigen Daten. In unserem Fall habe ich auf einen URL-Prefix verzichtet, damit wir später mit einem lokalen http-Server das Blog testen können, ohne das wir es gleich online stellen müssen (der Punkt "auto-reload & simpleHTTP"). Das ist sehr praktisch. Als Upload-Möglichkeit habe ich SSH festgelegt. Da ich noch keinen Server eintragen kann, habe ich einfach localhost und Benutzer root gewählt. Das lässt sich später problemlos anpassen.

$ workon blog-tests
(blog-tests)$ mkdir test-blog
(blog-tests)$ cd test-blog
(blog-tests)$ pelican-quickstart

Welcome to pelican-quickstart v3.4.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

Using project associated with current virtual environment.Will save to:
/home/.../blog-tests/test-blog

> What will be the title of this web site? A Sample Pelican Blog
> Who will be the author of this web site? John Doo
> What will be the default language of this web site? [en] en
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10] 10
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) y
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) y
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) y
> What is the hostname of your SSH server? [localhost] localhost
> What is the port of your SSH server? [22] 22
> What is your username on that server? [root] root
> Where do you want to put your web site on that server? [/var/www] /var/www
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) n
> Do you want to upload your website using GitHub Pages? (y/N) n
Done. Your new project is available at /home/.../blog-tests/test-blog

Nach dem Erstellen bekommt man folgenden Inhalt im Verzeichnis präsentiert:

content/
output/
develop_server.sh
fabfile.py
Makefile
pelicanconf.py
publishconf.py

Das Verzeichnis content nimmt unsere Markdown Dateien mit dem eigentlichen Inhalt auf. In output wird der komplette Inhalt der Website erzeugt. Das Shell-Script develop_server.sh dient zum Starten und Stoppen eines kleinen lokal arbeitenden HTTP-Servers, mit dem sich das Block lokal testen lässt. Die beiden Python-Dateien *conf.py enthalten die Konfiguration des Blogs und des Uploads. Der gesamte Prozess des Erzeugens der Website und des Hochladens auf den Server kann mit GNU-Make gesteuert werden. Alle notwendigen Daten finden sich in dem generierten Makefile. Auf die Verwendung der Datei fabfile.py gehe ich nicht weiter ein. Sie kann eigentlich gelöscht werden, stört aber auch nicht.

Wie man zu seinem Inhalt kommt

Noch haben wir keinen Inhalt. Wer jetzt neugierig ist, der kann schon mal versuchen, was beim Erzeugen der HTML-Ausgabe passiert.

(blog-tests)$ make html
pelican /home/.../blog-tests/test-blog/content -o /home/.../blog-tests/test-blog/output -s /home/.../blog-tests/test-blog/pelicanconf.py
WARNING: Feeds generated without SITEURL set properly may not be valid
WARNING: No valid files found in content.
Done: Processed 0 article(s), 0 draft(s) and 0 page(s) in 0.11 seconds.

Nach dem Aufruf von make mit dem Ziel html startet Pelican mit der Erzeugung unseres Blog. Hier kommt es aber zu zwei Warnungen. Die Erste liegt darin begründet, dann wir keine URL für unser Blog konfiguriert haben. Das lösen wir aber später. Die zweite Warnung hätten wird uns eigentlich schon denken können. Wir haben noch keinen Inhalt.

Ein Blick ins Verzeichnis zeigt, dass Pelican ein weiteres Unterverzeichnis mit Namen cache angelegt hat. Dies ist ein Verzeichnis für temporäre Daten und braucht uns nicht weiter zu interessieren. In output hat sich aber einiges getan. Pelican hat einige Dateien angelegt, und ein Verzeichnis output/theme mit einem Standard-Theme erzeugt.

Der erste Artikel

Nun ist es Zeit den ersten Artikel zu erstellen. Hierzu müssen wir eine Textdatei anlegen, die als Kopf einige vordefinierte Metadaten besitzt. Im Falle von Markdown-Texten müssen diese aus groß geschriebenen Schlüsselworten bestehen, die durch einen Doppelpunkt vom Wert getrennt sind. Pelican nutzt diese Metadaten für die Generierung und interne Verwaltung. Nach dem Kopf folgt der eigentliche Text mit Markdown-Formatierungen.

Die Datei muss im Unterverzeichnis content mit der Endung .md angelegt werden. Der sinnvollen Sortierung wegen beginne ich jeden Dateinamen mit dem Prefix aus Jahr-Monat-Tag! In diesem Beispiel wähle ich den Namen 2014-09-21-beispiel.md.

Hinweis: Der Titel des Textes wird immer als Überschrift der Ebene 1 generiert. Interne Überschriften sollten deswegen erst ab Ebene 2 genutzt werden.

Title: Ein Beispiel für einen Artikel
Date: 2014-09-21 15:20

## Unser erstes Kapitel

Hier kommt nun der  *unfertige*, *beispielhafte* Inhalt.

Die zuvor erwähnten Metadaten beschränken sich in dem Beispiel auf das Minimum. Mit Title: wird der eigentlich Titel des Artikels definiert. Dieser erscheint dann auch auf der Hauptseite als Überschrift für den Artikel. Durch Date: wird das Datum des Artikels angegeben. Es sollte nach internationaler Schreibweise als Jahr-Monat-Tag angegeben werden. Die Uhrzeit ist optional. Pelican erkennt aber auch andere Formate.

Nach dem Kopf kommt der eigentlich Artikel. Hier ist natürlich erst einmal nichts wesentlichen enthalten.

Ein beherztes make html in der Arbeitsshell erzeugt das Blog. Die Ausgabe sieht dann wie folgt aus:

Der erste Artikel im Blog

Was sieht man hier?

Neben dem Titel und der Menüzeile sieht man unseren ersten Artikel in der Zusammenfassung. Das Standard-Theme zeigt die Artikelinformationen (Datum, Autor) rechts an. Man sieht sofort, dass im Menü als auch in der Zusammenfassung der Begriff misc auftaucht. Das ist die Vorgabekategorie die Pelican vergibt, wenn man in den Metadaten nichts angibt.

Man kann in den Metadaten durch das Schlüsselwort Category: eine eigene Kategorie angeben. Jede Kategorie erscheint dann als eigener Menüpunkt. Das ist so schon ziemlich praktisch, da man für eine Gruppierung nichts mehr spezielles konfigurieren muss.

Kategorien und andere Gruppen

Der Weg Artikel über Kategorien zu gruppieren ist sehr einfach und angenehm. Allerdings muss man auch aufpassen, dass man es nicht übertreibt und so das Menü "zumüllt".

Neben den Metadaten kann man auch auf einem anderen Weg Kategorien erzeugen. Legt man im Verzeichnis content weitere Unterverzeichnisse an, dann nutzt Pelican diese automatisch als Kategorie. Alle Dateien, die in diesem Verzeichnis liegen, werden in die gleichnamige Kategorie einsortiert.

Hierbei gibt es aber Einschränkungen. Pelican kennt spezielle Verzeichnisse, deren Inhalt eine andere Behandlung erfährt. Dies wären zum Beispiel pages, extras und images. Daten in den letzten beiden Verzeichnisses werden einfach in das Ausgabeverzeichnis output kopiert, ohne dass die Dateien irgendwie verarbeitet werden. In extras kann man zum Beispiel eine eigene Robots.txt ablegen.

Im Verzeichnis pages hingegen kann man Markdown-Dateien speichern, die dann nach HTML konvertiert werden. Das besondere hierbei ist, dass die Titel der Seiten ebenfalls im Menü erscheinen. Diese Seiten tauchen dafür aber nicht in der Zusammenfassung der Artikel auf.

Seiten in pages sind sogenannte "statische Seiten". Hier kann man Seiten wie eine "Über mich" Seite oder das Impressum ablegen.

Legt man diese beiden Dateien in pages an und fügt in den ersten Beispielartikel eine Kategorie "Test" in die Metadaten ein, dann sieht unser Blog im zweiten Schritt leicht anders aus:

Das Blog mit statischen Seiten

Was hat sich verändert?

Man sieht nun die beiden neuen Menüeinträge "Über mich" und "Impressum". Dies sind die Titel der statischen Seiten unter pages. Dann ist misc verschwunden und es erscheint wie angedroht Test als Resultat der geänderten Kategorie. All Änderungen und Seiten findet ihr auf Github.

Vorschau

Im dritten Teil werde ich auf Tags (Englisch für "Etiketten") als Alternative für die Kategorien eingehen. Des weiteren werde ich euch zeigen, wie man mit dem lokalen hhtp-Server von Pelican wunderbar einfach sein Blog testen kann. Des weiteren werden wir die Konfigurationsdatei ändern um das Blog in Deutsch erscheinen zu lassen.

Das war es für heute.

Comments