Hinter den Kulissen

Wie bereits im letzten Blogbeitrag angekündigt, geht es heute darum, wie wir die neue Website von Isatis Web & Media technisch umgesetzt haben.

Die Grundlage bilden der Static Site Generator Jekyll mit dem Theme Minimal Mistakes. Jekyll ist in der Programmiersprache Ruby entwickelt. Die muss also auf dem Rechner, auf dem die Website gebaut werden soll, verfügbar sein. Auf dem Webserver, der das Endprodukt dann ausliefern soll, ist Ruby dagegen nicht notwendig. Es handelt sich ja um eine statische Website, deren HTML, CSS, JavaScript und so fort als “gewöhnliche” Dateien vorliegen. Wie man Ruby installiert, geht über den Rahmen dieses Blogbeitrags hinaus. Wir gehen also hier davon aus, dass Ruby zur Verfügung steht. Benötigt wird außerdem das im Ruby-Bereich weit verbreitete Tool Bundler.

Jekyll wird als Ruby-Gem installiert, beispielsweise mit gem install jekyll. Dann steht auf der Kommandozeile der neue Befehl jekyll zur Verfügung, mit dem man eine neue Website erzeugen kann. Die kann man dann nach und nach anpassen, wie man es haben möchte.

jekyll new legt die neue Website als Unterverzeichnis im aktuellen Verzeichnis an. Mit dem Kommando

jekyll new meine_neue_website

wird also ein neues Unterverzeichnis meine_neue_website erzeugt, was die initialen Dateien für die Website enthält. Der hier verwendete Name muss übrigens nicht dem späteren Namen der Website, wie er beispielsweise im title -Tag in HTML erscheint, entsprechen. Es ist aber erfahrungsgemäß eine gute Idee, einen “sprechenden Namen” zu verwenden, und sei es nur, damit man die Dateien später einmal auch wiederfindet.

Unter den erzeugten Dateien sind zunächst die zentrale Konfigurationsdatei _config.yml (man beachte den Unterstrich am Beginn, der wird uns noch häufiger begegnen) und das Unterverzeichnis _posts wichtig. Das Theme Minimal Mistakes wird als Gem installiert und dafür im Gemfile ergänzt. Das Theme benötigt außerdem das Jekyll-Plugin jekyll-include-cache. Dieses Plugin dient vereinfacht gesagt dazu, die Auswertungsergebnisse (das Rendering) von bestimmten Templates zwischenzuspeichern, damit sie nicht wiederholt gerendert werden müssen. Wir ergänzen das Gemfile also um die beiden Gems, die wir integrieren wollen:

gem 'minimal-mistakes-jekyll'
gem 'jekyll-include-cache'

und aktualisieren das Bundle mit bundle update auf der Kommandozeile. Nun wird das eben installierte Theme in der _config.yml eingetragen, damit Jekyll es verwendet. Dort ist standardmäßig das Theme Minima eingestellt.

# von
theme: minima
# ändern in
theme: minimal-mistakes-jekyll

Ebenfalls in der _config.yml muss noch jekyll-include-cache in der Plugin-Liste ergänzt werden, zum standardmäßig bereits vorhandenen jekyll-feed:

plugins:
  - jekyll-feed
  - jekyll-include-cache

Jetzt wird noch eine auf die Dauer nervige Deprecation-Meldung von Sass unterdrückt. Es würde hier zu weit führen, die Hintergründe im Detail zu erklären, aber so viel sei gesagt: Minimal Mistakes verwendet in seinen Stylesheets eine inzwischen nicht mehr unterstützte Syntax, die von neueren Versionen des CSS-Präprozessors Sass bemängelt wird. Die Verantwortlichen für Minimal Mistakes sind zögerlich dabei, die problematische Syntax einfach auf den aktuellen Stand zu bringen, weil dann das Theme nicht mehr mit einem bestimmten Setup bei GitHub Pages funktionieren würde, wo eine sehr alte Version von Jekyll verwendet wird. Das würde bedeuten, dass vermutlich tausende Websites plötzlich nicht mehr funktionieren würden. Dieses Problem betrifft eine ganze Reihe von Themes aus dem Jekyll-Ökosystem.

Um die Meldung auszublenden, ergänzt man die bereits bekannte Datei _config.yml um die entsprechende Konfiguration:

sass:
  quiet_deps: true

Nun wird noch die von jekyll new erzeugte Datei about.markdown entfernt. Wenn eine “Über uns”-Seite benötigt wird, kann man die einfach später an anderer Stelle anlegen.

Beim Erzeugen der Website hat jekyll new auch einen Beispiel-Blogeintrag angelegt, den man im Unterverzeichnis _posts findet. Der genaue Dateiname richtet sich danach, wann die Website erzeugt wurde, denn im Dateinamen eines Blogbeitrags in Jekyll ist das Datum enthalten. Der Blogbeitrag kann also beispielsweise in der Datei 2023-11-23-welcome-to-jekyll.markdown enthalten sein. In dieser Datei müssen wir noch das Layout post auf das von Minimal Mistakes unterstützte single ändern:

# von
layout: post
# ändern in
layout: single

Jetzt gilt es noch, zwei Verzeichnisse anzulegen, die typischerweise im Verlauf der Arbeit an der Seite mit Inhalt gefüllt werden: _pages , im Hauptverzeichnis der Seite auf derselben Ebene wie _posts, enthält die Seiten der Website. Das ist vereinfacht gesagt alles was kein Blogbeitrag ist, wie zum Beispiel die oben erwähnte “Über uns”-Seite. Jede Seite wird dort als eine eigene Markdown- oder HTML-Datei angelegt.

Für Assets, also Dinge wie Bilder, CSS-Dateien, JavaScript-Dateien und so fort, hat sich ein eigenes Verzeichnis assets ebenfalls im Hauptverzeichnis bewährt.

Jetzt bekommen wir zum ersten Mal das Ergebnis unserer bisherigen Arbeit zu Gesicht: Mit bundle exec jekyll server --livereload startet man den Entwicklungs-Server von Jekyll, der den aktuellen Stand der Seite auf localhost, Port 4000 anbietet. Wenn wir also im Webbrowser unserer Wahl die Adresse http://localhost:4000 aufrufen, können wir den aktuellen Stand der Website bewundern.

Die Option --livereload sorgt dabei dafür, dass bei Änderungen an den Dateien die Website im Browser automatisch neu geladen wird. Dabei gibt es allerdings eine Ausnahme: Änderungen an der bereits hinlänglich bekannten _config.yml werden vom Live Reload nicht erkannt. Hier muss der Server mit STRG-C beendet und anschließend mit dem oben genannten Kommando neu gestartet werden.

In der _config.yml geht es auch weiter, weil hier noch einige der vorgegebenen Standardwerte angepasst werden müssen. Bei den entsprechenden Schlüsseln können wir den Titel der Website angeben, wie er im Browser erscheint (Schlüssel title), die Emai-Adresse des Verantwortlichen (email), eine Beschreibung der Seite (description) und so fort. Die in der Konfigurationsdatei bereits vorhandenen Schlüssel sind weitgehend selbsterklärend. Zusätzlich bietet Minimal Mistakes die Möglichkeit, den Namen des (Haupt-)Autoren und eine Logografik festzulegen:

name: Max Mustermann
logo: /assets/images/logo.svg

Für das Favicon können wir den HTML-head erweitern. Dazu legen wir auf der Hauptebene der Website das Verzeichnis _includes an, darin wiederum das Unterverzeichnis head, und darin wiederum die Datei custom.html. Diese Datei enthält alle HTML-Tags, die in den head eingebunden werden sollen, zum Beispiel

<link rel="icon" href="/assets/images/favicon.svg" type="image/svg+xml">

In dieser Datei können auch weitere HTML-Fragmente eingefügt werden, die man im head braucht, etwa Angaben für soziale Netzwerke wie Facebook, wie Links zu dieser Website dargestellt werden sollen (Stichwort beispielsweise Open Graph).

Als nächstes werden die Einträge für die Hauptnavigation im Header der Website definiert. Dazu muss auf der Hauptebene das Unterverzeichnis ` _data angelegt werden, sowie darin die Datei navigation.yml`. In dieser YAML-Datei können wir die Menupunkte definieren:

main:
  - title: "Über uns"
    description: "Wer wir sind und was wir machen"
    url: /about
  - title: "Kontakt & Impressum"
    description: "Wie man uns erreicht und die Formalitäten"
    url: /contact

Minimal Mistakes bietet an, im Footer der Website externe Profile, etwa bei sozialen Medien, zu verlinken. Ein Link auf den RSS-Feed der Website unter /feed.xml ist bereits automatisch gesetzt. Die Links verwenden Symbole aus Font Awesome. Definiert werden die Links in der _config.yml:

footer:
  links:
    - label: "Mastodon"
      icon: "fab fa-fw fa-mastodon"
      url: "https://..."
    - label: "Codeberg"
      icon: "fab fa-fw fa-codeberg"
      url: "https://..."

Damit steht bereits ein großer Teil des “Rahmens” der Website, so dass wir uns jetzt dem eigentlichen Inhalt zuwenden können. Für die verschiedenen Seiten haben wir weiter oben ja schon das Verzeichnis _pages angelegt. Damit Jekyll die Dateien darin erkennt, müssen wir das Verzeichnis noch in der _config.yml einbinden, und zwar im Schlüssel include:

include:
  - _pages

Die einzelnen Seiten, also beispielsweise “Über uns”, “Kontakt” oder “Unsere Produkte”, entsprechen jeweils einer Datei in _pages. Das kann eine HTML-Datei oder eine Markdown-Datei sein. In beiden Fällen steht am Beginn ein sogenanntes Frontmatter. Darin sind Meta-Angaben zur Seite enthalten wie etwa der Titel oder das Datum der letzten Änderung. Das kann dann beispielsweise so aussehen, in einer about.md im Markdown-Format:

---
title: "Über uns"
permalink: /about
description: "Wer wir sind und wie wir es wurden"
date: 2023-11-17 15:41:00 +0200
last_modified_at: 2023-11-17 15:41:00 +0200
---

# Über uns

Alles begann an einem sonnigen Tag im Jahr 2002.

oder in einer products.html im HTML-Format:

---
title: "Unsere Produkte"
permalink: /products
description: "Was wir für Sie tun können"
date: 2023-11-17 15:41:00 +0200
last_modified_at: 2023-11-17 15:41:00 +0200
---

<h3>Unsere Produkte</h3>

<p>Bei uns finden Sie ein umfangreiches Angebot rund um...

Es mag auf den ersten Blick ungewohnt erscheinen, ein Frontmatter in eine HTML-Datei einzubinden, aber das ist korrekt so.

Der Schlüssel permalink gibt an, unter welchem Pfad die Seite erreichbar sein soll, relativ zur Domain. Wenn wir beispielsweise https://meine-website.tld/ bauen, entspricht ein Permalink /about demnach https://meine-website.tld/about.

Nach dem gleichen Prinzip können übrigens im Verzeichnis _posts Blogbeiträge erstellt werden.

Damit haben wir bereits einen großen Teil der Website behandelt. Natürlich bleibt noch einiges an “Feinschliff” zu tun, wie beispielsweise die Auswahl der Layouts für die einzelnen Seiten, die Verwendung von Helpern für Feature Rows oder Gallerien, die Archiv-Seiten für den Blog und so fort. Das würde aber den Rahmen dieser Übersicht sprengen. Mit dieser kurzen Einführung sollten Interessierte auf einem guten Weg sein, eine ansprechende Website mit Jekyll und Minimal Mistakes auf die Beine zu stellen. Allen anderen hoffen wir, einen interessanten kleinen Einblick darin gegeben zu haben, wie diese Website entwickelt wurde.