Blog @ herzog.network

Jekyll und GitHub Pages: Deine erste Webseite

Wie bereits in meinem Eingangsbeitrag geschrieben, wird dieser Blog durch Jekyll generiert und über GitHub Pages veröffentlicht. Dieser Beitrag beschreibt die Schritte, die notwendig sind, um diese Funktionalität bereitzustellen und erklärt kurz die einzelnen Dienste.

Übersicht

Definitionen

Jekyll

Jekyll ist ein einfacher, Blog-fähiger, statischer Site-Generator und generiert aus einem Vorlagenverzeichnis mit unformatierten Textdateien in verschiedenen Formaten über einen Konverter (wie Markdown) und einen Liquid-Renderer eine vollständige, einsatzbereite statische Website, die für die Bereitstellung mit einem Webserver geeignet ist. Jekyll ist auch die Engine hinter GitHub Pages. Das bedeutet, dass Jekyll verwendet werden kann, um eine Webseite oder einen Blog kostenlos von den GitHub-Servern zu hosten.

Git / GitHub

Git ist ein verteiltes Versionsverwaltungssystem. Die Besonderheit des Tools besteht darin, dass zwar ein zentrales Repository für jedes Projekt existiert, alle beteiligten Nutzer sich aber eine lokale Arbeitskopie dieses Verzeichnisses auf das eigene Arbeitsgerät herunterladen. Vorgenommene Änderungen können jederzeit mit allen anderen Projektteilnehmern ausgetauscht und – sofern relevant – in das Repository aufgenommen werden.

GitHub ist eine Plattform, in der Git-Projekte verwaltet und aufbewahrt werden können.

GitHub Pages

GitHub Pages ermöglichen die Erstellung von Webseiten aus einem GitHub-Repository heraus. Praktisch um schnell sein Unternehmen zu präsentieren, einen Blog zu betreiben oder ausführlich über sein neues Projekt zu berichten.

GitHub Account

Als erstes wird ein kostenloses Benutzerkonto eingerichtet. Unter github.com, wählt man unter “Sign Up” einen noch unbenutzten Usernamen, gibt eine E-Mail-Adresse und ein Passwort ein und klickt auf die Schaltfläche “Create Account”. Weitere Informationen, um zum Beispiel eine 2 Faktor Authentifizierung zu konfigurieren oder seine Biografie zu bearbeiten, können der Dokumentation entnommen werden.

GitHub Repository

Wenn der Account erfolgreich erstellt wurde muss auf GitHub noch eine Repository erstellt werden. Wie eine Repository erstellt wird ist in der GitHub Dokumentation beschrieben, welche Werte für die GitHub Pages Repository relevant sind, kann dieser Dokumentation entnommen werden. Wichtig ist hierbei, dass der username der Repository username.github.io mit dem erstellten Usernamen aus dem vorherigen Schritt übereinstimmt, da GitHub Pages sonst nicht funktionieren wird.

Erste Schritte

Grundlegend ist ab diesem Punkt die Webseite einsatzbereit, sobald man eine entsprechende Index Datei in die Repository lädt. Sofern Git auf dem lokalen Rechner installiert ist kann mit folgenden Kommandos in einem Terminal eine Webseite erstellt werden:

GitHub Repository lokal ablegen um damit zu arbeiten:

git clone https://github.com/username/username.github.io

Jetzt können wir in die geklonte Repository wechseln und eine index.html Datei anlegen:

cd username.github.io  
echo "Hello World" > index.html

Abschließend müssen diese Änderungen wieder in die GitHub Repository übertragen werden:

git add --all
git commit -m "Initial commit"
git push -u origin main

Damit ist die Webseite einsatzbereit und kann über die URL:
https://username.github.io aufgerufen werden.

Benutzerdefinierte Domain

Make sure you add your custom domain to your GitHub Pages site before configuring your custom domain with your DNS provider. Configuring your custom domain with your DNS provider without adding your custom domain to GitHub could result in someone else being able to host a site on one of your subdomains.

In den meisten Fällen will man die Webseite unter einer eigenen Domain bereitstellen. Dafür kommen sogenannte Custom Domains zum Einsatz. Momentan ist unsere Webseite nur über https://username.github.io erreichbar. Um die Webseite z.B. auch über https://blog.herzog.network erreichbar zu machen müssen wir auf die DNS Einträge der Domain Zugriff haben, für die wir eine Adresse erstellen wollen. Es muss ein CNAME für die gewünschte Domain erstellt werden. Da sich dies bei den DNS Anbietern unterscheidet kann man keine allgemeingütlige Anleitung schreiben, die meisten DNS Anbieter haben dafür aber FAQ Artikel oder man kann sich die Informationen beim Support einholen.

Ein richtig gesetzter CNAME kann z.B. mit dem Befehl dig blog.herzog.network abgefragt werden und würde folgendermaßen aussehen:

;; ANSWER SECTION:
blog.herzog.network.    60      IN      CNAME   herzog-network.github.io.

[dig - Wikipedia Beschreibung](https://en.wikipedia.org/wiki/Dig_(command)

Bevor der CNAME gesetzt wird sollte die GitHub Repository angepasst werden. In den Einstellungen der Respository kann eine custom domain konfiguriert werden.

custom_domain

Sobald die Custom Domain erfolgreich publiziert wurde und die Webseite über die neue Domain erreichbar ist kann auch noch HTTPS erzwungen werden. Detailliertere Informationen können den Docs entnommen werden.

Lokaler Jekyll Server

Da wir Jekyll als Site-Generator einsetzen brauchen wir auch eine lokale Umgebung, um Änderungen vorab testen zu können, bevor wir sie in die Repository übertragen und damit Live schalten. Ich habe mich entschieden die Entwicklungsumgebung in einem Docker Container bereitzustellen. Auf die Installation und Konfiguration von Docker kann ich in diesem Artikel nicht eingehen, da es den Rahmen sprengen würde aber folgende Schritte sollten ausreichen:

  • Installation von Docker Desktop
  • Erstellen einer Webseite mit Jekyll new
  • Bereitstellen des lokalen Jekyll Server

Ich nutze die Docker Container von BretFisher. Nachdem Docker Desktop installiert ist kann mit folgendem Befehl eine neue Webseite erstellt werden:

cd to empty directory
docker run -v $(pwd):/site bretfisher/jekyll new .

Dadurch wird ein Grundtemplate innerhalb des Ordner, in dem man sich befindet, angelegt. Dieses Template enthält Beispielbeiträge, ein minimales Theme und die wichtigsten Dateien, die von Jekyll benötigt werden.

Dieses Template kann nun nach belieben verändert werden. Um die Änderungen zu sehen verwendet man jekyll-serv:

cd dir/of/your/jekyll/site
docker run -p 8080:4000 -v $(pwd):/site bretfisher/jekyll-serve

Und kann dann über einen Browser unter http://localhost:8080 die von Jekyll generierte Webseite abrufen.

Anpassungen

Das Design von Jekyll Webseiten kann nach Belieben verändert werden, es gibt diverse Themes, die im Internet heruntergeladen werden können und die sich übertragen lassen. Für den Blog nutze ich aktuell dark-poole mit leicht angepasstem Code, dies wird als Grundlage dienen und in Zukunft weiter ausgebaut.

Um einen neuen Jekyll Beitrag zu erstellen wird einfach eine neue Markdown oder HMTL Datei im Ordner _posts erstellt. Wichtig ist hierbei, dass der Dateiname ein bestimmtes Format aufweisen muss. Informationen dazu sind den Docs zu entnehmen. Ein Beispielbeitrag würde folgendermaßen aussehen: 2020-12-14-how-to-write-a-blog.md, da die Syntax des Dateinamen so aussehen muss: YEAR-MONTH-DAY-title.MARKUP.

Bilder und Anhänge werden im Ordner _assets abgelegt, die Hauptkonfiguration für z.B. für die genutzten Plugins, den Titel der Webseite, die E-Mail Adresse und Autoren, Permalink Einstellungen, Base URL und so weiter wird über die Datei _config.yml vorgenommen.

Die Hauptstruktur sieht wie folgt aus:

  • _data: Diverse Dateien, Archive und so weiter können hier abgelegt werden
  • _drafts: Für Beiträge die noch nicht veröffentlicht werden sollen. Kann über .gitignore ausgeschlossen werden
  • _includes: Jekylls Includes - Wiederverwendbare HTML Komponenten
  • _layouts: HTML Layout zur Struktur der Webseite
  • _posts: Alle Beiträge die veröffentlicht werden
  • _sass: Sass (Syntactically Awesome Stylesheets) gehört in diesem Ordner
  • _site: Das automatisch generierte Build-Verzeichnis von Jekyll, in dem sich die kompilierte Webseite befindet. Dieser Ordner wird nicht an GitHub gesendet, da er sich in .gitignore befindet.
  • _assets: Hauptsächlich zum Speichern von Bildern und Skripten, kann aber auch eine Main-CSS-Datei enthalten.

You may be wondering why all of these directory names are prefixed by an underscore. A directory with a leading underscore is special and won’t get processed by Jekyll. As a result, it won’t appear in the build directory, _site/.

Um ein eigenes Theme zu erstellen oder Jekyl weiter zu konfigurieren steht die sehr ausführliche Dokumentation zur Verfügung - jekyllrb.com/docs/.

Des Weiteren kann unter anderem über den Webdienst IFTTT eine Verbindung vom Blog RSS Feed mit Twitter hergestellt werden. Damit wird ein Tweet abgesetzt, sobald ein neuer Beitrag auf dem Blog veröffentlicht wird. Eine Anleitung dazu findet sich in diesem Blog. Du kannst meinem Twitter Account gern folgen um über neue Blog Einträge von herzog.network benachrichtigt zu werden: twitter.com/herzog_network

Veröffentlichen

Zum Abschluss muss das in den letzten Schritten erstellte Template wieder in die GitHub Repository geladen werden, damit die Webseite über die in GitHub integrierte Jekyll Funktionalität generiert werden kann und danach über die gewünschte Domain erreichbar ist. GitHub unterstützt nicht alle Jekyll Plugins, wenn also ein Plugin in der lokalen Testumgebung funktioniert aber nicht über GitHub Pages, dann kann es daran liegen, dass es nicht untersützt wird. Ein Workaround dafür wäre, das _site Verzeichnis auch zu veröffentlichen und GitHub nicht das Generieren der Webseite übernehmen zu lassen.

In dem Jekyll Template, welches wir generiert haben, befindet sich keine Git Konfiguration. Diese können wir aus dem Ordner kopieren, den wir uns ganz am Anfang, in dem Abschnitt Erste Schritte, erstellt haben.

Beispiel:

cp -r /path/to/username.github.io/.git /dir/of/your/jekyll/site/

Nachdem sich die .git Konfiguration in dem entsprechenden Verzeichnis befindet kann die Jekyll Seite übertragen werden.

cd dir/of/your/jekyll/site
git add --all
git commit -m "Initial jekyll commit"
git push -u origin main

Alternativ ist es möglich via git init und git push --force die Repository aus dem Jekyll Verzeichniss neu zu initialisieren und zu überschreiben.


So long -
herzog

Hast du Fragen oder Anregungen?
Erstelle ein Ticket auf GitHub, frag mich auf Twitter oder
schreib mir eine E-Mail.