How-To Jekyll Cheat Sheet

Einleitung

Diese How-To Seite dient als Übersicht über den Jekyll Syntax. Sie ist eine Zusammenfassung und dient als Cheat Sheet.

Inhalt erstellen

Inhalt (Seiten pages oder Beiträge posts) wird als Markdown-Datei (*.md) erstellt.

Zu Beginn jeder Inhaltsseite ist ein Metadaten Block zu erstellen: Front Matter. Die Metadaten werden im YAML-Format eingetragen und mit --- umschlossen. Mehr Details zu Front Matter sind in dem Front Matter Post (Englisch) zu finden.

Post erstellen

Der Dateiname muss das Format YYYY-mm-DD-Title.md haben. Fertige Dateien werden unter _posts und Entwürfe unter _drafts abgelegt.

Post Header / Kopfdaten für die HTML Erstellung

---
layout: post
title: "Hallo Welt - mein erster Post"
date: 2000-01-01 12:00:00 +0200
lang: de
category: blog-post
tags: [ tag 1, tag 2 ]
post_key6: a1b2c3
---

Page erstellen

Der Dateiname hat das Format Title.md. Fertige Dateien werden unter pages (kein Unterstrich am Anfang) abgelegt.

Page Header / Kopfdaten für die HTML Erstellung

---
layout: page
title: How-To
date: 2020-01-14 18:00:00 +0200
permalink: /howto/
lang: de
---

Überschriften

Überschriften beginnen mit einem # gefolgt von einem Leerzeichen und der eigentlichen Überschrift. Überschriften sollten mit Leerzeilen umschlossen werden.

Markdown	HTML
`# Top Level Überschrift`	<h1>Top Level Überschrift</h1>
`## 2. Level Überschrift`	<h2>2. Level Überschrift</h2>
`### 3. Level Überschrift`	<h3>3. Level Überschrift</h3>
`#### 4. Level Überschrift`	<h4>4. Level Überschrift</h4>
`##### 5. Level Überschrift`	<h5>5. Level Überschrift</h5>

Die Top Level Überschrift, wird oft mit dem Titel page.title gleichgesetzt. Daher ist einfache # Verwendung in Jekyll nicht zu empfehlen.

Einen Absatz erstellen

Um Text in Blöcke oder Absätze zu unterteilen, ist es nötig, dass am Ende eines Absatzes ` ` (zwei Leerzeichen) getippt werden. So kann ein Zeilenumbruch erzwungen werden. Ein Trennung von einem Absatz ist auch zwei Zeilenumbrüchen möglich.

Text Formatieren

Fettdruck

Um Text in fett darzustellen muss man diesen mit ** einschießen.

Markdown	HTML
`Mein fetter Text`	Mein fetter Text

Kursiver Text

Um Text in kursiv darzustellen muss man diesen mit _ oder * einschießen.

Markdown	HTML
`_Mein kursiver Text_`	Mein kursiver Text
`Mein kursiver Text`	Mein kursiver Text

Durchgestrichener Text

Um Text durchzustreichen darzustellen muss man diesen mit ~~ einschießen.

Markdown	HTML
`~~Mein durchgestrichener Text~~`	~~Mein kursiver Text~~

Rechts ausgerichteter Text

Markdown unterstützt keinen “rechts-ausgerichteten” Text, aber das erzeugte HTML tut es mittels CSS. Um Text rechts auszurichten muss man diesen pre-fixen. Man kann das HTML Attribut style oder eine css class setzen.

Ein Text-Absatz der das style Attribut auf right setzt.

{: style="text-align: right" }
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Nascetur ridiculus mus mauris vitae ultricies. Sed risus pretium quam vulputate dignissim suspendisse in est. Diam vulputate ut pharetra sit amet. Fusce ut placerat orci nulla pellentesque dignissim enim sit amet. Egestas purus viverra accumsan in nisl. Mauris rhoncus aenean vel elit scelerisque mauris. Laoreet suspendisse interdum consectetur libero id. Mus mauris vitae ultricies leo integer malesuada nunc. Aliquet eget sit amet tellus cras. Volutpat sed cras ornare arcu dui vivamus arcu. Id diam vel quam elementum pulvinar etiam non quam.

Ergebnis (rechts aus gerichteter Text, mittels style):

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Nascetur ridiculus mus mauris vitae ultricies. Sed risus pretium quam vulputate dignissim suspendisse in est. Diam vulputate ut pharetra sit amet. Fusce ut placerat orci nulla pellentesque dignissim enim sit amet. Egestas purus viverra accumsan in nisl. Mauris rhoncus aenean vel elit scelerisque mauris. Laoreet suspendisse interdum consectetur libero id. Mus mauris vitae ultricies leo integer malesuada nunc. Aliquet eget sit amet tellus cras. Volutpat sed cras ornare arcu dui vivamus arcu. Id diam vel quam elementum pulvinar etiam non quam.

Blocksatz

Markdown unterstützt keinen “Blocksatz” Text, aber das erzeugte HTML tut es mittels CSS. Um Text als Blocksatz auszurichten muss man diesen pre-fixen. Man kann das HTML Attribut style oder eine css class setzen.

Ein Text-Absatz der das style Attribut auf justify setzt.

{: style="text-align: justify" }
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Nascetur ridiculus mus mauris vitae ultricies. Sed risus pretium quam vulputate dignissim suspendisse in est. Diam vulputate ut pharetra sit amet. Fusce ut placerat orci nulla pellentesque dignissim enim sit amet. Egestas purus viverra accumsan in nisl. Mauris rhoncus aenean vel elit scelerisque mauris. Laoreet suspendisse interdum consectetur libero id. Mus mauris vitae ultricies leo integer malesuada nunc. Aliquet eget sit amet tellus cras. Volutpat sed cras ornare arcu dui vivamus arcu. Id diam vel quam elementum pulvinar etiam non quam.

Ergebnis (Text als Blocksatz, mittels style):

Links ausgerichteter Text (erzwingen)

Markdown Text ist normal immer links ausgerichtet, allerdings kann man beim <body> oder beim Absatz <p>, <div> usw. eine andere Ausrichtung setzen. Wenn man nun die links Ausrichtung erzwingen möchte kannman das mittels CSS. Wie in den Absätzen davor beschrieben muss man den Abbsatz pre-fixen. Man kann das HTML Attribut style oder eine css class setzen.

Ein Text-Absatz der das style Attribut auf left setzt.

{: style="text-align: left" }
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Nascetur ridiculus mus mauris vitae ultricies. Sed risus pretium quam vulputate dignissim suspendisse in est. Diam vulputate ut pharetra sit amet. Fusce ut placerat orci nulla pellentesque dignissim enim sit amet. Egestas purus viverra accumsan in nisl. Mauris rhoncus aenean vel elit scelerisque mauris. Laoreet suspendisse interdum consectetur libero id. Mus mauris vitae ultricies leo integer malesuada nunc. Aliquet eget sit amet tellus cras. Volutpat sed cras ornare arcu dui vivamus arcu. Id diam vel quam elementum pulvinar etiam non quam.

Ergebnis (links ausgerichteter Text, mittels style):

Inline Code / Hervorheben

Um Text oder Code hervorzuheben muss man diesen mit ``` einschießen.

Mein wichtiger Text

HTML ID für Absatz setzen

Die id customID wird dem Absatz <p> zugewiesen.

Markdown:

{: #customID }
Mein Text mit ID customID, CSS class oder HTML attribute

HTML:

<p id="customID">
  Mein Text mit ID customID, CSS class oder HTML attribute
</p>

HTML CSS class für Absatz setzen

Die class customClass wird dem Absatz <p> zugewiesen.

Markdown:

{: .customClass }
Mein Text mit ID customID, CSS class oder HTML attribute

HTML:

<p class="customClass">
  Mein Text mit ID customID, CSS class oder HTML attribute
</p>

HTML attribute für Absatz setzen

Das attribute customAttr bekommt den Wert value und wird dem Absatz <p> zugewiesen.

Markdown:

{: customAttr="value" }
Mein Text mit ID customID, CSS class oder HTML attribute

HTML:

<p customAttr="value">
  Mein Text mit ID customID, CSS class oder HTML attribute
</p>

Das custom attribute kann auch das Attribute style sein um CSS zu setzen.

Post unterschreiben

Markdown:

{: .signature }
Author

HTML:

<p class="signature">
  Author
</p>

CSS:

.signature{
  font-family: "BradleyHandITC" !important;
  font-size: 4em;
  text-align: center;
}

Zitate

Text der mit > beginnt wird als eingerücktes Zitat dargestellt.

Mein 1. Zitat

Mein kurzes Zitat

Mein 2. Zitat empfohlen, > und beliebig langer Text ohne Umbrüche

Mein langes Zitat, Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar Foo Bar

Mein 3. Zitat, zeilweise, mit br und mehreren >

Mein Zitat über drei Zeilen: Das ist die erste Zeile
Mein Zitat über drei Zeilen: Das ist die erste Zeile
Mein Zitat über drei Zeilen: Das ist die dritte Zeile

Mein 4. Zitat, blockweise, mit br und einem >

Mein Zitat über drei Zeilen: Das ist die erste Zeile
Mein Zitat über drei Zeilen: Das ist die erste Zeile
Mein Zitat über drei Zeilen: Das ist die dritte Zeile

Mein 5. Zitat, blockweise, mit \n und einem > (funktioniert nicht)

Mein Zitat über drei Zeilen: Das ist die erste Zeile\n Mein Zitat über drei Zeilen: Das ist die erste Zeile\n Mein Zitat über drei Zeilen: Das ist die dritte Zeile

Listen

Nummerierte Listen

Liste, Element 1
Liste, Element 2
Liste, Element 3

Unsortierte Listen / Aufzählungen

* Listenelement
* Listenelement
* Listenelement

Tabellen

Tabellen werden mittels | Pipe-Symbolen getrennt. Jede Spalte wird mit je einen Pipe-Symbol umschlossen, Spalten in Mitte “teilen” sich das Pipe-Symbol.

Die erste Zeile ist der Header / die Kopfdaten, diese werden zu <th> Elementen im <thead>. Die zweite Zeile gibt die Ausrichtung (css text-align) der Spalten an, links, zentriert oder rechts. In der Ausrichtungsspalte müssen mindestens 3 Zeichen eingetragen sein. Die folgenden Zeilen sind der eigentliche Inhalten und werden zu <td> Elementen im <tbody>.

--- ist gleichwertig zu :-- und setzt den Text links
:-: zentriert den Text
--: richtet den Text rechts aus

Innerhalb von Zellen einer Tabellen kann auch weiteres Markdown verwendet werden, z.B. ** für Fettdruck oder ~~ zum Durchstreichen.

Eine Beispiel Tabelle

|     Head      |  Kopfdaten 1  | Kopfdaten 2 |
| ------------- | :-----------: | ----------: |
| col 1 / row 1 | col 2 / row 1 |         €43 |
| c 1 / r 2     | ~~c 2 / r 2~~ |        €250 |
| 1 / 3         |   **2 / 3**   |          €1 |

Ausgabe der Markdown Tabelle in HTML (Source Code)

<table>
  <thead>
    <tr>
      <th>Head</th>
      <th style="text-align: center">Kopfdaten 1</th>
      <th style="text-align: right">Kopfdaten 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>col 1 / row 1</td>
      <td style="text-align: center">col 2 / row 1</td>
      <td style="text-align: right">€43</td>
    </tr>
    <tr>
      <td>c 1 / r 2</td>
      <td style="text-align: center"><del>c 2 / r 2</del></td>
      <td style="text-align: right">€250</td>
    </tr>
    <tr>
      <td>1 / 3</td>
      <td style="text-align: center"><strong>2 / 3</strong></td>
      <td style="text-align: right">€1</td>
    </tr>
  </tbody>
</table>

Ausgabe der Markdown Tabelle in HTML (gerendert)

Head	Kopfdaten 1	Kopfdaten 2
col 1 / row 1	col 2 / row 1	€43
c 1 / r 2	~~c 2 / r 2~~	€250
1 / 3	2 / 3	€1

Jekyll Liquid Filter und Tags

A Filter in Jekyll comes from Liquid. Filters are wrapped with {{ }} double curly brackets.

A Tag in Jekyll comes from Liquid. Tags are wrapped with {% %} curly brackets followed by a percentage symbol.

Namen und Beschreibung

Name	Markdown	Ergebnis
About-Me Initialen	`{{ site.aboutme.initialen }}`
About-Me Claim	`{{ site.aboutme.claim }}`
About-Me Slogan (Initialen + Claim)	`{{ site.aboutme.slogan }}`

Capture und Variablen

Speichern von Text / Berechnungen als capture und Verwendung im weiteren ablauf.

Speichern eines Textes ein wenig Latin in der Variable loremipsum. Das Speichern wird {% %} block durch geführt, die Verwendung mittels {{ }}.

{% capture loremipsum %}Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Nascetur ridiculus mus mauris vitae ultricies. Sed risus pretium quam vulputate dignissim suspendisse in est. Diam vulputate ut pharetra sit amet. Fusce ut placerat orci nulla pellentesque dignissim enim sit amet. Egestas purus viverra accumsan in nisl. Mauris rhoncus aenean vel elit scelerisque mauris. Laoreet suspendisse interdum consectetur libero id. Mus mauris vitae ultricies leo integer malesuada nunc. Aliquet eget sit amet tellus cras. Volutpat sed cras ornare arcu dui vivamus arcu. Id diam vel quam elementum pulvinar etiam non quam.{% endcapture %}

Verwenung des Wertes der Variable


{{ loremipsum }}

Links / Querverweise

Es gibt grundsätzlich zwei Arten von Links absolute und relative.

Root-Relativer Link: [Link Text](/favicons/favicon.ico), sind die im Normallfall die Empfehlung. Sie sind robust, wenn Inhalt oft verschoben wird, da der Bezugspunkt erhalten bleibt. Allerdings kann es zu Problemen beim Testen kommen, wenn die Basis-Url nicht gesetzt ist. Root-Relative Links starten immer mit /.
Relative Link: [Link Text](../favicons/favicon.ico), sind die richtige Wahl, wenn man viele Daten-Dateien oder Bilder “in der Nähe” der eigentlichen Seite ablegen will. Ordner auf der Root-Ebene werden dann nicht so “überflutet”. Beim Verschieben von Inhalten / Bereichen muss allerdings die Datei- und Ordner-Struktur erhalten bleiben. Relative Links starten mit ./ (selber Ordner), ../ (Eltern-Verzeichnis) oder direkt mit dem Namen, z.B. favicons/favicon.ico, das entspricht ./favicons/favicon.ico.
Absoluter Link: [Link Text]([https://notes.kargware.com/favicons/favicon.ico), sollte für externe URLs / Links verwendet werden. Absolute Pfade für interne Links sind zum Testen nicht ideal, da die absoluten URLs, auf lokalen Systemen, wie localhost, nicht vorhanden sind. Externe URLs / Links sollten mit https:// oder http:// starten.

Links mit Markdown

Links sind im Format [name](url) einzutragen

[KargWare](https://kargware.com)

Links als Referenz einfügen

[KargWare][ref001]

[ref001]: https://kargware.com

Links zu Pages mit Liquid

In der offiziellen Dokumentation zu Jekyll Links, steht das man link für Links zu internen Pages verwenden soll.

Beispiele für Links

{% link _tooling/placeholder.md %}
{% link pages/impressum.md %}
{% link /assets/favicons/favicon.ico %}

Beispiele für Links in markdown syntax

[Link zu einem Dokument einer collection]({% link _tooling/placeholder.md %})
[Link zu einer Seite (page)]({% link pages/impressum.md %})
[Link zu einer Icon-Datei]({% link /assets/favicons/favicon.ico %})

Die Dateiendung muss beim Link mit angegeben werden! Die Basis-URL site.baseurl muss nicht vorangestellt werden. Bei der Verwendung des Jekyll Tags link wird überprüft ob das Ziel vorhanden ist, das ist ein Vorteil gegenüber normalen Markdown Links.

Links zu Posts mit Liquid

In der offiziellen Dokumentation zu Jekyll Links, steht das man post_url für Links zu internen Posts verwenden soll.

Ein Link zu einen Post 2020-04-16-Front-Matter-on-Notes-by-KargWare

{% post_url 2020-04-16-Front-Matter-on-Notes-by-KargWare %}

Ein Link zu einen Post 2020-04-16-Front-Matter-on-Notes-by-KargWare in markdown syntax

[Front-Matter-on-Notes-by-KargWare]({% post_url 2020-04-16-Front-Matter-on-Notes-by-KargWare %})

Die Dateiendung muss nicht beim Link mit angegeben werden! Die Basis-URL site.baseurl muss nicht vorangestellt werden. Bei der Verwendung des Jekyll Tags post_url wird überprüft ob das Ziel vorhanden ist, das ist ein Vorteil gegenüber normalen Markdown Links.

Bilder einfügen

Bilder verlinkt man im Format ![alttext](imageurl) einzutragen

![Text wenn Bild nicht gefunden wird](https://kargware.com/logo.png)

Bilder die Links sind

[![alt text](imageurl)](linkurl)

[![alt text](imageurl)](linkurl){:width="300px" height="150px"}

Beispiele

[![KargWare](https://kargware.com/logo.png)](https://kargware.com)

[![KargWare](/asset/img/logo.png)](https://kargware.com)

Breakpoints / Bildschirm-Breite

Die Breakpoints sind in .\node_modules\foundation-sites\scss\settings\_settings.scss definiert.

Name	Use Case	Max-Breite
small	Handy	0
medium	Tablet	640px
large	Bildschirm	1024px
xlarge	not used	1200px
xxlarge	not used	1440px

Includes / Einbetten von HTML-Dateien

Einbinden von HTML ohne Parameter

{% include simple.html %}

Einbinden von HTML mit einem Parameter

{% include simple.html para1=postObj  %}

Einbinden von HTML mit mehreren Parametern (Leerzeichen getrennte Parameterliste)

{% include simple.html para1="Hallo" para2="Welt" %}

Versteckte Kommentare

Markdown unterstützt keine Kommentare. Aber mit einem kleinen workaround, kann man doch kommentieren.

Der Zweifach-Vorwärts-Slash ist die die Link ID, die Raute (Hashtag) ist die Url (selbe Seite in dem Fall) und der Text in Klammern ist der Titel des Links.

[//]: # (This comment will not be visible to the visitor (in html)!)

MIME Types

Docu MIME-Types

Name	Type
CSS	text/css
JS	application/javascript 💬
SVG	image/svg+xml