From 87d3e7d133482df88c83272053c2ac99aa13f77d Mon Sep 17 00:00:00 2001
From: eclipse <eclipse@unterdemradar.de>
Date: Wed, 11 Jun 2025 12:17:01 +0200
Subject: [PATCH] created readme file, partially motivated by
 https://tom.preston-werner.com/2010/08/23/readme-driven-development.html

---
 README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b4fdd83
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# Autorenwebseite tobias-radloff.de
+
+Eine moderne statische Autorenwebseite mit Werksseiten, Neuigkeiten, Terminkalender, Newsletterabonnentenverwaltung und Kontaktformular auf Basis von [Pelican](https://getpelican.com).
+
+## Dependencies
+
+### Pelican
+
+In einer eigenen `venv`-Umgebung verwende ich Pelican (v4.11.0) mit Markdown-Support, installiert mittels `pip install pelican[markdown]`. Pelican setzt `python3` voraus.
+
+Plugins für Pelican: 
+
+* `pelican-yaml-metadata` – ermöglicht das Einlesen von Metadaten im YAML-Format
+* `pelican-image-process` – erlaubt das Bearbeiten von Bildern beim Erzeugen der Seite
+
+### CSS und Schriften
+
+* [Pico CSS](https://picocss.com/) – tatsächlich verwende ich einen [Fork](https://github.com/Yohn/PicoCSS), der zusätzlich Hamburger-Menüs unterstützt
+* [Libertinus Sans](https://github.com/alerque/libertinus) – im Development Mode greife ich auf lokale Dateien zurück, im Production Mode stammen sie von einem [CDN](https://www.cdnfonts.com/libertinus-sans.font)
+
+### Werke und Texte
+
+* TODO: die Sourcefiles für meine Werke und Texte sollen direkt aus der `the_works`-Datenbank erzeugt werden
+
+### Termine
+
+Das Script `utils/refresh-events.py` benötigt folgende Python-Packages (beide via `pip` installierbar): 
+
+* `caldav`
+* `vobject`
+
+### Bildverarbeitung
+
+@TODO: benutze ich das Script überhaupt noch?
+
+Das Script `utils/crop_image_to_bbox.py` setzt die Python-Bibliothek `PIL` voraus.
+
+### Favicon
+
+Um aus einer einzelnen SVG-Datei Favicons in allen nötigen Größen zu erzeugen, nutze ich das Script `utils/favicon-from-svg.sh`. Es setzt voraus:
+
+  * `inkscape`
+  * `pngquant`
+  * `image-magick`
+
+### Deployment Tool
+
+* `lftp`
+
+### Auf dem Produktionsserver
+
+* `php` (aktuell 8.1)
+* Datenbanktreiber, aktuell `pdo_sqlite`
+* `PHPMailer` (im Repository enthalten)
+
+## Konfiguration
+
+Das Projekt wird in diesen Dateien konfiguriert: 
+
+* `pelicanconf.py` und `publishconf.py` – enthalten die Pelican-Konfiguration für Development bzw. Production Mode
+* `config.ini` – enthält die Zugangsdaten für Datenbank und SMTP-Server); üblicherweise ist diese Datei ein Symlink zu einer der folgenden Dateien
+  * `config.dev.ini` – Werte für den Development Mode
+  * `config.prod.ini` – Werte für den Production Mode
+  * und `config.example.ini` ist ein Beispieldatei mit Dummy-Werten
+* `deploy.ini` – FTP-Zugangsdaten für den Produktionsserver
+* `events.ini` – Zugangsdaten für den CalDAV-Server
+
+## Ausführen
+
+### Seite im Development Mode (neu) erzeugen
+
+* `make clean` – Output-Verzeichnis leeren
+* `make html` – alle HTML-Seiten neu erzeugen, die nicht im Output-Verzeichnis vorhanden sind oder deren Sourcefiles sich seit dem letzten Erzeugen verändert haben
+* `make regenerate` – auf Änderungen in Sourcefiles lauschen und entsprechende Seiten neu erzeugen 
+* `sudo lighttpd -f lighttpd.conf` – Test-Webserver starten (Kontaktformular und Newsletteran-/-abmeldung erzeugen POST-Requests, doch der mit Pelican mitgelieferte Webserver verarbeitet nur GET-Requests; ich teste die Seite daher mit [lighttpd](https://www.lighttpd.net/))
+* `utils/refresh-events.py` – CalDAV-Termine neu einlesen
+
+### Seite im Production Mode (neu) erzeugen
+
+* `make clean` – Output-Verzeichnis leeren
+* `make publish` – Seite mit Produktionsparametern neu erzeugen (liest automatisch Termine neu ein) 
+
+### Deployment
+
+* `deploy-via-ftp.sh` – Seite auf den Produktionsserver hochladen
+
+## Dokumentation
+
+### Aufbau der Webseite
+
+Pelican kennt Artikel und Seiten. Ich verwende diese wie folgt: 
+
+* meine einzelnen Werke sowie News-Posts sind Artikel; die Sourcefiles liegen in `content/posts/` 
+  * die Kategorie entspricht der Werksart (Romane, Kurzprosa, Lyrik, Weitere, News); alle Sourcefiles einer Kategorie liegen im gleichnamigen Unterverzeichnis (zB `content/posts/romane/`)
+  * Schlagworte entsprechen – weitgehend – den Genres, geben aber auch zB englischsprachige Texte an 
+* alles andere sind Seiten; die Sourcefiles liegen in `content/pages/`
+
+### Templates
+
+
+
+### Termine neu einlesen
+
+
+
+## TODOs
+
+* Seite schneller laden (lazy loading?)
+* the_works anbinden, sodass die Werk-Seiten aus der DB automatisch übernommen werden
\ No newline at end of file