Einrichten von Jekyll und dem Chirpy-Theme für das Generieren einer statischen Webseite

Jekyll Setup

Die nachfolgenden Schritte stammen aus der offiziellen Anleitung von https://jekyllrb.com/docs/step-by-step/01-setup/, habe diese aber ergänzt um Ubuntu-spezifische Informationen. Die Anleitung hab ich mit Ubuntu 24.04 (Mai 2025) getestet.

Ruby + Ruby Gems + npm installieren:

sudo apt install ruby-rubygems ruby-dev npm

GEM_HOME Pfad festlegen (damit die gems ohne sudo installiert werden können):

1. export GEM_HOME=/home/ghorwin/.gem in ~/.profile hinzufügen
2. export PATH="$GEM_HOME/bin:$PATH" in ~/.bashrc hinzufügen

Wenn man das vergisst, bekommt man folgende Fehlermeldung angezeigt:

ERROR: While executing gem ... (Gem::FilePermissionError)

You don't have write permissions for the /var/lib/gems/3.0.0 directory.

# als normaler Nutzer ausführen, nicht als sudo
> gem install jekyll bundler
Fetching unicode-display_width-2.6.0.gem
Fetching terminal-table-3.0.2.gem
Fetching safe_yaml-1.0.5.gem
Fetching forwardable-extended-2.6.0.gem
Fetching mercenary-0.4.0.gem
Fetching liquid-4.0.4.gem
Fetching pathutil-0.16.2.gem
Fetching ffi-1.17.2-x86_64-linux-gnu.gem
Fetching rouge-4.5.2.gem
Fetching rb-inotify-0.11.1.gem
Fetching rexml-3.4.1.gem
Fetching kramdown-2.5.1.gem
Fetching rb-fsevent-0.11.2.gem
Fetching kramdown-parser-gfm-1.1.0.gem
Fetching http_parser.rb-0.8.0.gem
Fetching google-protobuf-4.30.2-x86_64-linux.gem
Fetching sass-embedded-1.87.0-x86_64-linux-gnu.gem
Fetching jekyll-sass-converter-3.1.0.gem
Fetching concurrent-ruby-1.3.5.gem
Fetching listen-3.9.0.gem
Fetching eventmachine-1.2.7.gem
Fetching colorator-1.1.0.gem
Fetching jekyll-watch-2.2.1.gem
Fetching addressable-2.8.7.gem
Fetching jekyll-4.4.1.gem
Fetching em-websocket-0.5.3.gem
Fetching i18n-1.14.7.gem
Fetching base64-0.2.0.gem
Fetching public_suffix-6.0.2.gem
Successfully installed unicode-display_width-2.6.0
...
...
Fetching bundler-2.6.8.gem
Successfully installed bundler-2.6.8
Parsing documentation for bundler-2.6.8
Installing ri documentation for bundler-2.6.8
Done installing documentation for bundler after 0 seconds
30 gems installed

Das Repo https://github.com/cotes2020/jekyll-theme-chirpy.git clonen:

git clone https://github.com/cotes2020/jekyll-theme-chirpy.git myWebPage

Initialisieren:

> cd myWebPage
> tools/init.sh
...

Nachdem npm durchgelaufen ist:

> tools/run.sh

> bundle exec jekyll s -l -H 127.0.0.1

Could not find gem 'html-proofer (~> 5.0)' in locally installed gems.
Run `bundle install` to install missing gems.

Also erstmal die Abhängigkeiten installieren:

bundle install

Fertig, nun kann die Webseite generiert und angezeigt werden:

> tools/run.sh

> bundle exec jekyll s -l -H 127.0.0.1

Configuration file: /home/ghorwin/webpage/myWebPage/_config.yml
 Theme Config file: /home/ghorwin/webpage/myWebPage/_config.yml
            Source: /home/ghorwin/webpage/myWebPage
       Destination: /home/ghorwin/webpage/myWebPage/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.399 seconds.
 Auto-regeneration: enabled for '/home/ghorwin/webpage/myWebPage'
LiveReload address: http://127.0.0.1:35729
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

Weitere Anpassungen

Rouge Syntax-Highlighting:

• Tab-Width auf 2 Spaces umstellen: Datei .gem/jekyll-theme-chirpy-7.2.4/_sass/base/_syntax.scss bearbeiten:

.highlight {

  /* ... */

  pre {
  
    /* ... */
  
    /* Die nächsten 2 Zeilen einfügen */
    tab-size: 2; 
    -moz-tab-size: 2;
  }

  /* ... */
}

Jekyll Markdown-Erweiterungen

Folgende Markdown-Erweiterungen sind spezifisch für Jekyll.

Dokumentation von Liquid statements

Dinge, die Jekyll/Liquid unverändert durchreichen soll, steckt man zwischen

{% raw %} und {% endraw %}

Textschnipsel.

Verweise zwischen Posts

Syntax:

{% post_url path/to/2025-01-11-some_document %}

Beispiel:

[Coding-Guidelines]( {% post_url cpp/2025-01-11-coding_style %} )

wird zu Coding-Guidelines

Info, Tip, Warnungs-Boxen

Syntax:

> Text
> in
> der
> Box
{: .prompt-tip }

Folgende Optionen:

{: .prompt-tip }

Langer Beispieltext für Textbox mit Zeilenumbruch und mindestens drei oder vier Zeilen

…und einer Leerzeile dazwischen.

{: .prompt-info }

Langer Beispieltext für Textbox mit Zeilenumbruch und mindestens drei oder vier Zeilen

…und einer Leerzeile dazwischen.

{: .prompt-warning }

Langer Beispieltext für Textbox mit Zeilenumbruch und mindestens drei oder vier Zeilen

…und einer Leerzeile dazwischen.

{: .prompt-danger }

Langer Beispieltext für Textbox mit Zeilenumbruch und mindestens drei oder vier Zeilen

…und einer Leerzeile dazwischen.

{: .prompt-note }

Langer Beispieltext für Textbox mit Zeilenumbruch und mindestens drei oder vier Zeilen

…und einer Leerzeile dazwischen.

Github Boxes

Man kann auch Github-Style Infoboxen erhalten, wie folgende:

This is a note.

This is a tip.

This is an important note.

This is a warning.

This is a caution.

Dazu müssen die Style-Sheets ergänzt werden (siehe auch Chirpy-Discussion-Topic ):

1. Datei github-alerts.css in das Chirpy-gem-Verzeichnis unter /assets/css kopieren, also bei mir nach ~/.gem/gems/jekyll-theme-chirpy-7.2.4/assets/css/github-alerts.css
2. Datei ~/.gem/gems/jekyll-theme-chirpy-7.2.4/assets/css/jekyll-theme-chirpy.scss bearbeiten und Zeile

   @import 'github-alerts.css';
   

   anfügen.

3. Im Text dann nach den Blockquotes folgende Makros einfügen:

> This is a note.
{: .gh-alert.note }

> This is a tip.
{: .gh-alert.tip }

> This is an important note.
{: .gh-alert.important }

> This is a warning.
{: .gh-alert.warning }

> This is a caution.
{: .gh-alert.caution }

Emojies

Um Emojies im Text zu verwenden, muss man ein Plugin installieren.