Getestet mit Ruby 2.5, Bundler 2.1.4 und Jekyll 4.0.0 (und Jekyll 4.1.1)

Inhalt

  1. Intention
  2. Installation
  3. Einsatz und Konfiguration
  4. Versionskontrolle hinzufügen
  5. tl;dr-Version
  6. Weiterführende Konfigurationen für das Jekyll-Projekt
  7. Quellen und weiterführende Links

Meine Intention für diese Anleitung

  • eine möglichst knappe Anleitung zu erstellen, welche die komplette Installation und mein verwendetes Setup dokumentiert
  • eine Anleitung zu erstellen, die Bundler korrekt verwendet
  • eine Anleitung zu erstellen, die einige weiterführende Fragen aufgreift und im tl;dr-Stil beantwortet, sofern sie dadurch die offizielle Jekyll-Dokumentation aus meiner Sicht sinnvoll ergänzt

Installation

Weiter unten befindet sich eine tl;dr-Version.

Repositories updaten (hier mit apt gezeigt)

sudo apt-get update
sudo apt-get upgrade -y

Ruby installieren (hier mit apt gezeigt)

sudo apt-get install -y ruby-full 

Bundler und Jekyll installieren

gem install bundler jekyll

Falls es dabei zu Problemen der Art You don't have /home/username/.gem/ruby/2.5.0/bin in your PATH,gem executables will not run.kommen sollte, kann Gems mit folgendem Befehl zum PATH hinzugefügt werden:

echo 'PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin:$PATH"' >> ~/.zshrc

(.zshrc ggf. durch die verwendete Shell (z.B. Bash) ersetzen.)

Bundler sollte ohne root-Rechte installiert und ausgeführt werden.

Ein neues Projekt erstellen

Bundler initialisieren

mkdir my-project
cd my-project
bundle init

**Alle folgenden Shell-Befehle werden im Root-Verzeichnis des aktuellen Projektes ausgeführt **


Bundler konfigurieren

Dieser Schritt dient dazu projektbezogene Abhängigkeiten ohne Tools wie Docker vom Rest des Systems zu isolieren und auf einfache Weise die Kontrolle über bestimmte Versionen von anderweitig verwendeten Gems zu behalten (mehr siehe unten).

bundle config set path 'vendor/bundle'

Jekyll via Bundler zum Projekt hinzufügen

bundle add jekyll

Die Verzeichnisstruktur für das Jekyllprojekt erzeugen

bundle exec jekyll new --force --skip-bundle . # Don't forget the dot!
bundle install	# installs missing gems

--force wird benötigt, da der Ordner nicht leer ist

--skip-bundle . wird benötigt, um bundle install seperat auszuführen (andernfalls könnte es zu Problemen mit Jekyll und dem bereits existierendem Gemfile geben.)

Die Seite für die lokale Entwicklung zum Laufen bringen

bundle exec jekyll serve

Die Seite ist nun unter http://127.0.0.1:4000 zu finden.

Hinweis: Alle Jekyll-Befehle sollten nun mit dem Präfix bundle exec versehen werden!


Ein Version-Control-System (hier Git) hinzufügen

Git installieren

sudo apt-get install git

Git initialisieren

git init

.gitignore hinzufügen

touch .gitignore
echo "# Ignore metadata generated by Jekyll
_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata

# Ignore folders generated by Bundler
.bundle/
vendor/" > .gitignore

Initialen Commit durchführen

git add *						# Add to index
git commit -m "Initial commit"	# Add to head
git tag -a v0.1 -m "Initial build"

tl;dr-Version

Zur Installation (ohne Git-Setup) folgende Befehle im gewünschten Projektverzeichnis ausführen:

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ruby-full 
gem install bundler	jekyll
mkdir my-project
cd my-project
bundle init
bundle config set path 'vendor/bundle'
bundle add jekyll
bundle exec jekyll new --force --skip-bundle .
bundle install			# to add missing gems
bundle exec jekyll serve

Weiterführende Konfigurationen für das Jekyll-Projekt

Aufteilung in Git-Branches

Die folgende Aufteilung hat sich für mich persönlich als nützlich erwiesen und ist kein must have

Aufteilung in

  • master: Für User-Seiten
  • gh-pages: Für Projektseiten (Von GitHub empfohlen)
  • testing: Für das Entwickeln und Testen neuer Funktionen
  • stable: Die fertige Seite aber ohne Posts, Blogbeiträge etc.
git checkout -b gh-pages	# for project sites only
git checkout -b stable
git checkout -b testing

Standart-Theme ändern

Im Gemfile einfach die Zeile `gem “minima”, “~> [version]” auskommentieren und ersetzen. Minima ist das Default-Theme für Jekyll.

Weitere Dependencies zum Projekt hinzufügen

Im Gemfile lassen sich unter

Gem::Specification.new do |spec|
    gem "name-of-gem", "~> 1.0.0"
end

weitere Plugins installieren.

Falls die Frage aufkommen sollte: Gemfile vs Gemspec

Die Jekyll-Configs anpassen

Die Konfiguration kann in der _config.yml-Datei angepasst werden. Eine komplette Referenz zur _config.yml und die Default-Config, sowie weitere Konfigurationsmöglichkeiten sind in den Jekyll-Docs zu finden.

Die Verzeichnisstruktur erweitern

Siehe hier für eine offizelle Referenz.


Die offizielle Installationsanleitung: https://jekyllrb.com/tutorials/using-jekyll-with-bundler/

Die Jekyll-Docs: https://jekyllrb.com/docs/

Eine einfache Anleitung zu Git (auf deutsch): https://rogerdudler.github.io/git-guide/index.de.html

Ein schlankes aber mächtiges GUI für Git (open-source, für Git, Windows und OS X): https://git-cola.github.io/

Hilfreiche CLI-Befehle für Jekyll (sollten mit dem Präfix bundle exec verwendet werden): https://jekyllrb.com/docs/usage/