Modul 22 — Capstone: Statischer Site-Generator

Willkommen zum Capstone

Dieses Modul fasst dein bisheriges Wissen zu einem echten Projekt zusammen: einem Statischen Site-Generator (SSG). Ein SSG verwandelt Textdateien in HTML-Seiten — so funktionieren unzählige Blogs und Dokumentation- Seiten (z. B. viele Rust-Crates).

Dein Mini-SSG soll:

1. Markdown-artigen Text in Blöcke parsen (Überschriften, Absätze)
2. Diese Blöcke als sauberes, sicheres HTML rendern
3. Seiten in eine Vorlage (Layout) einbetten
4. als Library + Binary im Workspace laufen
5. mit Tests gegen Regressionsfehler abgesichert sein

Das verknüpft Module 6 (Collections), 7 (Fehler), 8 (Traits/Generics), 10 (Closures/Iteratoren), 15 (Testen), 16 (Workspace & cargo), 18 (I/O) und 19 (Makros).

Ein Enum für den Inhalt

Das Herzstück ist unser Datenmodell: ein Block-Enum, das die Bausteine einer Seite beschreibt. Der Parser füllt es, der Renderer liest es — beide hängen nur an diesem Typ:

#[derive(Debug, PartialEq, Clone)]
pub enum Block {
    Heading(u32, String),   // Level (1,2,3...) und Text
    Paragraph(String),
}

Heading(u32, String) ist eine Struct-Variante mit zwei Feldern: der Überschrifts-Ebene und dem Text. PartialEq und Debug erhalten wir per derive — wichtig für Tests (assert_eq!) und Fehlermeldungen.

Übung: Block-Enum definieren

Von Zeilen zu Blöcken

Unser Parser liest den Text Zeile für Zeile und baut Blöcke:

• Zeilen, die mit # beginnen → Überschrift (Anzahl der # = Ebene)
• leere Zeile → schließt einen laufenden Absatz
• sonst → sammelt die Zeile in den aktuellen Absatz

pub fn parse(text: &str) -> Vec<Block> {
    let mut blocks = Vec::new();
    let mut para = Vec::new();

    for line in text.lines() {
        if line.starts_with('#') {
            if !para.is_empty() {
                blocks.push(Block::Paragraph(para.join(" ")));
                para.clear();
            }
            let level = line.chars().take_while(|&c| c == '#').count() as u32;
            let content = line
                .chars()
                .skip(level as usize)
                .collect::<String>()
                .trim()
                .to_string();
            blocks.push(Block::Heading(level, content));
        } else if line.trim().is_empty() {
            if !para.is_empty() {
                blocks.push(Block::Paragraph(para.join(" ")));
                para.clear();
            }
        } else {
            para.push(line.trim().to_string());
        }
    }
    if !para.is_empty() {
        blocks.push(Block::Paragraph(para.join(" ")));
    }
    blocks
}

Ein Absatz über mehrere Zeilen wird mit join(" ") zu einem Paragraph verbunden.

Von Blöcken zu HTML

Der Renderer macht das Gegenteil des Parsers: Er übersetzt Blocks in HTML-Strings:

pub fn render_block(block: &Block) -> String {
    match block {
        Block::Heading(level, text) => format!("<h{level}>{}</h{level}>", escape(text)),
        Block::Paragraph(text) => format!("<p>{}</p>", escape(text)),
    }
}

HTML-Escaping ist Sicherheitspflicht

Nutzertext darf nie unverändert in HTML landen — sonst ist ein <script>-Einschub („XSS") möglich. Wir ersetzen die gefährlichen Zeichen:

pub fn escape(s: &str) -> String {
    s.replace('&', "&")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

Daraus wird <script>& zu <script>& — im Browser harmloser Text.

Übung: Blöcke zu HTML rendern

Die ganze Seite zusammenbauen

Eine echte HTML-Seite braucht <!DOCTYPE html>, <head>, <title> und <body>. Unsere render_page-Funktion baut das vollständige Dokument:

pub fn render_page(title: &str, blocks: &[Block]) -> String {
    let body: String = blocks
        .iter()
        .map(render_block)
        .collect::<Vec<_>>()
        .join("\n");
    format!(
        "<!DOCTYPE html>\n<html>\n<head><meta charset=\"utf-8\">\
        \n<title>{}</title></head>\n<body>\n{}\n</body>\n</html>\n",
        escape(title),
        body
    )
}

blocks.iter().map(render_block) wandelt jeden Block in HTML um (map), sammelt das Ergebnis (collect) und fügt die Teile mit \n zusammen (join) — ein Paradebeispiel für die Iterator-Werkzeuge aus Modul 10.

In einen Writer schreiben (I/O)

Statt nur Strings zu liefern, nutzen wir das Write-Trait (Modul 18) — so können wir in Vec<u8>, Dateien oder sogar Netzwerk-Streams schreiben:

use std::io::Write;

pub fn build_to_writer<W: Write>(
    w: &mut W,
    title: &str,
    blocks: &[Block],
) -> std::io::Result<()> {
    let html = render_page(title, blocks);
    w.write_all(html.as_bytes())
}

<W: Write> ist ein generischer Parameter: Die Funktion akzeptiert jeden Schreiber, der das Write-Trait erfüllt.

Trennung von Logik und Einstieg

Unser Generator lebt in einer Library (src/lib.rs) — reine, wiederverwendbare Logik. Der Einstiegspunkt (Binary) ist ein dünnes CLI, das Dateien liest und HTML schreibt:

// src/main.rs (Binary) — nur der Einstieg
use std::fs;
use minissg::{parse, render_page};

fn main() -> std::io::Result<()> {
    let src = fs::read_to_string("index.md")?;
    let blocks = parse(&src);
    let html = render_page("Meine Seite", &blocks);
    fs::write("index.html", html)?;
    Ok(())
}

In der Cargo.toml ist die Binary nur eine Datei, die die Library als Pfad-Abhängigkeit nutzt (Workspace-Konzept aus Modul 16):

[package]
name = "minissg"

[dependencies]
minissg-lib = { path = "lib" }

Testen gegen Regressionsfehler

Ein Projekt ist nur fertig, wenn es absicherbar ist. Unsere drei wichtigsten Tests decken Parser, Sicherheit und Ausgabe ab:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parses_headings_and_paragraphs() {
        let blocks = parse("# Titel\n\nein Absatz.\nund weiter.");
        assert_eq!(
            blocks,
            vec![
                Block::Heading(1, "Titel".to_string()),
                Block::Paragraph("ein Absatz. und weiter.".to_string()),
            ]
        );
    }

    #[test]
    fn escapes_html() {
        assert_eq!(escape("<script>&"), "&lt;script&gt;&amp;");
    }

    #[test]
    fn renders_writer_output() {
        let mut buf = Vec::new();
        let blocks = parse("# Hi");
        build_to_writer(&mut buf, "Seite", &blocks).unwrap();
        let html = String::from_utf8(buf).unwrap();
        assert!(html.contains("<h1>Hi</h1>"));
        assert!(html.contains("<title>Seite</title>"));
    }
}

Jeder Test sichert eine Eigenschaft: sinnvolles Parsen, sichere Ausgabe, korrekter Writer-Pfad. Diese drei zusammen fangen die häufigsten Regressionsfehler.

Übung: Der komplette Site-Generator