Quintessenz

Die Webseiten werden dabei aus dem GitHub Repository erstellt. Das GitHub Repo https://github.com/DXorSX/dxorsx.github.io wird zur Webseite https://dxorsx.github.io/

Der Schnellstart ist hier perfekt erklärt.

Achtung: Das Repo muss exakt so heißen wie die spätere GitHub.io Page!

Nachfolgend die Einrichtung im Schnelldurchlauf nachdem ihr ein leeres GitHub Repository angelegt habt, Details siehe weiter unten

    # Repository lokal clonen
    git clone https://github.com/dxorsx/dxorsx.github.io
    cd dxorsx.github.io
    # Jeykll initiieren
    jekyll new .
    # Die geänderten Inhalte zurück in das Repository pushen
    git add --all
    git commit -m "Initial commit"
    git push -u origin main
  

Nachdem die GitHub Action gelaufen ist finden sich die Inhalte auf https://dxorsx.github.io/.

Hinweis: dxorsx ist mein GitHub Username. Wollt ihr das nachvollziehen müsst ihr dxorsx durch euren GitHub Username ersetzen.

Jekyll als WebSite Generator

Jekyll ist ein Ruby programmierter Parser der aus Plaintext Dateien eine statische Webseite baut. Einmal konfiguriert und aufgesetzt könnt ihr Inhalte in simplen Text Dateien ablegen und Jekyll kümmert sich darum das alles hübsch formatiert, verlinkt und erreichbar ist.

Jekyll bietet sich für die Nutzung auf GitHub Pages weil es von den GitHub Action unterstützt wird. Das heißt der Jekyll Parser wird in der GitHub Action ausgeführt. Trotz der guten Dokumentation habe ich einige Iterationen gebraucht um ein für mich funktionierende Setup zu finden.

Nachfolgend die Schritte die ich durchgeführt habe, die jeweils aktuelles Konfiguration findet ihr in meine GitHub Repo.

Schritt 1: Erstellen einer lokalen Arbeitsumgebung

Ich beschreibe das Vorgehen anhand einer Debian Linux Umgebung. Wenn ihr etwas anderes verwendet (Windows/macOS/FreeBSD etc.) schaut in die Jekyll Installationsanleitung.

Installiere notwendige Pakete:

    sudo apt update
    sudo apt install ruby-full build-essential zlib1g-dev
  

Mit Ruby haben wir auch den Ruby Package Manager “gem” bekommen. Diesen konfigurieren wir:

    echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
    echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
    echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
  

und installieren anschließen Jekyll:

    gem install jekyll bundler
  

Schritt 2: Gemfile anpassen

Das Gemfile editieren und den Eintrag gem "jekyll" mit einem # auskommentieren und die Zeile gem "github-pages" ergänzen. Da ich das Jekyll Template Minimal Mistakes nutze kommen bei mir noch die Einträge gem "minimal-mistakes-jekyll" und gem "jekyll-remote-theme" hinzu.

    source "https://rubygems.org"
    # Hello! This is where you manage which Jekyll version is used to run.
    # When you want to use a different version, change it below, save the
    # file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
    #
    #     bundle exec jekyll serve
    #
    # This will help ensure the proper Jekyll version is running.
    # Happy Jekylling!
    # gem "jekyll", "~> 4.3.1"
    gem "github-pages"
    # This is the default theme for new Jekyll sites. You may change this to anything you like.
    # gem "minima", "~> 2.5"
    gem "minimal-mistakes-jekyll"
    gem "jekyll-remote-theme"
    # If you want to use GitHub Pages, remove the "gem "jekyll"" above and
    # uncomment the line below. To upgrade, run `bundle update github-pages`.
    # gem "github-pages", group: :jekyll_plugins
    # If you have any plugins, put them here!
    group :jekyll_plugins do
      gem "jekyll-feed", "~> 0.12"
    end

    # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
    # and associated library.
    platforms :mingw, :x64_mingw, :mswin, :jruby do
      gem "tzinfo", ">= 1", "< 3"
      gem "tzinfo-data"
    end

    # Performance-booster for watching directories on Windows
    gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]

    # Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
    # do not have a Java counterpart.
    gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
  

Die aktuelle Version meines Gemfiles findet ihr im GitHub Repo.

Wichtig: Nachdem ihr das Gemfile angepasst habt müsst ihr bundle install ausführen um alles zu aktualisieren.

Schritt 3: _config.yml anpassen

Die _config.yml ist individuell und muss auch individuell angepasst werden. Ein simple Version kann so aussehen:

    domain: my-site.github.io       # if you want to force HTTPS, specify the domain without the http at the start, e.g. example.com
    url: https://my-site.github.io  # the base hostname and protocol for your site, e.g. http://example.com
    baseurl: /REPOSITORY-NAME/      # place folder name if the site is served in a subfolder
  

oder wenn ihr das Minimal Mistakes Template nutzt auch viel größer _config.yml

Schritt 4: Lokal testen

Nachdem ihr alles angepasst habt bleibt der erste Testlauf, dazu bringt Jekyll einen eigenen kleinen WebServer mit den wir mit

    bundle exec jekyll server
  

startet. Ihr könnt dann vom lokalen Rechner aus darauf zu greifen http://127.0.0.1:4000 vergesst nicht den Prozess jedes Mal neu zu starten wenn ihr etwas verändert habt.

Schritt 5: Auf GitHub veröffentlichen

Wenn ihr nun die Inhalte auf GitHub veröffentlicht:

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

Könnt ihr in eurem GitHub Repository unter Actions den Status einsehen und falls etwas schiefgeht im Logfile nach Hinweisen suchen.