adocWP/codex.md

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:

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:

doku.md
stepbystep.md
images/

Empfohlen:

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.

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:

> **Hinweis:** Zusatzinformation ohne direkten Einfluss auf die Funktion.

Warnungen:

> **Warnung:** Kritischer Punkt oder Fallstrick bei der Konfiguration.

7. Link- und Bildauflösung

Interne Markdown-Links werden umgeschrieben:

[FAQ](faq.md)

wird zu:

<a href="/docs/produkt/version/faq/">FAQ</a>

doku.md und index.md verweisen auf die Versions-Startseite.

Bilder muessen relativ zum Projektroot unter images/ liegen:

![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:

_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:

/docs/
/docs/{product}/
/docs/{product}/{version}/
/docs/{product}/{version}/{page}/

Shortcodes:

[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:

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:

markdown-beispielprojekt/

Diese Struktur dient als Vorlage fuer neue GitLab-Dokumentationsprojekte.