Getestet mit Ruby 2.5, Bundler 2.1.4 und Jekyll 4.0.0 (und Jekyll 4.1.1)
Inhalt
- Intention
- Installation
- Einsatz und Konfiguration
- Versionskontrolle hinzufügen
- tl;dr-Version
- Weiterführende Konfigurationen für das Jekyll-Projekt
- 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 oder
- 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.
Quellen und weiterführende Links
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/