Kapitel 9: Markdown in statischen Webseitengeneratoren (SSG)

In diesem Kapitel lernen Sie, wie Sie Markdown für Webseiten mit Static Site Generators (SSG) verwenden.

9.1 Was sind Static Site Generators (SSG)?

SSG sind Tools, die Markdown-Dateien in statische HTML-Webseiten umwandeln.

Vorteile von SSG

• ✅ Schnell: Keine Datenbankabfragen
• ✅ Sicher: Keine Datenbank, die gehackt werden kann
• ✅ Günstig: Hosting oft kostenlos (GitHub Pages, Netlify)
• ✅ Einfach: Schreiben in Markdown

Beliebte SSGs

Name	Sprache	Besonderheit
Jekyll	Ruby	GitHub-Pages-Standard
Hugo	Go	Sehr schnell
Gatsby	JavaScript	React-basiert
VuePress	JavaScript	Vue-basiert, gut für Docs
VitePress	JavaScript	Leichtgewichtig, Vue 3
Hexo	JavaScript	Einfach, beliebt in Asien

9.2 VitePress (wird in diesem Projekt verwendet!)

VitePress ist ein Static Site Generator, der wir in diesem Projekt verwenden.

Installation

# Neues Projekt erstellen
mkdir mein-docs && cd mein-docs
npm init -y
npm install vitepress --save-dev

# package.json anpassen
"scripts": {
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs"
}

Projektstruktur

docs/
├── .vitepress/
│   ├── config.mts
│   └── theme/
├── seite1.md
├── seite2.md
└── index.md

Markdown in VitePress

# Meine Dokumentationsseite

Das ist Inhalt in Markdown.

## Unterabschnitt

Noch mehr Inhalt.

VitePress-spezifische Features

Container:

::: tip
Das ist ein Tipp!
:::

::: warning
Das ist eine Warnung!
:::

Benutzerdefinierte Komponenten:

<script setup>
import MyComponent from './MyComponent.vue'
</script>

# Meine Seite

<MyComponent />

9.3 VuePress

VuePress ist der Vorgänger von VitePress, ebenfalls Vue-basiert.

Installation

npm install -g @vuepress/cli
vuepress create my-docs

Besonderheiten

• Unterstützt Vue-Komponenten in Markdown
• Unterstützt PWA (Progressive Web Apps)
• Erweiterbar mit Plugins

9.4 Jekyll

Jekyll ist der Standard für GitHub Pages.

Installation

# Ruby muss installiert sein
gem install jekyll bundler

Projekt erstellen

jekyll new meine-webseite
cd meine-webseite
bundle exec jekyll serve

Markdown in Jekyll

Jekyll verwendet Front Matter:

---
layout: post
title: "Mein erster Post"
date: 2024-01-15
categories: [blog, tutorial]
---

# Meine Überschrift

Inhalt...

9.5 Hugo

Hugo ist bekannt für seine Geschwindigkeit.

Installation

# macOS
brew install hugo

# Windows
choco install hugo -confirm

# Linux
sudo apt install hugo

Neues Projekt

hugo new site meine-webseite
cd meine-webseite
git submodule add https://github.com/the.NewDynamic/gohugo-theme.git themes/gohugo-theme

Inhalt erstellen

hugo new posts/mein-erster-post.md

9.6 Gatsby

Gatsby ist ein React-basierter SSG.

Installation

npm install -g gatsby-cli
gatsby new meine-webseite

Besonderheiten

• Verwendet GraphQL für Datenabfragen
• React-Komponenten
• Große Plugin-Ökosystem

9.7 Markdown in SSG: Best Practices

Front Matter verwenden

---
title: Seitentitel
description: Eine Beschreibung für SEO
date: 2024-01-15
tags: [markdown, tutorial]
---

Bilder optimal einbinden

mein-projekt/
├── content/
│   ├── blog-post.md
│   └── bilder/
│       └── foto.jpg

In blog-post.md:

![Foto](./bilder/foto.jpg)

Links zwischen Seiten

[Über mich](/about)
[Erster Blogpost](/blog/erster-post)

9.8 Deployment (Veröffentlichung)

GitHub Pages

# Bei Jekyll-Projekten
git push origin main

# Bei anderen SSGs: Build-Output pushen
npm run build
cd dist
git init
git add -A
git commit -m "Deploy"
git push -f https://github.com/user/repo.git main:gh-pages

Netlify

1. Repository mit Netlify verbinden
2. Build-Befehl angeben: npm run build
3. Publish-Verzeichnis angeben: dist/ oder public/

Vercel

1. Repository importieren
2. Framework Preset wählen (z.B. "VitePress")
3. Deploy!

9.9 Zusammenfassung

In diesem Kapitel haben Sie gelernt:

• ✅ Was Static Site Generators sind
• ✅ VitePress, VuePress, Jekyll, Hugo, Gatsby
• ✅ Wie man Markdown in SSGs verwendet
• ✅ Front Matter und Best Practices
• ✅ Deployment auf GitHub Pages, Netlify, Vercel

Im nächsten Kapitel werden wir lernen, wie man Markdown in Kombination mit Pandoc für verschiedene Exportformate nutzt!

---

Übung: Erstellen Sie eine einfache VitePress-Dokumentationsseite mit:

1. Einem index.md mit Willkommensnachricht
2. Einem about.md mit Informationen über Sie
3. Einem blog/ Ordner mit einem Blogpost
4. Passender Navigation in .vitepress/config.mts