Struktur des Kirby-Projekts „GRAFFITI“

Mein erster Test mit Cursor auf dem VPS war denkbar unspektakulär – und genau deshalb beeindruckend. Cursor ist ein KI-gestützter Code-Editor (basierend auf VS Code), der direkt mit dem eigenen Server verbunden werden kann. Ich habe die KI einfach mein bestehendes Kirby-Projekt analysieren lassen – das Ergebnis war diese automatisch generierte Strukturdokumentation.
Dieses Dokument beschreibt die Architektur des Kirby-Projekts unter /var/www/kirby — ein**Kirby 5 Plainkit**-Setup (Flat-File-CMS, PHP 8.x) für meine persönliche Website/Blog.
Kirby lädt Inhalte aus Textdateien, rendert sie über Templates und Snippets und stellt ein Panel zur Bearbeitung bereit.

Gesamtarchitektur

flowchart TB
    subgraph request [Anfrage]
        Browser --> index.php
    end
    index.php --> Kirby[kirby/ CMS-Kern]
    Kirby --> Config[site/config/]
    Kirby --> Content[content/ Seiten und Felder]
    Kirby --> Site[site/ Templates, Blueprints, Plugins]
    Kirby --> Media[media/ Thumbnails und Uploads]
    Site --> Templates
    Site --> Blueprints
    Site --> Plugins
    Templates --> Snippets
    Templates --> Assets[assets/ CSS, JS, Fonts]

Einstiegspunkt: index.php bootstrapped Kirby und rendert die aktuelle Seite:

<?php

require 'kirby/bootstrap.php';

echo (new Kirby)->render();

Verzeichnisse auf oberster Ebene

Ordner/Datei	Rolle
`kirby/`	CMS-Kern (über Composer: `getkirby/cms` 5.4.2)
`site/`	Projekt-spezifischer Code: Panel, Templates, Plugins, Config
`content/`	Alle Seiteninhalte als Ordner + `.txt`-Dateien (eigenes Git-Repo)
`media/`	Generierte Bildvarianten, verarbeitete Uploads
`assets/`	Statisches Frontend: CSS, JS, Fonts, Icons
`vendor/`	Composer-Abhängigkeiten
`storage/`	Laufzeitdaten (nicht im Haupt-Git)
`.env`	API-Keys (Copilot, Pexels) — nicht versioniert

Weitere Root-Dateien: composer.json, composer.lock, robots.txt, site.webmanifest, Favicons/PWA-Icons.

`content/` — die Seitenstruktur

In Kirby ist jeder Ordner = eine Seite. Der Präfix mit Nummer (1_, 2_, …) steuert die Sortierung im Panel.

Hauptbereiche

Ordner	Inhalt
`home/`	Startseite mit Hero + bis zu 6 Block-Sektionen
`1_my-blog/`	Blog mit vielen Artikeln (`article.txt` pro Beitrag)
`2_photography/`	Fotografie-Bereich
`3_mastodon/`	Fediverse/Mastodon-Seite
`4_tags/`	Tag-Übersicht
`5_faq/`, `6_about-us/`, `7_get-in-contact/`	Statische Seiten
`impressum/`, `privacy-policy/`	Rechtliches
`search/`, `error/`, `login/`	Systemseiten

Globale Site-Daten: content/site.txt (Titel, Logo, Kontakt, Navigation, Social Media, …).

Besonderheit: separates Content-Repository

content/ ist ein eigenes Git-Repository (Verzeichnis content/.git). Auf Produktion synchronisiert das Plugin kirby-git-content Änderungen per Commit, Push und Pull. Code und Inhalt sind getrennt versioniert.

Typischer Artikel

Pfad: content/1_my-blog/<slug>/article.txt

Beispiel-Felder:

Title, Menutitle, Headings, Topheading, Subheading
Description (Intro + Meta Description)
Cover (Datei-Referenz)
Layout (JSON mit Block-Editor-Inhalten)
Share, Tooltip, Tags, Autor, …

Medien liegen im gleichen Ordner (bild.png + bild.png.txt für Metadaten).

Entwürfe: content/1_my-blog/_drafts/.

`site/` — Logik und Panel

`site/config/`

Datei	Rolle
`config.php`	Basis-Konfiguration (siehe unten)
`config.xxx.php`	Hostname-spezifisch (SMTP, Git-Content)
`retour.yml`	URL-Redirects (Plugin Retour)
`.env` (im Projektroot)	Wird per `parse_ini_file` geladen

Wichtige Optionen in config.php:

Kirby Copilot (Google Gemini) für KI-Texte im Panel
Pexels Image Field (API-Key aus .env)
Cookie-Banner (Analytics, Video, Maps)
SimpleStats (anonyme Statistik)
Thumbnails: ImageMagick, WebP, Qualität 60, Srcsets 600–2400px
Mastodon-Feed: User waidler auf bayerwald.social, 15 Min. Cache
Custom Routes: /sitemap.xml, /feed (RSS), /logout
Kirbytags-Hooks für <panel>, <grid>, <column>
Panel: install => false, Custom CSS

`site/blueprints/`

Definieren das Kirby Panel (Backend-Formulare):

Unterordner	Inhalt
`pages/`	Seitentypen: `article.yml`, `home.yml`, `collection.yml`, `tags.yml`, …
`blocks/`	Block-Editor-Definitionen (Hero, Text, Bild, Bookmark, …)
`fields/`	Wiederverwendbare Felder (Cover, Layout, Share, Writer, …)
`files/`, `tabs/`, `users/`	Datei-, Tab- und Benutzer-Blueprints
`site.yml`	Globale Site-Einstellungen

`site/templates/`

PHP-Templates pro Seitentyp:

Template	Verwendung
`home.php`	Startseite: Blocks + Sektionen 1–6
`article.php`	Blogartikel: TOC, Layout, Isso-Kommentare, Schema.org
`collection.php`	Übersichtsseiten / Blog-Listing
`tags.php`	Tag-Übersicht
`mastodon.php`	Mastodon-Seite
`contact.php`, `faq.php`, `about.php`, …	Weitere Seitentypen
`default.php`	Fallback
`emails/`	E-Mail-Templates

Templates nutzen oft Slots mit snippet('layouts/default', slots: true).

`site/controllers/`

Bereiten Daten für Templates vor, z. B. article.php:

$section (übergeordnete Navigations-Sektion)
$chapeau, $title, $subheading, $description, $cover, $user

Weitere Controller: home.php, collection.php, contact.php, search.php, tags.php, …

`site/snippets/`

Wiederverwendbare HTML-Teile, u. a.:

Layout: layouts/default.php, layout.php
Navigation/Meta: head.php, breadcrumbs.php, page-meta.php, footer-nav.php
Blog: toc.php, related.php, previous-next.php, rss.php, share.php
Integrationen: mastodon_feed.php, contact-form.php, Analytics-Snippets
sitemap.php für die Custom-Route

`site/plugins/`

Mix aus Composer-Paketen (unter vendor/, teils auch in site/plugins/) und lokalen Plugins:

Plugin	Zweck
kirby-copilot	KI-Texte im Panel (Google Gemini)
markdown-field	Erweiterter Markdown-Editor
git-content	Content per Git versionieren
kirby-uniform + kirby-form + kirby-flash	Kontaktformulare
embed	oEmbed/Iframes
footnotes	Fußnoten
pexelsimagefield	Stock-Fotos aus Pexels
kirby3-feed	RSS (zusätzlich eigene Route `/feed`)
autopublish	Geplante Veröffentlichung per Secret
retour	URL-Redirects
simplestats	Anonyme Statistik
mastodon-feed	Fediverse-Timeline
bookmark (custom, `site/bookmark`)	Link-Vorschau via Iframely
kirby-cookie-banner	DSGVO-Einwilligung
kirby3-janitor	Panel-Wartungsaufgaben
back-to-top, resize, icon, icons, tooltip	UI-Hilfen

`assets/` — Frontend

Statische Dateien für Theme und Layout:

css/ — Stylesheets (inkl. Custom Panel CSS-Verweis)
js/ — JavaScript
fonts/, icons/, svg-icons/, blocks/

`media/` — verarbeitete Dateien

Kirby speichert hier generierte Thumbnails und verarbeitete Uploads, strukturiert nach Seitenpfad (z. B. media/pages/my-blog/...). .jobs/-Ordner enthalten Metadaten für asynchrone Bildverarbeitung.

Datenfluss einer Blogseite

URL /my-blog/cursor
    → Kirby findet content/1_my-blog/47_cursor/
    → Template: site/templates/article.php
    → Controller: site/controllers/article.php
    → Blueprint: site/blueprints/pages/article.yml
    → Layout-Feld (JSON-Blöcke) → snippet('layout')
    → Kommentare: Isso (extern eingebettet)

Die Startseite nutzt stattdessen Block-Felder (blocks, section_1 … section_6) und rendert sie über snippet('layout').

Composer-Abhängigkeiten

Aus composer.json (Auszug):

Paket	Version	Zweck
`getkirby/cms`	5.4.2	CMS-Kern
`distantnative/retour-for-kirby`	^5.6	Redirects
`thathoff/kirby-git-content`	^5.4	Git-Sync für Content
`mzur/kirby-uniform`	^5.7	Formulare
`fabianmichael/kirby-markdown-field`	^4.0	Markdown-Editor
`johannschopplich/kirby-copilot`	^3.8	KI im Panel
`bnomei/kirby3-feed`	^5.2	Feeds
`bnomei/kirby3-janitor`	^5.5	Wartung
`konzentrik/autopublish`	^1.0	Auto-Veröffentlichung
`sylvainjule/embed`, `footnotes`	—	Embeds, Fußnoten
`mauricerenck/pexelsimagefield`	^2.2	Pexels-Bilder
`daandelange/simplestats`	@dev	Statistik

PHP: >=8.0.0 <8.5.0

Dev-Server: composer start → php -S localhost:8000 kirby/router.php

Konfiguration und Betrieb

Thema	Details
Umgebungsvariablen	`.env` mit `API_KEYS`
Multi-Environment	`config.<hostname>.php` überschreibt Basis-Config
Thumbnails	ImageMagick (`im`), WebP, Srcsets
Cache	Seiten-Cache deaktiviert; Mastodon-Feed gecacht
E-Mail	Lokal: SMTP; Produktion: TBD
Git (Hauptrepo)	Code, `site/`, `assets/` — `content/`, `vendor/`, `media/` ignoriert
Git (Content)	Separates Repo unter `content/`

Zusammenfassung

Das Projekt ist kein Minimal-Plainkit mehr, sondern ein voll ausgebauter persönlicher Blog/CMS:

Block-basiertes Layout (Kirby Blocks)
Umfangreicher Artikel-Workflow (Copilot, Markdown, Pexels, Embeds, Bookmarks)
Fediverse-Integration (Mastodon-Feed, Share-Buttons)
Content in separatem Git-Repository
Produktions-Features: RSS, Sitemap, Redirects, Cookie-Banner, Statistik, Isso-Kommentare

Erstellt am 25.05.2026 — Analyse des Projekts unter /var/www/kirby.

Struktur des Kirby-Projekts „GRAFFITI“

Gesamtarchitektur

Verzeichnisse auf oberster Ebene

content/ — die Seitenstruktur

Hauptbereiche

Besonderheit: separates Content-Repository

Typischer Artikel

site/ — Logik und Panel

site/config/

site/blueprints/

site/templates/

site/controllers/

site/snippets/

site/plugins/

assets/ — Frontend

media/ — verarbeitete Dateien