# QuillDrop

**QuillDrop** ist ein modernes, minimalistisches Blog-CMS, geschrieben in Go. Es kombiniert die Geschwindigkeit eines Static Site Generators mit der Flexibilität eines dynamischen HTTP-Servers - ohne externe Datenbank, ohne JavaScript-Frameworks, ohne Overhead.

## Philosophie

> Write. Save. Published.

QuillDrop folgt dem Prinzip der maximalen Einfachheit: Markdown-Dateien schreiben, speichern - fertig. Kein Build-Tool-Chaos, kein Node.js, keine Datenbank. Ein einzelnes Go-Binary erledigt alles.

## Features

### Dual-Mode Betrieb

QuillDrop unterstützt zwei Betriebsmodi in einem einzigen Binary:

- **`quilldrop serve`** - Startet einen dynamischen HTTP-Server für lokale Entwicklung und Vorschau. Ideal zum Schreiben und sofortigen Testen neuer Posts.
- **`quilldrop generate`** - Generiert eine komplette statische Website als HTML-Dateien. Perfekt für Deployment auf Nginx, Apache, CDN oder GitHub Pages.

### Markdown mit YAML-Frontmatter

Posts und Seiten werden als einfache Markdown-Dateien mit YAML-Frontmatter geschrieben:

```yaml
---
title: "Mein neuer Blogpost"
date: 2025-11-06 12:00:00
author: "Max Mustermann"
cover: "/images/posts/2025/11/cover.webp"
tags: [Kubernetes, DevOps, Self-Hosted]
categories: [Technik]
preview: "Kurze Vorschau des Posts..."
draft: false
toc: true
---

# Hier beginnt der Post

Normales Markdown mit allen Extras...
```

Unterstützte Frontmatter-Felder:

| Feld | Beschreibung |
|------|-------------|
| `title` | Titel des Posts |
| `date` | Veröffentlichungsdatum (mehrere Formate unterstützt) |
| `update` | Letzte Aktualisierung |
| `author` | Autor des Posts |
| `cover` / `featureImage` | Cover-Bild (mit Fallback) |
| `tags` | Liste von Tags |
| `categories` | Liste von Kategorien |
| `preview` | Benutzerdefinierte Vorschau (sonst automatisch aus erstem Absatz) |
| `draft` | Entwurf - wird nicht veröffentlicht |
| `toc` | Inhaltsverzeichnis automatisch generieren |
| `hide` | Post verstecken |
| `top` | Post oben anpinnen |

### Erweitertes Markdown-Rendering

QuillDrop nutzt [Goldmark](https://github.com/yuin/goldmark) als Markdown-Engine mit folgenden Erweiterungen:

- **GitHub Flavored Markdown (GFM)** - Tabellen, Strikethrough, Autolinks, Task-Listen
- **Syntax Highlighting** - Über 200 Programmiersprachen mit dem Dracula-Theme via [Chroma](https://github.com/alecthomas/chroma)
- **Emoji-Support** - Shortcodes wie `:rocket:`, `:tada:`, `:satellite:`
- **Automatische Heading-IDs** - Für Ankerverlinkung und Inhaltsverzeichnis
- **Raw HTML** - Einbettung von HTML direkt im Markdown
- **Hugo-Kompatibilität** - `{{</* rawhtml */>}}` Shortcodes werden automatisch verarbeitet

### Responsives Design mit Dark/Light Theme

Das mitgelieferte Theme bietet:

- **Dark Mode als Default** mit einem hellen Alternativ-Theme
- **Theme Toggle** mit localStorage-Persistenz (bleibt nach Reload erhalten)
- **Futuristisches Design** - Dunkle Hintergrunde, Cyan-Akzente, subtile Glow-Effekte
- **Responsive Layout** - Mobile-first, optimiert für alle Bildschirmgrößen
- **Hamburger-Navigation** auf mobilen Geräten mit Fullscreen-Overlay und eigenem Stacking Context
- **Dropdown-Menus** für verschachtelte Navigation (Touch-optimiert auf Mobile)
- **Integrierte Suche** — Lupe in der Navbar mit Ctrl+K Shortcut
- **Typographie** - Inter als Textfont, JetBrains Mono für Code und Metadaten

### Navigation und Menü

Das Navigationsmenü wird vollständig über die `config.yaml` konfiguriert und unterstützt verschachtelte Dropdown-Menüs:

```yaml
menu:
  - label: "Home"
    url: "/"
  - label: "Projekte"
    children:
      - label: "VM-Manager"
        url: "/sites/projekte/vm-manager"
      - label: "VM-Tracker"
        url: "/sites/projekte/vm-tracker"
      - label: "QuillDrop"
        url: "/sites/projekte/quilldrop"
  - label: "Über mich"
    url: "/sites/ueber-mich"
  - label: "Tags"
    url: "/tags"
```

Neue Menüpunkte und Untermenüs können jederzeit durch einfaches Erweitern der YAML-Konfiguration hinzugefügt werden.

### Pagination

Die Startseite zeigt eine konfigurierbare Anzahl von Posts pro Seite (Standard: 5). Die Pagination bietet:

- **Intelligente Seitennummerierung** - Zeigt erste und letzte Seite, plus ein Fenster um die aktuelle Seite herum
- **Ellipsis** bei vielen Seiten (1 ... 10 11 **12** 13 14 ... 23)
- **Neuere/Ältere Buttons** für schnelle Navigation
- **Pretty URLs** - `/page/2`, `/page/3`, etc.
- SEO-freundlich: `/page/1` wird automatisch auf `/` umgeleitet (301)

### Tags und Kategorien

QuillDrop unterstützt sowohl Tags als auch Kategorien zur Strukturierung von Inhalten:

- **Tag-Übersicht** unter `/tags/` mit Anzahl der Posts pro Tag
- **Tag-Seiten** unter `/tags/kubernetes/` mit allen Posts eines Tags
- **Kategorie-Übersicht** unter `/categories/` mit Anzahl der Posts pro Kategorie
- **Kategorie-Seiten** unter `/categories/technik/` mit allen Posts einer Kategorie
- **Tag- und Kategorie-Badges** auf Post-Cards und Einzelseiten
- Tags und Kategorien werden aus dem YAML-Frontmatter (`tags`, `categories`) ausgelesen

### Volltextsuche

QuillDrop enthält eine integrierte Client-seitige Suche, die komplett ohne Backend auskommt:

- **Suchindex** — Beim Generieren wird eine `search-index.json` mit allen Posts erstellt
- **Lazy Loading** — Der Suchindex wird erst beim ersten Öffnen der Suche geladen
- **Multi-Term-Suche** — Mehrere Suchbegriffe werden mit UND verknüpft
- **Felder** — Durchsucht Titel, Vorschau, Tags und Kategorien
- **Keyboard-Shortcut** — `Ctrl+K` / `Cmd+K` öffnet die Suche
- **Lupe in der Navbar** — Klick auf das Such-Icon öffnet das Suchfeld
- **Debounce** — Suchergebnisse erscheinen nach 200ms Tippverzögerung
- **Maximal 8 Treffer** mit Highlighting der Suchbegriffe
- **Escape** oder Klick außerhalb schließt die Suche
- Kein externer Dienst, kein Framework — reines Vanilla JavaScript

### Artikel-Navigation

Am Ende jedes Blog-Posts wird eine Navigation zum vorherigen und nächsten Artikel angezeigt:

- **Neuerer Artikel** (← links) — Verlinkt zum chronologisch neueren Post
- **Älterer Artikel** (→ rechts) — Verlinkt zum chronologisch älteren Post
- Beim neuesten Artikel wird nur "Älterer Artikel" angezeigt
- Beim ältesten Artikel wird nur "Neuerer Artikel" angezeigt
- Zeigt jeweils den Titel des verlinkten Artikels an

### Inhaltsverzeichnis (Table of Contents)

Posts können ein automatisch generiertes Inhaltsverzeichnis aktivieren:

- Aktivierung über `toc: true` im Frontmatter
- Unterstützt **H1, H2 und H3** Überschriften
- **Relative Einrückung** — Das TOC erkennt die minimale Heading-Ebene und rückt relativ dazu ein
- Automatische Anchor-Links zu den jeweiligen Überschriften
- Wird client-seitig generiert für schnelle Seitenladezeit

### Statische Seiten

Neben Blog-Posts unterstützt QuillDrop statische Seiten für:

- Impressum, Datenschutzerklärung
- Über mich / About
- Projektseiten (mit Unterseiten)
- Beliebige weitere Seiten

Seiten werden als Markdown-Dateien im `sites/`-Verzeichnis abgelegt. Verschachtelte Verzeichnisse werden automatisch erkannt - z.B. wird `sites/projekte/vm-tracker/index.md` unter `/sites/projekte/vm-tracker` erreichbar.

### RSS Feed

Automatisch generierter RSS 2.0 Feed unter `/index.xml` mit:

- Den letzten 20 Posts
- Titel, Link, Vorschau und Veröffentlichungsdatum
- RSS-Autodiscovery im HTML-Head
- RSS-Icon in der Navigation
- URL `/index.xml` für Kompatibilität mit bestehenden Blog-Setups

### Sitemap

Parallel zum RSS-Feed wird eine `sitemap.xml` nach dem [sitemaps.org-Protokoll 0.9](https://www.sitemaps.org/protocol.html) erzeugt - unter `/sitemap.xml` sowohl im dynamischen Server als auch in der statischen Generierung. Enthalten sind:

- Startseite und alle Pagination-Seiten (`/page/2/`, ...)
- Alle Blog-Posts (`lastmod` aus `update`, sonst `date`)
- Alle statischen Seiten aus `sites/`
- Tag- und Kategorie-Übersichten sowie alle einzelnen Tag-/Kategorie-Seiten

Die Sitemap lässt sich in der Config an- und abschalten (Default: aktiv):

```yaml
sitemap:
  enabled: true   # false schaltet /sitemap.xml komplett ab
```

### robots.txt

Ebenfalls automatisch erzeugt: eine `robots.txt` unter `/robots.txt`. Sie verweist automatisch auf die Sitemap, sobald diese aktiviert ist, und lässt sich in der Config konfigurieren (Default: aktiv):

```yaml
robots:
  enabled: true
  userAgent: "*"        # optional, Default "*"
  disallow:             # optional
    - /search-index.json
  allow:                # optional
    - /
```

Ohne eigene `allow`/`disallow`-Regeln wird `Allow: /` geschrieben, d.h. die ganze Seite ist freigegeben:

```
User-agent: *
Allow: /

Sitemap: https://blog.kuepper.nrw/sitemap.xml
```

Ist `sitemap.enabled: false` oder `baseURL` leer, entfällt die `Sitemap:`-Zeile.

### Cover-Bilder

Posts können ein Cover-Bild definieren, das sowohl auf der Startseite (als Post-Card) als auch auf der Einzelansicht angezeigt wird:

- **21:9 Aspect Ratio** auf Post-Cards mit Zoom-on-Hover Effekt
- **Volle Breite** auf der Einzelpost-Seite
- **Lazy Loading** für optimale Performance
- **Fallback** von `cover` auf `featureImage`

## Architektur

### Projektstruktur

```
quilldrop/
├── main.go                          # CLI Entry Point
├── config.yaml                      # Konfiguration
├── content/                         # Blog-Posts (Markdown)
│   ├── 2025-11-06-mein-post.md
│   └── ...
├── sites/                           # Statische Seiten
│   ├── ueber-mich.md
│   ├── impressum.md
│   └── projekte/
│       └── mein-projekt/
│           └── index.md
├── static/                          # Seiten-Assets (Icons, Bilder, ...)
│   ├── icons/
│   └── images/
├── themes/                          # Themes — ein Verzeichnis je Theme
│   └── default/
│       ├── templates/
│       │   ├── base.html            # Base Layout + Navbar + Suche
│       │   ├── home.html            # Homepage + Pagination
│       │   ├── post.html            # Einzelner Post + Prev/Next Navigation
│       │   ├── page.html            # Statische Seite
│       │   ├── tags.html            # Tag-Übersicht
│       │   ├── tag.html             # Tag-Seite
│       │   ├── categories.html      # Kategorie-Übersicht
│       │   └── category.html        # Kategorie-Seite
│       └── static/                  # Theme-Assets (werden nach /static/ gemerged)
│           ├── css/style.css
│           └── js/
│               ├── theme.js         # Dark/Light Toggle + TOC Generator
│               └── search.js        # Client-seitige Volltextsuche
├── internal/
│   ├── config/config.go             # YAML Config Loader
│   ├── content/
│   │   ├── post.go                  # Post Struct + FlexTime + Tags/Categories
│   │   ├── parser.go                # Markdown + Frontmatter Parser
│   │   └── page.go                  # Statische Seiten Parser
│   ├── server/server.go             # HTTP Server
│   ├── generator/
│   │   ├── generator.go             # Static Site Generator
│   │   ├── robots.go                # robots.txt Generator
│   │   └── search.go                # Search-Index Generator (JSON)
│   └── templates/
│       ├── render.go                # Template Engine + Functions (lädt das Theme)
│       ├── rss.go                   # RSS Feed Generator
│       └── sitemap.go               # sitemap.xml Generator
└── output/                          # Generierte statische Dateien
```

### Technologie-Stack

| Komponente | Technologie |
|-----------|-------------|
| Sprache | Go (Standard Library + minimale Dependencies) |
| HTTP Server | `net/http` (Go Standard Library) |
| Templates | `html/template`, zur Laufzeit aus `themes/<name>/templates/` geladen |
| Markdown | Goldmark + GFM + Emoji + Chroma |
| Konfiguration | YAML via `gopkg.in/yaml.v3` |
| Syntax Highlighting | Chroma (Dracula Theme) |
| Fonts | Inter + JetBrains Mono (Google Fonts) |
| CSS | Vanilla CSS mit Custom Properties |
| JavaScript | Vanilla JS — Theme Toggle, Suche, TOC (kein Framework) |

### Dependencies

QuillDrop hat bewusst minimale Abhängigkeiten - **kein Web-Framework**, **kein CSS-Framework**, **kein JS-Framework**:

- `github.com/yuin/goldmark` - Markdown Parser (CommonMark-konform)
- `github.com/yuin/goldmark-emoji` - Emoji Shortcodes
- `github.com/yuin/goldmark-highlighting/v2` - Syntax Highlighting
- `github.com/alecthomas/chroma/v2` - Syntax Highlighting Engine
- `gopkg.in/yaml.v3` - YAML Parser

### Themes

Templates und deren Assets liegen ausserhalb des Binaries in `themes/<name>/`. Dadurch
kann dasselbe QuillDrop-Binary beliebig viele Websites bedienen, jede mit eigenem Design:

```
themes/
├── default/
│   ├── templates/       # Pflicht: base, home, post, page, tags, tag, categories, category
│   └── static/          # Optional: CSS, JS, Theme-Bilder
└── newdesign/
    ├── templates/
    └── static/
```

Das aktive Theme wird in der `config.yaml` gewählt:

```yaml
themesDir: "themes"   # Default
theme: "default"      # liest aus themes/default/
```

Oder temporär per Flag, z. B. um ein Redesign zu testen:

```bash
./quilldrop serve -theme newdesign
./quilldrop generate -theme newdesign
```

**Neues Theme anlegen:**

```bash
cp -r themes/default themes/newdesign      # oder: make new-theme NAME=newdesign
# themes/newdesign/templates/*.html und themes/newdesign/static/css/style.css anpassen
./quilldrop serve -theme newdesign -dev
```

**Live-Reload:** Mit `-dev` werden die Templates bei jedem Request neu aus dem
Theme-Verzeichnis gelesen — Änderungen an HTML, CSS und JS sind nach einem
Browser-Reload sichtbar, ohne den Server neu zu starten (im Dev-Modus wird
zusätzlich `Cache-Control: no-store` gesetzt, damit der Browser nichts
zwischenspeichert). Ein fehlerhaftes Template liefert eine 500 statt einer halb
gerenderten Seite; die genaue Fehlermeldung mit Datei und Zeile steht im
Server-Log. Ohne `-dev` werden die Templates wie bisher einmal beim Start
geparst. Neue oder geänderte Markdown-Dateien erfordern weiterhin einen Neustart.

Ein Theme muss alle acht Templates enthalten (`base.html`, `home.html`, `post.html`,
`page.html`, `tags.html`, `tag.html`, `categories.html`, `category.html`);
fehlt eines oder existiert das Theme nicht, bricht QuillDrop mit einer klaren
Fehlermeldung ab.

**Statische Assets** werden gemerged: zuerst `themes/<name>/static/`, danach das
eigene `static/` der Seite — gleichnamige Dateien der Seite gewinnen also
(z. B. `static/icons/favicon.ico`). Das Design gehört ins Theme (CSS, JS),
seitenspezifisches Material bleibt in `static/` (Icons, Bilder). Beides wird unter
`/static/` ausgeliefert; `static/images/` und `static/videos/` zusätzlich unter
`/images/` und `/videos/`.

## Konfiguration

Die gesamte Konfiguration erfolgt über eine einzige `config.yaml`:

```yaml
title: "Mein Blog"
description: "Tech Blog - DevOps, Kubernetes, Self-Hosted"
author: "Max Mustermann"
baseURL: "https://mein-blog.de"
port: 8080
postsPerPage: 5
contentDir: "content"
sitesDir: "sites"
staticDir: "static"
outputDir: "output"
themesDir: "themes"
theme: "default"

menu:
  - label: "Home"
    url: "/"
  - label: "Tags"
    url: "/tags"
  - label: "Über mich"
    url: "/sites/ueber-mich"
```

| Option | Default | Beschreibung |
|--------|---------|-------------|
| `title` | - | Titel der Website |
| `description` | - | Beschreibung (Meta-Tag + Hero) |
| `author` | - | Autor der Website |
| `baseURL` | - | Basis-URL für RSS, Sitemap und absolute Links |
| `port` | `8080` | Port für den dynamischen Server |
| `postsPerPage` | `5` | Anzahl Posts pro Seite |
| `contentDir` | `content` | Verzeichnis für Blog-Posts |
| `sitesDir` | `sites` | Verzeichnis für statische Seiten |
| `staticDir` | `static` | Verzeichnis für Seiten-Assets |
| `outputDir` | `output` | Ausgabeverzeichnis für statische Generierung |
| `themesDir` | `themes` | Verzeichnis mit allen Themes |
| `theme` | `default` | Aktives Theme, gelesen aus `<themesDir>/<theme>/` (Override: `-theme`) |
| `menu` | `[]` | Navigationsmenü mit optionalen Untermenüs |
| `sitemap.enabled` | `true` | Erzeugt/serviert `/sitemap.xml` |
| `robots.enabled` | `true` | Erzeugt/serviert `/robots.txt` (mit Sitemap-Verweis) |
| `robots.userAgent` | `*` | User-agent-Zeile in der `robots.txt` |
| `robots.allow` | `[]` | Zusätzliche `Allow:`-Regeln |
| `robots.disallow` | `[]` | Zusätzliche `Disallow:`-Regeln |

## Schnellstart

### Installation

```bash
# Repository klonen
git clone https://github.com/ruedigerp/quilldrop.git
cd quilldrop

# Dependencies laden
go mod download

# Binary bauen
go build -o quilldrop .
```

### Neuen Post erstellen

Eine neue Markdown-Datei im `content/`-Verzeichnis anlegen:

```bash
touch content/2025-12-01-mein-erster-post.md
```

```markdown
---
title: "Mein erster Post"
date: 2025-12-01 10:00:00
author: "Max Mustermann"
tags: [Blog, QuillDrop]
preview: "Das ist mein erster Post mit QuillDrop!"
toc: false
---

# Willkommen

Das ist mein erster Post mit **QuillDrop**.

```

### Lokale Vorschau

```bash
# Dynamischen Server starten
./quilldrop serve

# Oder direkt mit Go
go run . serve

# Mit Live-Reload für Templates (Theme-Entwicklung)
./quilldrop serve -dev
```

Dann im Browser: [http://localhost:8080](http://localhost:8080)

### Statische Seite generieren

```bash
# HTML-Dateien generieren
./quilldrop generate

# Generierte Dateien befinden sich in output/
ls output/
```

Die generierten Dateien im `output/`-Verzeichnis können direkt auf einen Webserver (Nginx, Apache, Caddy) oder CDN deployed werden.

## URL-Schema

Alle URLs verwenden konsequent Trailing Slashes, um serverseitige Redirects zu vermeiden:

| URL | Beschreibung |
|-----|-------------|
| `/` | Startseite (letzte N Posts) |
| `/page/2/` | Seite 2 der Post-Liste |
| `/posts/2025-11-06-mein-post/` | Einzelner Blog-Post |
| `/tags/` | Tag-Übersicht |
| `/tags/kubernetes/` | Posts mit Tag "Kubernetes" |
| `/categories/` | Kategorie-Übersicht |
| `/categories/technik/` | Posts in Kategorie "Technik" |
| `/sites/ueber-mich/` | Statische Seite |
| `/sites/projekte/vm-tracker/` | Verschachtelte Projektseite |
| `/index.xml` | RSS Feed |
| `/sitemap.xml` | Sitemap für Suchmaschinen (falls aktiviert) |
| `/robots.txt` | Crawler-Regeln + Sitemap-Verweis (falls aktiviert) |
| `/search-index.json` | Suchindex (JSON) |
| `/static/css/style.css` | Statische Assets |
| `/images/posts/2025/11/cover.webp` | Bilder |

## Warum QuillDrop?

- **Keine Datenbank** - Dateisystem als einzige Datenquelle
- **Keine Build-Pipeline** - Ein `go build` und fertig
- **Keine JS-Frameworks** - Vanilla JavaScript für Theme, Suche und TOC
- **Minimale Dependencies** - 5 Go-Packages, alle fokussiert auf Markdown
- **Blitzschnell** - Generiert 100+ Posts in unter 3 Sekunden
- **Einzelnes Binary** - Templates eingebettet, kein Runtime-Setup
- **Hugo-kompatibel** - Bestehende Hugo-Posts mit Frontmatter funktionieren
- **Dual-Mode** - Entwicklung mit Server, Produktion mit Static Generator

## Lizenz

QuillDrop ist Open Source.