Ein einfacher Einstieg in Eleventy

About 4 min reading time

Eleventy (11ty) ist schon seit einigen Jahren mein Tool der Wahl, wenn es um die Erstellung von Webseiten geht. Dabei eignet sich Eleventy sowohl für eine einfache statische Seite, einen Blog wie diesen oder auch die Seite zu meinem Podcast Ready for Review.
Das schöne ist, dass man hier recht schnell gute Ergebnisse erzielen kann und daher zeige ich in diesem Tutorial, die Grundlagen um einen Blog zu erstellen.

Den Code für dieses Tutorial habe ich auf Github veröffentlicht. Die Zielgruppe sind Menschen, die Eleventy lernen wollen. Ich zeige im Folgenden:

  1. wie man eine einzelne Seite mit Eleventy erstellt (main branch),
  2. wie man Styling und Layout ergänzen kann (layout branch), und
  3. wie ein Blog und eine Blog-Übersicht eingefügt werden können (blog branch).

Schritt 1: Eine einzelne Seite

Um eine erste Seite zu erstellen, sind die folgenden Schritte notwendig:

  1. ein neues Verzeichnis erstellen und in dieses wechseln
  2. eine Markdown Datei anlegen und als index.md in diesem Ordner speichern
  3. im Verzeichnis mithilfe von npx eleventy ausführen: npx @11ty/eleventy

Eleventy verarbeitet nun die Markdown Datei und legt eine Datei index.html im Standardausgabeordner _site ab. Mit npx @11ty/eleventy --serve können wir die Seite auch direkt lokal starten und im Browser betrachten (die URL steht im Terminal und sollte normalerweise localhost:8080 sein).

Wenn alles funktioniert, können wir noch ein richtiges npm Projekt daraus machen und Skripte für unsere Arbeit anlegen:

  1. im Verzeichnis npm init -y ausführen
  2. Eleventy mit npm install @11ty/eleventy installieren
  3. In der package.json die Skripte durch eigene ersetzen
"scripts": {
	"build": "eleventy",
	"start": "eleventy --serve"
},

Das start Skript funktioniert auch einwandfrei ohne das build Skript. Wenn wir Änderungen vornehmen, wird die Seite neu erstellt und direkt korrekt ausgeliefert.

Schritt 2: Layout und Styling ergänzen

Bevor wir eine komplexere Seite bauen, benötigen wir etwas Struktur. Hierfür passen wir die Ordnerstruktur unseres Projekts mithilfe der Eleventy Konfiguration an.

  1. wir legen eine neue Datei .eleventy.js an
  2. dort ergänzen wir die folgende Konfiguration:
module.exports = function (config) {
	return {
		dir: {
			input: 'src',
			includes: '_includes',
			data: '_data',
			output: '_site'
		}
	};
};
  1. die index.md verschieben wir nun noch in einen neuen Ordner src
  2. Falls der Eleventy Server läuft (start Skript) beenden wir diesen und starten ihn dann neu

Die Konfiguration erlaubt uns später noch weitere Anpassungen vorzunehmen. Momentan interessiert uns aber nur der Rückgabewert, über den wir die wichtigsten Verzeichnisse definieren:

  • input definiert das Verzeichnis, wo unser Code liegt
  • includes legt fest, wo wir bspw. Layputs anlegen können. Dabei wird immer ein Unterverzeichnis von input genommen, hier also src/includes
  • data definiert den Ordner, wo wir zusätzliche Datenquellen anlegen. Diesen ignorieren wir in diesem Tutorial.
  • output definiert das Verzeichnis, wo unser Code landet. Hier also weiterhin unverändert _site

Ein Layout definieren

Was jetzt noch fehlt, ist ein Layout. Unsere Seite sollte schon valides HTML enthalten und später werden wir beispielsweise eine Navigation haben, die auf jeder Seite sichtbar sein soll.

Layouts können wir im src/_includes Ordner anlegen. Hierzu erstellen wir dort eine neue Datei layout.njk (Eleventy unterstützt sehr viele unterschiedliche Templatesprachen. Ich nutze meistens Nunjucks) mit folgendem Inhalt:


<!doctype html>
<html lang="de">
	<head>
		<meta charset="UTF-8" />
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>{{ title }}</title>
	</head>
	<body>
		{{ content | safe }}
	</body>
</html>

In den geschweiften Klammern liegen Informationen, die zur Build Zeit dort eingefügt werden. Mit {{content}} wird hier später der eigentliche Inhalt der Seite eingefügt.

Nun müssen wir unser Layout nur noch mit unserer index.md verknüpfen und den title festlegen. Beides können wir in der index.md über FrontMatter erreichen:

---
layout: layout.njk
title: Unsere erste 11ty Seite
---

CSS einbinden

Nun fehlt nur noch eine CSS Datei, um das Ganze etwas hübscher aussehen zu lassen:

  1. wir erstellen eine Datei src/style.css und ergänzen in dieser etwas CSS
  2. wir fügen <link rel="stylesheet" href="/style.css"/>im head unseres Layouts (/src/_includes/layout.njk) ein
  3. in der Eleventy Konfiguration legen wir fest, dass unsere CSS Datei einfach ins Zielverzeichnis kopiert werden soll
module.exports = function (config) {
	config.addPassthroughCopy('src/*.css');

	return {
		passthroughFileCopy: true,
		dir: {
			input: 'src',
			includes: '_includes',
			data: '_data',
			output: '_site'
		}
	};
};

Schritt 3: Einen Blog erstellen

Die meisten Dinge, die wir für einen Blog brauchen, haben wir schon in den beiden vorherigen Abschnitten angewendet. Daher ist die Erstellung eines neuen Blog Beitrags auch recht einfach:

  1. wir legen zunächst ein neues Verzeichnis src/blog an
  2. in diesem Verzeichnis legen wir für jeden Beitrag eine Markdown Datei an. Zum Beispiel my-first-post.md und füllen sie mit Front Matter für Titel und Layout und unserem Beitrag
---
layout: layout.njk
title: Mein erster Blogbeitrag
---

# Herzlich Willkommen

Dies ist mein neuer Blog

Abrufbar ist dieser Beitrag jetzt unter http://localhost:8080/blog/my-first-post. Jetzt könnten wir den Link manuell an beliebiger Stelle pflegen, was mit der Zeit aber aufwendig wird. Eleventy erlaubt uns, dies zu automatisieren. Hierfür erstellen wir eine collection mit unseren Blog-Beiträgen:

  1. in der Front Matter des Blog-Beitrags ergänzen wir einen tag blog
---
layout: layout.njk
title: Mein erster Blogbeitrag
tags: blog
---
  1. die Datei index.md benennen wir um in index.njk um hier mit Nunjucks arbeiten zu können
---
layout: layout.njk
title: Unsere erste 11ty Seite
---

<h1>Dies ist meine erste 11ty Seite</h1>
  1. in der index.njk nutzen wir unsere neue Collection, um eine Liste der Blog Beiträge anzeigen zu können

<ul>
	{% for post in collections.blog %}
	<li><a href="{{ post.url }}">{{ post.data.title }}</a></li>
	{% endfor %}
</ul>

Wenn wir jetzt weitere Blog Beiträge mit dem passenden Tag erstellen, werden diese automatisch aufgelistet.

Einfachere Navigation

Was jetzt nur noch fehlt, ist eine Navigation, damit wir wieder auf unsere Startseite kommen. Hierzu können wir im Layout (src/_includes/layout.njk) diese über unserem Content einfügen:

<nav>
	<a href="/">Start</a>
</nav>

Und das war es auch schon. Die nächsten Schritte wären wahrscheinlich weitere Seiten und eine etwas schönere Navigation. Was würde Euch an der Arbeit mit Eleventy noch interessieren? Schreibt mir gerne auf Mastodon.

This post is based on my opinion and experience. It is based on what worked for me in my context. I recognize, that your context is different.
The "Just Sharing" Principle