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:

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

```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.
Die Ausgabe ist als Doku-App aufgebaut: Startseite rechts, persistente Sidebar links. Die Sidebar zeigt alle Produkte und fuer die aktive Version alle Seiten, sodass man direkt von der Portalseite in die konkrete Doku springen kann. Die Version wird nicht in der Sidebar gewechselt, sondern per Dropdown im Kopf der jeweiligen Dokumentationsseite.

Die Dokumentations-Startseite ist im Backend anpassbar. Sie enthaelt einen frei pflegbaren Anleitungstext zum Umgang mit der Dokumentation und einen Produktupdate-Bereich. Produktupdates werden nicht bei jedem Seitenaufruf live geladen, sondern per OLM-Changelog-Sync in WordPress gespeichert und danach aus der Datenbank gelesen.
Der OLM-Changelog-Sync bildet die bestehende Python-Logik nach: `POST /login`, danach paginiert `/api/rest/v1/product?page=N&size=1`, sammelt `downloads[].id` und liest pro Download `/api/rest/v1/download/field/{id}?page=N&size=1`. Importiert werden nur Eintraege mit `qa=true`, `publishedAt`, veroeffentlichtem Produkt und nicht ignorierter `productNo`. Der Zeitraum und die ignorierten OLM-Nummern sind im Backend konfigurierbar.
Der Changelog-Sync laeuft manuell ueber die Synchronisationsseite und automatisch mit dem bestehenden Synchronisationsintervall. `Sync All` fuehrt sowohl den GitLab-Doku-Import als auch den OLM-Changelog-Sync aus.
Unter `Produkte` koennen importierte GitLab-Produkte einem gemeinsamen Frontend-Produkt zugeordnet werden. Damit lassen sich mehrere Teildokumentationen, z. B. App, Modul und Exporter, als ein Produkt in der Dokumentation anzeigen. Pro Produkt/Modul kann ausserdem eine Kategorie fuer die Frontend-Gruppierung gepflegt werden.
Die Sidebar zeigt die aktive Seitennavigation immer oben separat an. Die komplette Produktliste ist darunter nach Kategorien gruppiert, damit Nutzer nicht in langen Produktlisten zur aktuellen Seitennavigation scrollen muessen.

## 10. Admin-Einstellungen

Backend-Menue:

```text
Knowledgebase
  Uebersicht
  Produkte
  Synchronisation
  Einstellungen
```

Unter `Produkte` koennen importierte Produkte in einer Tabelle gesammelt verwaltet und mit einem `Save all`-Button gespeichert werden. Admins koennen Frontend-Produkt, Teildokumentation und Kategorie pflegen oder ausgewaehlte fehlerhafte Produkte inklusive der zugehoerigen Doku-Seiten in den Papierkorb verschieben.

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`
- Dokumentations-Startseite mit Anleitungstext
- OLM-Zugangsdaten fuer den Changelog-Sync
- OLM-Changelog-Zeitraum und ignorierte OLM-Nummern
- Produktmanagement mit Frontend-Produkt, Teildokumentation und Kategorie

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.
- `[kb_docs]` zeigt eine Startseite mit persistenter Produkt- und Seitennavigation sowie Versionswechsel per Dropdown in der Dokumentationsseite.
- Die Dokumentations-Startseite zeigt den im Backend gepflegten Anleitungstext.
- Die Dokumentations-Startseite zeigt die per OLM-Changelog-Sync gespeicherten Produktupdates.
- OLM-Changelog-Daten koennen manuell und per bestehendem Sync-Intervall aktualisiert werden.
- Mehrere importierte GitLab-Produkte koennen im Frontend als ein Produkt zusammengefasst werden.
- Produkte koennen Kategorien zugeordnet werden.
- `/docs/{product}/{version}/` zeigt die Startseite.
- Im Backend koennen Produkte bei fehlerhaften Importen verwaltet und entfernt werden.
- 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.