OpenGATE Retro Blog Retro-Logo

Jekyll Blog Setup


Diese Seite wurde mit der Software Jekyll erstellt.

Jekyll sammelt in Markdown geschriebene Dateien ein und generiert daraus gemeinsam mit einem Design-Paket eine vollständige statische Webseite (also reine HTML Dateien). Diese Dateien überträgt man dann auf seinen Webspace und kann sich sicher sein, dass es keine Einfalltore für Hacker gibt, so wie bei anderen online CMS Systemen.

Das Abenteuer Jekyll Setup möchte ich hiermit dokumentieren, denn spätestens wenn es zur die Installation und Anpassung von Themes kommt, wird es nicht mehr ganz so unkompliziert.

Meine Umgebung sieht so aus:

  • Windows 10 Pro 64 bit
    • Keine Sorge, es klappt auch mit einer Home Edition
  • Ubuntu Linux 18.04 installiert mittels Windows 10 Subsystem für Linux (WSL)
    • Dafür muss man unter Systemsteuerungen, Programme und Features unter Windows Features aktivieren oder deaktivieren den Eintrag Windows-Subsystem für Linux aktivieren (und eventuell neu starten).
    • Danach sucht man im Windows App Store nach Ubuntu und installiert es.
    • Im Startmenü findet man dann Ubuntu, das sich beim ersten Starten auf dem System einrichtet, einen Linux-User samt Passwort verlangt und am Ende hat man ein kleines Linux unter Windows am Laufen.

In der Linux Umgebung sind unter /mnt/c und /mnt/d usw. alle Windows Laufwerke verfügbar. Man kann somit seine Webseiten-Dateien irgend wo im Windows-Dateisystem ablegen und dann von der Linux/Ubuntu Umgebung darauf zugreifen.

Mein Motto: Windows editiert, Linux generiert

Eines gleich vorweg: Jekyll alleine reicht für das absolute Minimum eines Blogs, jedoch benötigen die meisten schöneren Designes und Themes zusätzliche Features und diese erhalten sie durch gem, einer auf der Programmiersprache Ruby basierenden Paketverwaltungs-Komponente.

Achtung! Die direkte Installation von jekyll und gem über Ubuntu’s apt-get führte bei mir (und laut Netz auch bei anderen) zu Fehlern.
Daher sollte man NUR ruby per apt-get installieren. ruby beinhaltet das Tool gem und mittels diesem wird dann bundler (ein weiteres gem tool) und letztendlich jekyll installiert.

Hinweis: Ich wechsle für Installationen gerne direkt zum root account, wer das nicht will, muss vor den apt-get Zeilen immer noch ein sudo setzen. Bei gem und bundler kann man das auch tun, obwohl diese Tools selbständig nach dem Root-Passwort fragen, wenn es fehlt.

  • apt-get update: Kann nicht schaden, dass man zuerst mal die Paketlisten aktualisiert
  • apt-get install build-essential: installiert Tools wie GCC und co, damit andere Module erzeugt werden können
  • apt-get install ruby: installiert ruby und seine Tools
  • apt-get install ruby-dev: installiert Quellcodes für die ruby Entwicklung und Erweiterung
  • apt-get install zlib1g-dev: installiert die Bibliothek zlib-eins-G. Bei mir war das notwendig, damit für mein Designpaket ein anderes Modul namens nokogiri installiert werden kann. Ich habe diesen Schritt ursprünglich nicht durchgeführt, womit einer der nachfolgenden Befehle abgebrochen wird, und zwar mit dem Verweis, dass zlib fehlt.
    Wer andere Designs einsetzt, kann unter Umständen auf ähnliche Probleme mit anderen Bibliotheken stoßen und muss diese nachinstallieren.
  • gem install bundler: Bundler hilft uns notwendige Zusatzmodule für jekyll zu installieren und zu nutzen.
  • gem install jekyll: Nun installieren wir noch jekyll auf dem System.
  • Bei einer weiteren Installation war bei mir noch das Kommando
    gem update --system nötig, da bundler sich mit dem Softwarestand noch nicht nutzen ließ.

Die wichtigsten Tools sind nun installiert.

Nun kann man sich eines der fertigen Seiten-Designs herunterladen. jekyllthemes.org wäre eine mögliche Quelle, aber die Suchmaschine des Vertrauens findet bestimmt noch weitere.

In der Regel kopiert man sich so ein Theme/Design Paket einfach in ein Unterverzeichnis, bzw. man klont es sich direkt aus einem GIT Repository, denn die meisten Themes sind irgendwo auf github.com abgelegt.

Nun wechselt man in eben dieses Verzeichnis und:

  • führt bundler install aus. Denn dort befindet sich eine Datei namens _config.yml, die die wichtigsten Einstellungen der Seite beinhaltet. Darunter auch eine Liste aller erforderlichen Plugins, die bundler für uns herunterlädt und installiert. Falls bundler Probleme meldet, hilft oft das Kommando bundle update --bundler um die Software zu aktualisieren.
  • Werden später Plugins der Seite geändert, sollte immer bundler update nochmals im Seiten-Verzeichnis aufgerufen werden.

Das wär’s dann. Jetzt darf man sich in Jekyll einlesen.

Falls das Theme/Design Paket fehlerfrei ist (bei mir war Nacharbeit leider notwendig), kann man die neue Seite sofort testen:

Wird bundler exec jekyll serve im Seitenverzeichnis ausgeführt, fährt ein Test-Webserver auf Port 4000 hoch und man kann sofort im Browser zur Seite http://127.0.0.1:4000/ wechseln, wo die generierte Seite angezeigt wird.

Hinweis: Wenn man unter Windows 10 mit den Services for Linux bundler auf einem /mnt/* Pfad arbeitet, hat man als normaler Benutzer keine Rechte um Dateiattribute zu verändern. bundler schlägt dann mit dem Fehler EPERM fehl. Da hilft dann sudo bundler exec jekyll serve um die nötigen Adminrechte für alle Operationen zu bekommen.

Manche Seiten sind für ein Unterverzeichnis konfiguriert (in _config.yml), und dann muss man diesen Pfad natürlich auch angeben.
z.B. blog findet man dann unter http://127.0.0.1:4000/blog/
(Der finale Slash am Ende kann manchmal zwingend notwendig sein.)

Wie die Seite jetzt genau aufgebaut ist, hängt natürlich vom eingesetzten Theme ab. Aber grundsätzlich gilt:

  • /path/to/page/_posts beinhaltet die Markdown Files einzelner Blog Beiträge, wobei Datum und Titel im Dateinamen kodiert sein sollten.
    • z.B. /_posts/2018-12-24-my-christmas-adventure.md
    • Innerhalb der Markdown Datei gibt es einen Header, der in etwa so aussieht 
      1 ---  
2 layout: post  
3 title:  "My christmas adventure"  
4 date:   2018-12-24 20:15:00 +0100  
5 categories: [event, adventure]  
6 ---

      Dieser Datensatz hilft bei der Generierung eines schönen Eintrags auf der Übersicht-Seite.

  • /path/to/page/_pages enthält zusätzliche Webseiten, die keine posts sind
  • /path/to/page/_layouts und /path/to/page/_includes enthalten die HTML Teildateien, aus denen das Design der Seite zusammengebaut wird.
  • Und dann gibt es noch Zusatzverzeichnisse für CSS- und Javascript-Dateien. Oft findet man die in /path/to/page/assets

Und wenn man seine Seite fertig gestellt hat, ruft man einfach
bundler exec jekyll build im Seitenverzeichnis auf. Dann findet man alle generierten HTML (und sonstigen) Dateien im Unterverzeichnis /path/to/page/_site.

In der Regel kann man den Inhalt von _site direkt auf seinen Webspace übertragen. Natürlich vorausgesetzt, dass die Einstellungen über Pfade und Domainnamen in der _config.yml auch mit dem Webspace zusammenpassen.

Zwei wichtige Zusatzkommandos, möchte ich noch erwähnen:
bundler exec jekyll serve --future und
bundler exec jekyll build --future
Diese starten den Test-Server bzw. generieren die Seite mit wirklich allen Postings. Denn ohne --future werden nur jene Posts generiert, die in der Vergangenheit liegen.

Ich schreibe ja gelegentlich das Thema von morgen schon heute und will das Ergebnis sofort begutachten.

Gut, das wars fürs Erste. Richtig spannend wird jekyll, wenn man sich mit seinen internen Schleifen und Funkionen neue Features bastelt … aber das führt hier zu weit, davon abgesehen bin ich da auch kein Experte, sondern spiele einfach so lange damit herum, bis vernünftige Resultate vorliegen.

Alles weitere findet man auf jekyllrb.com