Setup

Prüfe, ob dein jekyll funktioniert:

$ jekyll -version
Jekyll 0.12.0

Zuerst erstellt ihr euch einen Projektordner:

$ mkdir ~/projects/jekyll-demo

Im neuen Projekt-Ordner wird die jekyll-kKonfigurationsdatei erstellt:

$ vim ~/projects/jekyll-demo/_config.yml

Nach Konvention behandelt jekyll Dateien mit Unterstrichen _ besonders. Alle anderen Dateien im Ornder werden als statische Ressourcen ins _site Verzeichnis kopiert.

Die _config.yml beinhaltet z.B. alle Konfigurationen, die für den Betrieb des jekyll Generators nötig sind und überschrieben werden sollen.

In meinem Fall habe ich eine Vorlage verwendet, um auch die Menge der Optionen im Überblick zu behalten.

In die _config.yml wird die Basiskonfiguration abgelegt:

afe:         false
auto:        true
server:      false
server_port: 4000
baseurl:     /
url:         http://localhost:4000

source:      .
destination: ./_site
plugins:     ./_plugins

future:      true
lsi:         false
pygments:    false
markdown:    maruku
permalink:   date

maruku:
  use_tex:    false
  use_divs:   false
  png_engine: blahtex
  png_dir:    images/latex
  png_url:    /images/latex

rdiscount:
  extensions: []

redcarpet:
  extensions: []

kramdown:
  auto_ids: true,
  footnote_nr: 1
  entity_output: as_char
  toc_levels: 1..6
  use_coderay: false

  coderay:
	coderay_wrap: div
	coderay_line_numbers: inline
	coderay_line_numbers_start: 1
	coderay_tab_width: 4
	coderay_bold_every: 10
	coderay_css: style

Die Konfiguration kann mit Parametern überschreiben werden. Welche genau, findet ihr hier.

Für's Erste reicht es nur einen Parameter zu kennen: --server. Dieser erlaubt es die Server-Version von jekyll zu starten, der mit der Konfiguration auto, live zu coden.

Ihr startet also:

$ cd ~/projects/jekyll-demo
$ jekyll --server

Im Browser könnt ihr dann mit http://localhost:4000/ den Server ansprechen.

404 File Not Found

Na klar, denn wir haben noch kein einziges File im System.

Dank auto-updates in der _config.yml können wir aber fröhlich drauflos coden.

Zuerst legen wir ein Template an, das als HTML-Ausgangsstruktur herhalten wird.

$ touch ~/projects/jekyll-demo/_layouts/base.html

In die base.html wird die grobe Seite strukturiert:

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" />
	<title> {% if page.title %} {{ page.title }} | {% endif %} Jekyll demo </title>
	<link rel="stylesheet" href="/resources/css/styles.css" />
</head>
<body>
	<h1>Demo</h1>
	<ul>
		<li><a href="/">Home</a></li>
		<li><a href="/blog/">Blog</a></li>
	</ul>
	{{ content }}
</body>
</html>

Ist das Template angelegt, wird es in die Startseite eingesetzt. Dafür wird eine index.html Seite im Projektordner angelegt.

$ touch ~/projects/jekyll-demo/index.html

Diese beinhaltet dann folgenden Code:

---
layout: base
title: Willkommen
---
<p>
	Willkommen auf meiner Homepage
</p>

layout legt das zu Grunde liegende Template fest. Bei komplexeren Sites sind mehrere Templates im _layout Ordner sinnvoll. Verschachtelungen sind möglich.

Der Inhalt von title wird mit der Angabe {{ page.title }} in die späteren Seite gerendert.

Das Verfahren, wie die Parameter in den Kopf der Seite eingebunden werden, wird hier beschrieben.

Unterhalb des zweiten --- wird der content definiert. Dies wird als {{ content }} durch das Template base.html in die Seite index.html eingefügt.

Kompliziert? Nicht wirklich, probiert es einfach mal aus...

Bevor ihr die Blog Artikel schreiben könnt, solltet ihr dafür sorgen, dass eure Leser die Artiekl auch finden. Dazu richtet ihr einen kleinen Index an. Erweitert die Seite index.html um diesen Abschnitt, indem ihr ihn einfach am Ende der Datei anhängt:

<ul>
{% for post in site.posts %}
	<li>
		<a href="{{ post.url }}"> {{ post.title }}</a>
	</li>
{% endfor %}
</ul>

Dies baut die Liste der verfügbaren Posts, indem jekyll in dem Ordner _posts wühlt und die Titel der markdown-Files einliest, die der jekyll Konvention entsprechen: YYYY-MM-DD-titel-abc.md

Dabei ist der title innerhalb der Datei entscheidend, nicht der Titel der Datei selbst.

Blogging

Als nächstes legt ihr euch einen _posts Ordner an und befüllt es mit einigen markdown bzw. md-Files.

$ mkdir ~/projects/jekyll-demo/_posts

Nun ist es Zeit für den ersten Post:

$ touch ~/projects/jekyll-demo/_posts/2013-02-11-my-first-blog-article.md

Darin legt ihr folgenen Text ab:

---
layout: base
title: Mein erster Blog Artikel.
---
# Überschrift

Dies ist mein erster Blog Artikel.

# Lessions Learned

Juhu! Ich kann Kung-Fu!

Prinzipiell ist die Syntax an Wiki-markup angeleht und damit äusserst simpel. Eine genaue Beschreibung finet ihr hier.

Testet nun die Seite mit eurem Browser indem ihr http://localhost:4000 aufruft.

Es sollte eure Seite mit einem Eintrag zu sehen sein.

Ist die Site mal erstellt, findet ihr das Ergebnis im ordner - ratet mal - _site natürlich. Diese lässt sich einfach auf euren Webserver kopieren und fertig.

Fehlerbehandlung

Einige Fehler werden im Terminal/in der Konsole angezeigt, in der ihr den Server gestartet habt. Diese Fehler lassen sich leicht beheben.

Sollte mal der Server auf eure Änderungen mal nicht reagieren liegt vermutlich ein gravieredneres Problem vor und jekyll muss mit dem Parameter --no-auto gestartet werden. Das erlaubt dann genauere Fehlermeldungen.

Fazit

Jekyll kann viel mehr als in dem Arikel beschrieben wird. Es lohnt sich also die Links zu studieren. Happy blogging.

jekyll Kickstart

Setup

Blogging

Fehlerbehandlung

Fazit

Links