# 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.

## 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.
