# Codex-Anweisung: WordPress-Plugin fuer GitLab-basierte Markdown-Knowledgebase ## 1. Projektziel Entwickle ein WordPress-Plugin, das technische Produktdokumentationen aus einer GitLab-Gruppe einliest, verarbeitet und innerhalb eines WordPress-basierten Kundenportals veroeffentlicht. Die neue Dokumentationsstruktur basiert ausschliesslich auf **Markdown (`.md`)**. Die alte Dokumentation wird ausserhalb dieses Plugins als statischer Legacy-Stand weitergehostet. Das Plugin importiert keine Legacy-Dateien und bildet keine Legacy-Strukturen mehr nach. ## 2. GitLab-Struktur GitLab enthaelt eine Gruppe, zum Beispiel: ```text knowledgebase/ produkt-a/ Branch: v1.0.0 Branch: v1.1.0 produkt-b/ Branch: v2.0.0 ``` Jedes Projekt repraesentiert ein Produkt oder Modul. Jede Branch repraesentiert eine Dokumentationsversion. ## 3. Pflichtstruktur pro Version-Branch Jeder Branch muss mindestens enthalten: ```text doku.md stepbystep.md images/ ``` Empfohlen: ```text doku.md stepbystep.md faq.md doku.yml images/ produktbild.png allgemein.png konfiguration.png ``` `doku.md` ist die Startseite der Version. `stepbystep.md` ist immer vorhanden und enthaelt die konkrete Einrichtung und Konfiguration. Weitere Markdown-Dateien auf Root-Ebene sind erlaubt und werden als Unterseiten importiert. `README.md` wird ignoriert. ## 4. Optionale Metadaten: doku.yml `doku.yml` kann Produkttitel, Version und Navigationsreihenfolge definieren. ```yaml title: Testdoku version: X.X.X revision: vXXX starface: "ab STARFACE 9.0.0.0" date: 2025-01-01 start: doku.md nav: - title: Uebersicht file: doku.md - title: Schritt fuer Schritt file: stepbystep.md - title: FAQ file: faq.md ``` Wenn `doku.yml` fehlt, nutzt das Plugin den GitLab-Projektnamen als Produkttitel, den Branchnamen als Version und erzeugt die Navigation aus den Markdown-Dateien. ## 5. Importlogik Pro Synchronisation: 1. Einstellungen laden. 2. GitLab-Gruppe abrufen. 3. Projekte abrufen. 4. Branches nach Pattern filtern, Standard `^v.*`. 5. Repository Tree pro Branch abrufen. 6. Branch nur importieren, wenn `doku.md` vorhanden ist. 7. Warnung loggen, wenn `stepbystep.md` fehlt. 8. Optional `doku.yml` lesen. 9. Root-Markdown-Dateien importieren, `README.md` ignorieren. 10. Bilder aus `images/` in die WordPress Media Library importieren. 11. Markdown nach HTML rendern. 12. Interne `.md`-Links auf WordPress-Doku-URLs umschreiben. 13. Bildreferenzen auf WordPress-Medien-URLs umschreiben. 14. Seiten als `kb_doc_page` speichern oder aktualisieren. 15. Importlog schreiben. ## 6. Markdown-Regeln Unterstuetzt werden mindestens: - Ueberschriften `#` bis `######` - Absaetze - ungeordnete und geordnete Listen - Blockquotes fuer Hinweise und Warnungen - Code-Fences - Inline-Code - Fett und kursiv - Bilder `![Alt](images/datei.png)` - Links `[Text](ziel.md)` Hinweise: ```md > **Hinweis:** Zusatzinformation ohne direkten Einfluss auf die Funktion. ``` Warnungen: ```md > **Warnung:** Kritischer Punkt oder Fallstrick bei der Konfiguration. ``` ## 7. Link- und Bildauflösung Interne Markdown-Links werden umgeschrieben: ```md [FAQ](faq.md) ``` wird zu: ```html FAQ ``` `doku.md` und `index.md` verweisen auf die Versions-Startseite. Bilder muessen relativ zum Projektroot unter `images/` liegen: ```md ![Allgemein](images/allgemein.png) ``` Das Plugin importiert diese Dateien in die WordPress Media Library und ersetzt die Bild-URLs im HTML. ## 8. WordPress-Datenmodell Das Plugin nutzt WordPress-nativ: - Custom Post Type `kb_doc_page` - Taxonomie `kb_product` - Taxonomie `kb_version` - optional Taxonomie `kb_component` Wichtige Metadaten: ```text _kb_gitlab_project_id _kb_gitlab_project_path _kb_gitlab_branch _kb_gitlab_commit_sha _kb_markdown_source_path _kb_page_checksum _kb_last_imported_at _kb_nav_order _kb_product_slug _kb_version_slug _kb_page_slug _kb_nav_tree _kb_renderer_version ``` ## 9. Frontend Standard-URL-Struktur: ```text /docs/ /docs/{product}/ /docs/{product}/{version}/ /docs/{product}/{version}/{page}/ ``` Shortcodes: ```text [kb_docs] [kb_docs_index] [kb_product_index product="produkt-a"] [kb_search] ``` `[kb_docs]` bindet die Dokumentation in eine normale WordPress-Seite ein. ## 10. Admin-Einstellungen Backend-Menue: ```text Knowledgebase Uebersicht Synchronisation Einstellungen ``` Einstellungen: - GitLab Base URL - GitLab API Token - GitLab Group Path / ID - Branch Pattern - Frontend Base Slug - Bilder mit Lightbox verlinken - Dokumentation oeffentlich anzeigen - SVG-Import erlauben - Automatische Synchronisation - Frontend-Design - Optionale eigene `theme.css` Es gibt keine Renderer-Modus-Einstellung mehr. Markdown wird direkt im Plugin verarbeitet. ## 11. Sicherheit - GitLab-Token niemals ausgeben. - Admin-Aktionen mit Capabilities absichern. - REST-API mit Berechtigungen schuetzen. - Markdown-HTML sanitizen. - Keine Shell-Aufrufe fuer Rendering. - SVG nur erlauben, wenn die Option aktiv ist. - Keine privaten GitLab-URLs im Frontend leaken. - Logs ohne Secrets speichern. ## 12. Akzeptanzkriterien - Plugin heisst **KB Markdown Importer**. - Plugin laesst sich aktivieren. - Admin-Menue erscheint. - GitLab-Verbindungstest funktioniert. - Projekt mit Branch `v...` wird erkannt. - Branch mit `doku.md`, `stepbystep.md` und `images/` wird importiert. - `doku.md` wird Startseite der Version. - `stepbystep.md` wird als Unterseite importiert. - Weitere Root-`.md`-Dateien werden als Unterseiten importiert. - Bilder aus `images/` werden importiert und im HTML ersetzt. - Interne `.md`-Links funktionieren. - `/docs/` zeigt die Dokumentationsuebersicht. - `/docs/{product}/{version}/` zeigt die Startseite. - Synchronisation dupliziert unveraenderte Seiten nicht. - Importfehler werden im Backend-Log sichtbar. ## 13. Nicht-Ziele - Kein Legacy-Rendering. - Keine Legacy-Kompatibilitaet im Importpfad. - Kein externer Render-Service. - Kein lokaler CLI-Renderer. - Kein Live-Rendering aus GitLab bei jedem Seitenaufruf. - Kein Gutenberg-Editor fuer Dokumentationsquellen. ## 14. Beispielprojekt Ein Beispiel fuer die neue Struktur liegt im Repository unter: ```text markdown-beispielprojekt/ ``` Diese Struktur dient als Vorlage fuer neue GitLab-Dokumentationsprojekte.