Mein Start mit Jekyll
Ich habe mich - siehe Webseite und Software - für Jekyll als Basis für mein Blog entschieden. Neben der Einrichtung und Bedienung beschreibe ich hier auch meine ersten Änderungen und Anpassungen an der Basis-Konfiguration.
Installation
Für die Installation unter OSX auf dem Mac folgte ich der Installationsanleitung. Sie funktionierte bis auf ein kleines Problem ohne Schwierigkeiten. Leider will Jekyll oder eine der Basis-Komponenten davon auch während der Benutzung Schreibrechte auf dem Ruby-Verzeichnis. Mein normales Benutzer-Konto hatte nur Lese-Rechte; schweren Herzens - ich bin gerne sparsam mit Schreibrechten für dieses Konto - habe ich das ändern müssen.
Einstieg
Der Einstieg war wie gewünscht einfach. Dabei haben mir neben der Dokumentation zum Schnellstart auf der Jekyll-Homepage auch die Tutorial-Videos von Mike Dane auf YouTube geholfen. Durch die Videos bin ich auch auf die Idee gekommen, den Atom-Editor für die Pflege des Blogs zu benutzen. Im Rahmen der Installation bekommt man auch das Gerüst für eine Webseite, die man nur noch mit eigenen Inhalten füllen muss.
Bedienung
Die Bedienung von Jekyll erfolgt über die Kommandozeile. Wesentlich sind für mich folgende Befehle:
Neues Webseiten-Projekt
Um das Gerüst eines neuen Webseite-Projekts mit dem Namen “Beispiel” zu erzeugen: jekyll new beispiel
Webseite generieren und lokalen Webserver starten
Jekyll erzeugt mit jekyll serve aus den Dateien des Projekts eine fertige Webseite und startet auch gleich einen lokalen Webserver. Danach kann man sie sich unter localhost:4000 ansehen. Um die Webseite zu veröffentlichen, kopiere ich dann den Inhalt des Unterordners _site in das entsprechende Verzeichnis auf dem Server meines Webhosters.
Wenn man Posts vorbereiten, aber noch nicht veröffentlichen will, legt man den Unterordner _drafts an. Dort hinein kommen die Posts, die noch in Arbeit sind. In diesem Fall benutzt man jekyll serve --drafts um die Webseite zu generieren und anzuzeigen.
Fehlermeldungen
Durch den Befehl jekyll new beispiel kann es dazu kommen, daß einige Komponenten von Jekyll aktualisiert werden, und andere Jekyll-Projekte plötzlich Fehlermeldungen folgender Art erzeugen:
You have already activated xyz 3.4.1, but your Gemfile requires xyz 3.3.3.
Dies läßt sich durch den Befehl bundle update xyz lösen.
Nach dem Update auf OSX 12 “Monterey” hatte ich plötzlich Probleme, Jekyll zu starten. Teil der Lösung war, die “Developer Tools” neu zu installieren bzw. die Xcode-Lizenz für die Command-Line-Tools abzunicken:
Developer-Tools doppelt installieren: xcode-select --install und xcode-select -s /Applications/Xcode.app/Contents/Developer. Danach für das Akzeptieren der Lizenzbedingungen: Erst xcode-select --switch /Library/Developer/CommandLineTools, gefolgt von: xcodebuild -license.
Struktur der Webseite - Permalinks
Zur Zeit ist die Webseite komplett auf Deutsch. Eventuell biete ich aber später auch eine englische Variante an. Oder packe neben den Blog noch andere Infos. Deshalb habe ich bis auf die Homepage alles under /de gepackt, und die Blog-Seiten dann unter de/blog. Ein einfacher Weg dazu sind die Permalinks, die Jekyll anbietet. Impressum- und Datenschutz-Seiten haben in ihrem “Front Matter” den Eintrag permalink: /de/impressum/ bzw. permalink: /de/datenschutz/.
Der Permalink für die Blog-Einträge wird durch einen Eintrag in config.yaml festgelegt - siehe Global permalinks:
permalink: /de/blog/:year/:month/:day/:title:output_ext
Auszüge
In der Standard-Installation erscheinen auf der Homepage des Blogs nur die Titel der Blogposts. Möchte man auch den ersten Abschnitt der Posts anzeigen lassen, ist ein Eintrag in _config.yaml erforderlich:
show_excerpts: true
Um den Abschnitt ordentlich vom restlichen Text im Post abzugrenzen, ist auch hier ein Eintrag im Front Matter erforderlich:
excerpt_separator: <!--more-->
Als Ende des Abschnitts kommt dann eine Zeile mit <!--more--> als Text, gefolgt von einer Leerzeile.
Erweiterungen
Kategorien
In den Beispielen von Jekyll werden im “front matter” zwar die Artikel mit Kategorien versehen - Beispiel:
---
categories: eins zwei drei
---
Aber man kann sie in der Standard-Installation mit dem “minima”-Thema auf der Webseite weder sehen, noch Gruppen von Artikeln mit ihnen finden. Auch tauchen sie unter den Artikeln nicht auf.
Übersicht aller Artikel einer Kategorie
Ich benötigte eine Lösung, um automatisch zu jeder Kategorie eine Unter-Seite mit einer Auflistung aller Artikel der Kategorie zu erzeugen. Über Tags And Categories stieß ich auf ein passendes Ruby-Script auf Github, zusammen mit dem entsprechenden Layout.
Kleines Problem dabei: Die Unter-Seiten mit den Artikeln zu einer Kategorie erschienen mit auf der Homepage, und machten sie unübersichtlich.
Also musste ich noch eine kleine Änderung am generate-categories.rb vornehmen:
# Kein Title => Homepage bleibt leer! self.data['title'] = "#{title_prefix}#{category}"
Kurz auskommentiert, schon von der Homepage verschwunden.
Das zugehörige category_index.html-Layout blieb nicht unverändert; ich wollte neben den Titeln der Posts dort auch die Auszüge der Artikel anzeigen.
---
layout: default
---
<h1 class="category">Thema: {{ page.category | capitalize }}</h1>
<ul class="posts">
{% for post in site.categories[page.category] %}
<div>{{ post.date | date: "%-d.%m.%Y"}}</div>
<h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
{%- if site.show_excerpts -%}
{{ post.excerpt }}
{%- endif -%}
<!-- <div class="categories">Filed under {{ post.categories | category_links }}</div> -->
{% endfor %}
</ul>
Aufbau einer Kategorien-Seite
Ein gutes Beispiel für eine Seite, die alle Kategorien samt zugehörigen Artikeln anzeigt, fand ich hier: 3 Simple steps to setup Jekyll Categories and Tags, das ich jetzt auch einsetze. Allerdings mit einer kleinen Modifikation: Ich verlinke dort auch auf die Übersichts-Seiten mit den Artikeln einzelner Kategorien.
---
layout: page
permalink: /de/categories/
title: Themen
---
<div id="archives">
{% for category in site.categories %}
<div class="archive-group">
{% capture category_name %}{{ category | first}}{% endcapture %}
<div id="#{{ category_name | slugize }}"></div>
<p></p>
<h2 class="category-head" ><a href="{% link de/techn/categories/{{ category_name }}/index.html %}">{{ category_name | capitalize}}</a></h2>
<a name="{{ category_name | slugize }}"></a>
{% for post in site.categories[category_name] %}
<article class="archive-item">
<h4><a href="{{ site.baseurl }}{{ post.url }}">{{post.title}}</a></h4>
</article>
{% endfor %}
</div>
{% endfor %}
</div>
Kategorien und Tags bei Artikeln
Mit der Anleitung Adding tags to posts hatte ich eine Basis für ein eigenes postx.html-Layout im Unterordner _layouts. Es sorgt dafür, daß am Fuß aller Posts mit der Layout-Angabe postx im Front Matter die Tags (“Stichworte”) zum Artikel erscheinen, und für die Kategorien des Artikels Links zu den jeweiligen Übersichts-Seiten - siehe weiter unten - mit allen Artikeln zu dieser Kategorie.
---
layout: post
---
<div>
{{ content }}
</div>
<hr>
<div class="post-tags">
Stichworte:
{% for tag in page.tags %}
<span class="tag">{{ tag }}</span>
{% endfor %}
</div>
<hr>
<div class="post-categories">
Themen:
{% for category in page.categories %}
<span class="category"><a href="{% link de/techn/categories/{{ category }}/index.html %}">{{ category | capitalize }}</a></span>
{% endfor %}
</div>
<hr>
Das Datums-Format
Ebenfalls die Darstellung vom Datum musste noch angepasst werden. Das Datums-Format wird in der _config.yml-Datei festgelegt.
# Minima date format
# refer to http://shopify.github.io/liquid/filters/date/ if you want to customize this
minima:
date_format: "%d.%m.%Y"
Das Favicon
Die Wikipedia empfiehlt, das Favicon nicht einfach in das Wurzelverzeichnis der Homepage zu packen. Aber obwohl nicht W3C-konform, funktioniert es. Und es war für den Start wesentlich praktischer, als den komplizierten offiziellen Weg zu benutzen. Deshalb bleibt es auf absehbare Zeit erst mal so - nur, um eine Konformität einzuhalten, war mir der Aufwand für die entsprechenden Änderungen an der generierten Standard-Webseite doch zu hoch.
Kleiner Tipp 1
An vielen Stellen füge ich Beispiele für Layouts oder Teile von Markdown-Dateien ein. Für die entsprechende Formatierung kommt das “Syntax-Highlighting” zum Einsatz. Jekyll fügt sie trotzdem nicht immer 1:1 in die jeweilige Seite ein, sondern interpretiert sie als Teil des Markdown-Codes der Seite. Das verhindert ein “Einklammern” des Blocks mit {% raw %} und {% endraw %}.
Kleiner Tipp 2
Zur Darstellung von {% raw %} und {% endraw %} muß man zum in Writing the endraw tag in Jekyll code blocks beschriebenen Umweg greifen. Erst definiert man die Variable openTag: assign openTag = '{%' %}. Anschließend kommt an jede entsprechende Stelle statt {% ein {{ openTag }}
##