Post

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

Posted Updated
By Andreas Nicolai
7 min read
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:

1

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# 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:

1

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

Initialisieren:

1
2
3

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

Nachdem npm durchgelaufen ist:

1
2
3
4
5
6

> 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:

1

bundle install

Fertig, nun kann die Webseite generiert und angezeigt werden:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

> 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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

.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:

1

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

Beispiel:

1

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

wird zu Coding-Guidelines

Ab und zu bekommt man von Jekyll eine Warnung wie folgende:

1
2
3

Deprecation: A call to '{% post_url 2024-08-29-my-post-text %}' did not match 
a post using the new matching method of checking name (path-date-slug) equality. 
Please make sure that you change this tag to match the post's name exactly.

Die beste Möglichkeit, diese Warnung loszuwerden ist die Verwendung von Permalinks (zumindest habe ich auch bei Verwendung unterschiedlicher Schreibweisen mit Bindestrich oder Underscore noch kein Muster gefunden, warum die Warnung mal kommt und mal nicht).

Alternativ kann man auch Permalinks benutzen, die bei mir in der _config.yml für normale posts so konfiguriert sind:

1
2
3
4
5
6
7
8
9
10
11

defaults:
  - scope:
      path: "" # An empty string here means all files in the project
      type: posts
    values:
      layout: post
      comments: true # Enable comments in posts.
      toc: true # Display TOC column in posts.
      # DO NOT modify the following parameter unless you are confident enough
      # to update the code of all other post links in this project.
      permalink: /posts/:title/```

Damit werden Pfade für Artikel aus dem Dateinamen ohne Suffix .md und ohne Datum generiert. Im Beispiel oben würde man die Seite also referenzieren mit:

1

[Coding-Guidelines]( /posts/coding_style/ )

Info, Tip, Warnungs-Boxen

Syntax:

1
2
3
4
5

> 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 
    1

    @import 'github-alerts.css';

    anfügen.

  3. Im Text dann nach den Blockquotes folgende Makros einfügen:
1
2
3
4
5
6
7
8
9
10
11
12
13
14

> 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 }

Startseite anpassen

Um die Startseite anzupassen, muss man im Theme (Jekyll-gem) die Datei: gems/jekyll-theme-chirpy-7.2.4/_layouts/home.html anpassen, beispielsweise:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

...

<!-- Get normal posts on current page -->

{% assign normal_size = paginator.posts | size | minus: pinned_size %}

{% if normal_size > 0 %}
  {% if pinned_size > 0 %}
    {% assign normal_start = 0 %}
  {% else %}
    {% assign normal_start = visible_start | minus: all_pinned.size %}
  {% endif %}

  {% assign normal_end = normal_start | plus: normal_size | minus: 1 %}

  {% for i in (normal_start..normal_end) %}
    {% assign posts = posts | push: all_normal[i] %}
  {% endfor %}
{% endif %}

<!-- eigenes Zeug am Kopf der Startseite -->
<div>
  <h1>Schneggenport.de - Webseite von Andreas Nicolai</h1>
    <h2>Meine kleine Sammlung von Notizen rund um Computer und Programmierung.</h2>
</div>
<!-- eigenes Zeug Ende -->

<div id="post-list" class="flex-grow-1 px-xl-1">
  {% for post in posts %}
    <article class="card-wrapper card">
      <a href="{{ post.url | relative_url }}" class="post-preview row g-0 flex-md-row-reverse">

...

Mathematisches/Gleichungen mit Latex

Dazu muss man MathJax einschalten.

Die Datei gems/jekyll-theme-chirpy-7.2.4/_includes/mathjax-support.html anlegen mit folgendem Inhalt:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
      TeX: {
        equationNumbers: {
          autoNumber: "AMS"
        }
      },
      tex2jax: {
      inlineMath: [ ['$', '$'] ],
      displayMath: [ ['$$', '$$'], ['\\[', '\\]'] ],
      processEscapes: true,
    }
  });
  MathJax.Hub.Register.MessageHook("Math Processing Error",function (message) {
        alert("Math Processing Error: "+message[1]);
      });
  MathJax.Hub.Register.MessageHook("TeX Jax - parse error",function (message) {
        alert("Math Processing Error: "+message[1]);
      });
</script>
<script
  type="text/javascript"
  async
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"
></script>

Und in der Datei gems/jekyll-theme-chirpy-7.2.4/_layouts/default.html die Zeile

1

{% include mathjax-support.html %}

einfügen:

1
2
3
4
5
6
7
8
9
10

...
<!-- `site.alt_lang` can specify a language different from the UI -->
<html lang="{{ page.lang | default: site.alt_lang | default: site.lang }}" {{ prefer_mode }}>
  {% include head.html %}
  {% include mathjax-support.html %}

  <body>
...

Und jetzt kann man auch Latex-Formeln verwenden:

\[\left( \sqrt{ \sin^2 x + \cos^2 x } \right) ^3 = 1\]
Linux
Linux Webdesign
This post is licensed under CC BY 4.0 by the author.