# Codex-Anweisung: WordPress-Plugin für GitLab-/Antora-basierte Knowledgebase

## 1. Projektziel

Entwickle ein WordPress-Plugin, das technische Produktdokumentationen aus einer GitLab-Gruppe einliest, verarbeitet und innerhalb eines WordPress-basierten Kundenportals veröffentlicht.

Die vorhandene Dokumentationsstruktur basiert auf **AsciiDoc (`.adoc`)** und ist grundsätzlich für **Antora** ausgelegt. In GitLab existiert eine Gruppe namens `knowledgebase`. Darin liegen mehrere GitLab-Projekte, jeweils ein Projekt pro Produkt oder Modul. Innerhalb jedes Projekts existieren mehrere Branches, wobei jede Branch eine Dokumentationsversion repräsentiert.

Das Plugin soll diese GitLab-Struktur lesen, relevante Branches erkennen, `.adoc`-Dateien importieren, in HTML rendern und als durchsuchbare, versionierte Dokumentation innerhalb von WordPress bereitstellen.

Das Ziel ist **nicht**, Antora vollständig nachzubauen. Das Ziel ist ein WordPress-native Plugin, das die bestehende Antora-kompatible Struktur möglichst gut versteht und daraus eine konsistente Kundenportal-Dokumentation erzeugt.

---

## 2. Ausgangssituation

### 2.1 GitLab-Struktur

GitLab enthält eine Gruppe:

```text
knowledgebase/
├── produkt-a/
│   ├── Branch: v1.0.0
│   ├── Branch: v1.1.0
│   └── Branch: v2.0.0
├── produkt-b/
│   ├── Branch: v3.4.0
│   └── Branch: v3.5.0
└── produkt-c/
    └── Branch: v1.0.0
```

Jedes Projekt enthält eine Antora-kompatible Dokumentationsstruktur, zum Beispiel:

```text
antora.yml
modules/
└── ROOT/
    ├── pages/
    │   ├── index.adoc
    │   ├── installation.adoc
    │   └── configuration.adoc
    ├── images/
    │   └── screenshot.png
    ├── partials/
    └── examples/
```

Die genaue Struktur kann je nach Produkt variieren, soll aber an Antora angelehnt bleiben.

### 2.2 Versionierung

Die Versionierung erfolgt derzeit über Git-Branches. Branches, die als Dokumentationsversion gelten, beginnen üblicherweise mit `v`, zum Beispiel:

```text
v1.0.0
v1.2.0
v2.0.0
```

Die eigentliche Anzeigenversion kann zusätzlich aus der jeweiligen `antora.yml` gelesen werden.

Beispiel:

```yaml
name: produkt-a
title: Produkt A
version: 1.2.0
nav:
  - modules/ROOT/nav.adoc
```

Das Plugin soll Branch- und `antora.yml`-Informationen kombinieren.

---

## 3. Grundanforderungen

Das Plugin soll folgende Kernfunktionen bereitstellen:

1. Verbindung zu GitLab über API-Token.
2. Auswahl einer GitLab-Gruppe, zum Beispiel `knowledgebase`.
3. Auslesen aller Projekte innerhalb dieser Gruppe.
4. Erkennen relevanter Dokumentationsbranches.
5. Auslesen der `antora.yml` pro Projekt und Branch.
6. Auslesen der Antora-typischen Dateistruktur.
7. Importieren und Rendern von `.adoc`-Dateien nach HTML.
8. Speichern der gerenderten Dokumentationsseiten in WordPress.
9. Abbildung von Produkten, Versionen, Navigationsstruktur und Seiten.
10. Anzeige der Dokumentation im WordPress-Frontend.
11. Suche innerhalb der importierten Dokumentation.
12. Synchronisation per manuellem Button, WP-Cron und optional Webhook.
13. Rechte-/Zugriffssteuerung passend für ein Kundenportal.

---

## 4. Technische Zielarchitektur

Das Plugin soll als eigenständiges WordPress-Plugin entwickelt werden.

Vorgeschlagener Plugin-Name:

```text
kb-antora-importer
```

Vorgeschlagene Hauptdatei:

```text
kb-antora-importer.php
```

Vorgeschlagene Struktur:

```text
kb-antora-importer/
├── kb-antora-importer.php
├── composer.json
├── readme.md
├── uninstall.php
├── assets/
│   ├── css/
│   │   └── frontend.css
│   └── js/
│       └── frontend.js
├── includes/
│   ├── Plugin.php
│   ├── Admin/
│   │   ├── SettingsPage.php
│   │   ├── SyncPage.php
│   │   └── StatusPage.php
│   ├── GitLab/
│   │   ├── GitLabClient.php
│   │   ├── GitLabProject.php
│   │   └── GitLabBranch.php
│   ├── Antora/
│   │   ├── AntoraParser.php
│   │   ├── AntoraYamlReader.php
│   │   ├── AntoraNavParser.php
│   │   └── AntoraResourceResolver.php
│   ├── AsciiDoc/
│   │   ├── AsciiDocRenderer.php
│   │   └── ShortcodeTransformer.php
│   ├── Import/
│   │   ├── ImportManager.php
│   │   ├── ImportJob.php
│   │   ├── ImportLogger.php
│   │   └── Checksum.php
│   ├── Repository/
│   │   ├── ProductRepository.php
│   │   ├── VersionRepository.php
│   │   └── PageRepository.php
│   ├── Frontend/
│   │   ├── Router.php
│   │   ├── TemplateLoader.php
│   │   ├── SearchController.php
│   │   └── BreadcrumbBuilder.php
│   └── Access/
│       └── AccessController.php
└── templates/
    ├── documentation-index.php
    ├── product.php
    ├── version.php
    ├── page.php
    └── search.php
```

---

## 5. WordPress-Datenmodell

Es gibt zwei mögliche Umsetzungswege. Codex soll zunächst Variante A umsetzen, sofern nichts dagegenspricht.

### 5.1 Variante A: Custom Post Types

Verwende Custom Post Types für die Dokumentationsseiten.

#### Custom Post Type: `kb_doc_page`

Repräsentiert eine gerenderte Dokumentationsseite.

Wichtige Meta-Felder:

```text
_kb_gitlab_project_id
_kb_gitlab_project_path
_kb_gitlab_branch
_kb_gitlab_commit_sha
_kb_antora_component
_kb_antora_component_title
_kb_antora_version
_kb_antora_module
_kb_antora_page_path
_kb_antora_source_path
_kb_page_checksum
_kb_last_imported_at
_kb_nav_order
_kb_parent_page_path
```

#### Taxonomie: `kb_product`

Repräsentiert Produkt oder Modul.

Beispiele:

```text
Produkt A
Produkt B
STARFACE Modul X
Yeastar Integration Y
```

#### Taxonomie: `kb_version`

Repräsentiert Dokumentationsversionen.

Beispiele:

```text
1.0.0
1.2.0
2.0.0
```

#### Taxonomie: `kb_component`

Optional, falls Antora-Komponenten explizit abgebildet werden sollen.

---

### 5.2 Variante B: Eigene Datenbanktabellen

Diese Variante ist für spätere Skalierung möglich, soll aber nicht initial umgesetzt werden, außer WordPress-Performance oder Datenmodellgründe erzwingen es.

Mögliche Tabellen:

```text
wp_kb_products
wp_kb_versions
wp_kb_pages
wp_kb_assets
wp_kb_import_logs
```

Für den MVP soll jedoch WordPress-nativ mit Custom Post Types gearbeitet werden.

---

## 6. GitLab-Integration

### 6.1 Konfiguration im WordPress-Backend

Erstelle eine Admin-Seite unter:

```text
Einstellungen → Knowledgebase
```

Oder als eigener Menüpunkt:

```text
Knowledgebase
├── Übersicht
├── Synchronisation
├── Einstellungen
└── Import-Logs
```

Benötigte Einstellungen:

```text
GitLab Base URL
GitLab API Token
GitLab Group Path oder Group ID
Branch Pattern, Standard: ^v\d+\.\d+\.\d+.*$
Standard-Synchronisationsintervall
Frontend-Basis-Slug, Standard: /docs/
Zugriffsbeschränkung aktiv/inaktiv
```

Beispiele:

```text
GitLab Base URL: https://git.example.de
GitLab Group Path: knowledgebase
Branch Pattern: ^v.*
Frontend-Basis-Slug: docs
```

### 6.2 API-Zugriff

Implementiere eine Klasse `GitLabClient`.

Aufgaben:

1. Authentifizierung per Private Token oder Bearer Token.
2. Abrufen der Gruppe.
3. Abrufen aller Projekte innerhalb der Gruppe.
4. Abrufen aller Branches pro Projekt.
5. Filtern der Branches nach Pattern.
6. Abrufen einzelner Dateien per Repository Files API.
7. Abrufen von Repository Trees.
8. Abrufen von Raw File Content.
9. Fehlerbehandlung für 401, 403, 404, 429 und 5xx.
10. Optional: einfache Rate-Limit-Behandlung.

Der Token darf niemals im Klartext ausgegeben werden.

Speicherung des Tokens:

- möglichst verschlüsselt oder zumindest über WordPress Options API geschützt,
- niemals in Logs,
- niemals im Frontend,
- niemals in Fehlermeldungen.

---

## 7. Antora-Kompatibilität

Das Plugin soll zentrale Antora-Konzepte verstehen, ohne Antora vollständig nachzubauen.

### 7.1 `antora.yml`

Pro Projekt und Branch soll die Datei `antora.yml` gelesen werden.

Relevante Felder:

```yaml
name: product-name
title: Product Title
version: 1.2.0
nav:
  - modules/ROOT/nav.adoc
```

Verwendung:

```text
name      → interner Komponenten-/Produktname
title     → Anzeigename im Frontend
version   → Anzeigenversion
nav       → Navigationsdateien
```

Falls `antora.yml` fehlt:

- Projekt nicht hart abbrechen,
- Fehler sauber loggen,
- Projekt/Branch überspringen oder Fallback verwenden,
- Importstatus anzeigen.

### 7.2 Module

Unterstütze mindestens:

```text
modules/ROOT/pages/
modules/ROOT/images/
modules/ROOT/partials/
modules/ROOT/examples/
modules/ROOT/nav.adoc
```

Später optional:

```text
modules/<module-name>/pages/
modules/<module-name>/images/
modules/<module-name>/partials/
modules/<module-name>/examples/
```

MVP-Anforderung:

- `ROOT`-Modul vollständig unterstützen.
- Weitere Module erkennen, aber zunächst einfach als zusätzliche Bereiche importieren.

### 7.3 Navigation

Antora nutzt häufig `nav.adoc`.

Beispiel:

```adoc
* xref:index.adoc[Einführung]
* Installation
** xref:installation.adoc[Installation]
** xref:configuration.adoc[Konfiguration]
```

Das Plugin soll daraus eine hierarchische Navigation erzeugen.

Anforderungen:

1. `xref:`-Links erkennen.
2. Titel aus eckigen Klammern lesen.
3. Verschachtelung anhand der Sternchen-Ebene erkennen.
4. Seitenreihenfolge speichern.
5. Nicht verlinkte Überschriften als Navigationsgruppen darstellen.
6. Navigation im Frontend als Sidebar ausgeben.

---

## 8. AsciiDoc-Rendering

### 8.1 Grundsatz

`.adoc`-Dateien müssen in HTML gerendert werden.

Mögliche Renderer:

1. PHP-basierter AsciiDoc-Parser, falls ausreichend stabil.
2. Externer CLI-Aufruf zu Asciidoctor, falls verfügbar.
3. Container-/Service-basierter Renderer als spätere Option.

Für den MVP soll eine robuste und realistische Lösung gewählt werden. Wenn ein vollständiger AsciiDoc-Renderer in PHP nicht zuverlässig verfügbar ist, soll das Plugin optional `asciidoctor` per CLI verwenden können.

### 8.2 Renderer-Konfiguration

Backend-Einstellung:

```text
Renderer Mode:
- PHP Renderer
- Asciidoctor CLI
- External Render Service später
```

Wenn `asciidoctor` CLI verwendet wird:

- Pfad konfigurierbar machen,
- Verfügbarkeit prüfen,
- Fehlermeldung im Status anzeigen,
- keine unsicheren Shell-Aufrufe,
- Eingaben escapen,
- temporäre Dateien sicher speichern und löschen.

### 8.3 Mindestfeatures

Folgende AsciiDoc-Features sollen unterstützt werden:

```text
Überschriften
Absätze
Listen
Tabellen
Quellcodeblöcke
Admonitions / Hinweise
Bilder
Interne xref-Links
Externe Links
Includes / Partials, soweit lokal auflösbar
```

### 8.4 Link-Transformation

Antora-/AsciiDoc-Links müssen in WordPress-URLs umgeschrieben werden.

Beispiele:

```adoc
xref:installation.adoc[Installation]
image::screenshot.png[Screenshot]
```

Soll werden zu:

```html
<a href="/docs/produkt-a/1.2.0/installation/">Installation</a>
<img src="..." alt="Screenshot">
```

Bei fehlendem Ziel:

- Link markieren,
- Importwarnung loggen,
- Frontend nicht hart abbrechen.

---

## 9. Assets und Bilder

Bilder aus Antora-Strukturen müssen importiert oder proxyfähig ausgeliefert werden.

### 9.1 Import in WordPress Media Library

Bevorzugt für MVP:

1. Bilder aus `modules/*/images/` erkennen.
2. In die WordPress Media Library importieren.
3. Medien-ID speichern.
4. Bildreferenzen im HTML auf WordPress-Medien-URLs umschreiben.
5. Checksums nutzen, damit Bilder nicht bei jedem Sync dupliziert werden.

### 9.2 Unterstützte Dateitypen

Mindestens:

```text
.png
.jpg
.jpeg
.gif
.svg
.webp
```

SVG nur zulassen, wenn sicher behandelt oder explizit erlaubt.

### 9.3 Lightbox-Kompatibilität

Das gerenderte HTML soll optional CSS-Klassen oder Attribute erhalten, damit Bilder im Frontend mit einer Lightbox geöffnet werden können.

Beispiel:

```html
<a href="FULL_IMAGE_URL" class="kb-lightbox">
  <img src="IMAGE_URL" alt="...">
</a>
```

Dies soll als Option steuerbar sein:

```text
Bilder automatisch mit Lightbox verlinken: ja/nein
```

---

## 10. Frontend-Ausgabe

Die Dokumentation soll unter einem konfigurierbaren Basis-Slug erscheinen.

Standard:

```text
/docs/
```

URL-Struktur:

```text
/docs/
/docs/{product}/
/docs/{product}/{version}/
/docs/{product}/{version}/{page}/
```

Beispiele:

```text
/docs/starface-modul-x/
/docs/starface-modul-x/2.1.0/
/docs/starface-modul-x/2.1.0/installation/
```

### 10.1 Frontend-Komponenten

Jede Dokumentationsseite soll enthalten:

1. Produktname.
2. Versionsauswahl.
3. Sidebar-Navigation.
4. Breadcrumbs.
5. Hauptinhalt.
6. Optional: Inhaltsverzeichnis der Seite.
7. Optional: Hinweis, wenn es eine neuere Version gibt.
8. Suchfeld innerhalb der Dokumentation.

### 10.2 Shortcodes oder Blöcke

Zusätzlich sollen Shortcodes bereitgestellt werden:

```text
[kb_docs_index]
[kb_product_index product="produkt-a"]
[kb_search]
```

Optional später Gutenberg-Blöcke.

---

## 11. Suche

Für den MVP reicht eine WordPress-native Suche über den Custom Post Type `kb_doc_page`.

Anforderungen:

1. Suche nur innerhalb der Dokumentation.
2. Filter nach Produkt.
3. Filter nach Version.
4. Treffer mit Titel, Auszug und Produkt-/Versionskontext anzeigen.

Später optional:

- Relevanzranking,
- Volltextindex,
- externe Search Engine,
- Synonyme,
- Suchstatistiken.

---

## 12. Synchronisation

### 12.1 Manuelle Synchronisation

Backend-Seite:

```text
Knowledgebase → Synchronisation
```

Funktionen:

1. Alle Projekte synchronisieren.
2. Einzelnes Projekt synchronisieren.
3. Einzelne Version/Branch synchronisieren.
4. Dry Run durchführen.
5. Import-Log anzeigen.

### 12.2 WP-Cron

Konfigurierbare automatische Synchronisation:

```text
Deaktiviert
Stündlich
Täglich
Wöchentlich
```

### 12.3 Webhook später

Optional soll vorbereitet werden:

```text
/wp-json/kb-antora/v1/gitlab-webhook
```

Der Webhook soll später GitLab Push Events empfangen können.

Für MVP nur vorbereiten oder als einfache Version implementieren.

---

## 13. Importlogik

### 13.1 Importablauf

Pro Synchronisation:

1. Einstellungen laden.
2. GitLab-Verbindung prüfen.
3. Gruppe abrufen.
4. Projekte abrufen.
5. Pro Projekt Branches abrufen.
6. Branches nach Pattern filtern.
7. Pro Branch `antora.yml` abrufen.
8. Version und Produkttitel bestimmen.
9. Repository Tree abrufen.
10. `.adoc`-Dateien unter `modules/*/pages/` finden.
11. Assets unter `modules/*/images/` finden.
12. Navigation aus `nav.adoc` lesen.
13. Assets importieren.
14. `.adoc` rendern.
15. Links und Bilder umschreiben.
16. WordPress-Posts erstellen oder aktualisieren.
17. Veraltete Seiten markieren.
18. Importlog schreiben.

### 13.2 Update-Erkennung

Verwende Checksums und/oder Git Commit SHA.

Wenn sich eine Datei nicht geändert hat:

- nicht neu rendern,
- nicht unnötig WordPress-Post aktualisieren,
- Importzeit sparen.

### 13.3 Löschverhalten

Wenn eine Seite in GitLab nicht mehr existiert:

Optionen:

```text
Als veraltet markieren
In Papierkorb verschieben
Hart löschen
Ignorieren
```

MVP-Standard:

```text
Als veraltet markieren
```

---

## 14. Rechte und Kundenportal-Integration

Das Plugin wird in einem Kundenportal verwendet. Dokumentationen dürfen je nach Portalstruktur nicht immer öffentlich sein.

### 14.1 Zugriff

Backend-Option:

```text
Dokumentation öffentlich anzeigen: ja/nein
```

Wenn nein:

- nur eingeloggte Benutzer dürfen Dokumentation sehen.

Später optional:

- Zugriff nach Produkt,
- Zugriff nach Kundengruppe,
- Zugriff nach WordPress-Rolle,
- Zugriff nach Membership-/Portal-Plugin.

### 14.2 WordPress Capabilities

Neue Capabilities:

```text
manage_kb_docs
view_kb_docs
sync_kb_docs
```

Administratoren erhalten alle Capabilities automatisch.

---

## 15. Admin-UX

Das Backend soll technisch sauber, aber nicht überladen sein.

### 15.1 Übersichtsseite

Anzeigen:

```text
GitLab-Verbindungsstatus
Anzahl Projekte
Anzahl importierte Produkte
Anzahl Versionen
Anzahl Seiten
Letzte Synchronisation
Letzter Fehler
Renderer-Status
```

### 15.2 Synchronisationsseite

Anzeigen:

```text
Button: Alles synchronisieren
Button: Dry Run
Projektliste mit Sync-Button pro Projekt
Fortschritts-/Statusanzeige
Importlogs
```

### 15.3 Einstellungen

Felder:

```text
GitLab Base URL
GitLab Token
GitLab Group Path / ID
Branch Pattern
Docs Base Slug
Renderer Mode
Asciidoctor Path
Lightbox für Bilder
Öffentlich / nur eingeloggte Benutzer
Cron-Intervall
```

Alle Eingaben validieren und escapen.

---

## 16. REST API

Erstelle eine kleine interne REST API für Admin-Aktionen.

Namespace:

```text
kb-antora/v1
```

Routen:

```text
GET  /status
POST /sync
POST /sync/project
GET  /search
POST /gitlab-webhook optional
```

Alle schreibenden Endpoints müssen Nonce- und Capability-Prüfung verwenden.

---

## 17. Sicherheit

Besondere Anforderungen:

1. GitLab-Token niemals ausgeben.
2. Alle Admin-Aktionen mit Capability Checks absichern.
3. REST-API mit Nonces und Berechtigungen schützen.
4. Gerendertes HTML sanitizen.
5. Keine ungeprüften Shell-Befehle.
6. Temporäre Dateien sicher behandeln.
7. SVG nur nach Sanitizing oder deaktiviert.
8. Keine privaten GitLab-URLs im Frontend leaken.
9. Keine Stacktraces im Frontend.
10. Logs ohne Secrets speichern.

---

## 18. Performance

Die Dokumentation kann viele Produkte, Versionen und Seiten enthalten. Deshalb:

1. Imports in Batches ausführen.
2. Lange Prozesse nicht direkt in einem einzelnen HTTP-Request blockieren, wenn vermeidbar.
3. Checksums verwenden.
4. Caching für Navigationsbäume.
5. Caching für Produkt-/Versionslisten.
6. WP_Query effizient halten.
7. Nur geänderte Dateien neu rendern.
8. Importlogs begrenzen oder rotieren.

Für den MVP darf die manuelle Synchronisation zunächst sequentiell laufen, solange der Code so strukturiert ist, dass Batch-/Queue-Verarbeitung später leicht ergänzt werden kann.

---

## 19. Fehlerbehandlung und Logging

Implementiere Importlogs mit Schweregraden:

```text
INFO
WARNING
ERROR
DEBUG optional
```

Zu loggende Ereignisse:

```text
GitLab-Verbindung erfolgreich/fehlgeschlagen
Projekt gefunden
Branch gefunden
Branch übersprungen
antora.yml gefunden/fehlt/fehlerhaft
nav.adoc gefunden/fehlt/fehlerhaft
Seite importiert
Seite aktualisiert
Seite unverändert
Asset importiert
Linkziel fehlt
Rendering fehlgeschlagen
Synchronisation abgeschlossen
```

Logs sollen im Backend sichtbar sein.

---

## 20. MVP-Umfang

Der erste funktionsfähige Stand soll Folgendes können:

1. Plugin installierbar und aktivierbar.
2. Admin-Einstellungen für GitLab-Zugang.
3. Verbindungstest zu GitLab.
4. Projekte einer GitLab-Gruppe abrufen.
5. Branches nach Pattern `^v.*` erkennen.
6. `antora.yml` lesen.
7. `modules/ROOT/pages/*.adoc` importieren.
8. Einfache `.adoc`-Dateien nach HTML rendern.
9. Bilder aus `modules/ROOT/images/` importieren.
10. Interne `xref:`-Links umschreiben.
11. Seiten als `kb_doc_page` speichern.
12. Frontend-Ausgabe unter `/docs/{product}/{version}/{page}/`.
13. Produktindex und Versionsauswahl anzeigen.
14. Einfache Sidebar aus `nav.adoc` erzeugen.
15. Manuelle Synchronisation im Backend.
16. Importlogs anzeigen.

---

## 21. Nicht-Ziele für den MVP

Nicht im ersten Schritt umsetzen:

1. Vollständige Antora-Engine nachbauen.
2. Mehrsprachigkeit.
3. Komplexe Berechtigung nach Kunde/Produkt.
4. Externe Suchmaschine.
5. Live-Rendering bei jedem Seitenaufruf.
6. GitLab-Webhook mit vollständiger Eventlogik.
7. Gutenberg-Blöcke.
8. Visueller Editor für `.adoc`.
9. Merge-Request-Workflow.
10. Antora UI Bundles vollständig unterstützen.

---

## 22. Coding-Standards

Bitte nach WordPress-Standards entwickeln:

1. PHP 8.1+ kompatibel.
2. WordPress Coding Standards berücksichtigen.
3. Namespaces verwenden.
4. Klassen sauber trennen.
5. Keine Businesslogik in Templates.
6. Keine direkten `$_POST`/`$_GET`-Zugriffe ohne Sanitizing.
7. Alle Ausgaben escapen.
8. Transients/Options API sinnvoll verwenden.
9. Composer Autoloading nutzen, falls sinnvoll.
10. Code dokumentieren, aber nicht überkommentieren.

Namespace-Vorschlag:

```php
Obyte\Knowledgebase\
```

Oder neutral:

```php
KbAntoraImporter\
```

---

## 23. Akzeptanzkriterien

Der MVP gilt als erfolgreich, wenn folgende Tests bestehen:

### 23.1 Installation

- Plugin lässt sich in WordPress aktivieren.
- Admin-Menü erscheint.
- Keine PHP-Warnings oder Fatal Errors.

### 23.2 GitLab-Verbindung

- GitLab Base URL und Token können gespeichert werden.
- Verbindungstest funktioniert.
- Gruppe `knowledgebase` kann gelesen werden.
- Projekte werden angezeigt.

### 23.3 Import

- Mindestens ein Projekt mit Branch `v1.0.0` wird erkannt.
- `antora.yml` wird gelesen.
- `.adoc`-Seiten werden importiert.
- Bilder werden importiert oder korrekt referenziert.
- Seiten erscheinen als `kb_doc_page`.

### 23.4 Frontend

- `/docs/` zeigt eine Dokumentationsübersicht.
- `/docs/{product}/` zeigt Produktversionen.
- `/docs/{product}/{version}/` zeigt die Versionsübersicht.
- `/docs/{product}/{version}/{page}/` zeigt die gerenderte Seite.
- Sidebar-Navigation funktioniert.
- Interne Links funktionieren.

### 23.5 Sync

- Erneuter Import dupliziert keine Seiten.
- Geänderte Seiten werden aktualisiert.
- Unveränderte Seiten bleiben unverändert.
- Fehler werden im Log sichtbar.

---

## 24. Entwicklungsreihenfolge

Bitte in dieser Reihenfolge entwickeln:

1. Plugin-Grundstruktur und Autoloading.
2. Admin-Menü und Einstellungsseite.
3. GitLabClient mit Verbindungstest.
4. Projekt- und Branch-Erkennung.
5. `antora.yml` Reader.
6. Repository Tree Reader.
7. Importmodell für Produkte, Versionen und Seiten.
8. Custom Post Type und Taxonomien.
9. Einfacher AsciiDoc Renderer.
10. Link- und Bild-Umschreibung.
11. Frontend-Routing und Templates.
12. Navigation aus `nav.adoc`.
13. Importlogs.
14. Suche.
15. Cron/Webhook-Grundlage.
16. Sicherheits- und Performance-Review.

---

## 25. Wichtige Architekturentscheidung

Das Plugin soll Dokumentation **nicht bei jedem Seitenaufruf live aus GitLab rendern**.

Stattdessen:

```text
GitLab → Sync/Import → WordPress-Speicherung → Frontend-Ausgabe aus WordPress
```

Begründung:

1. Bessere Performance.
2. Kein GitLab-API-Zugriff bei jedem Kundenaufruf.
3. Bessere WordPress-Suche.
4. Bessere Kontrolle über Zugriffsrechte.
5. Stabileres Kundenportal bei GitLab-Ausfällen.

---

## 26. Beispiel-Frontend-Struktur

Dokumentationsübersicht:

```text
/docs/

Knowledgebase
├── Produkt A
│   ├── Version 1.0.0
│   └── Version 1.2.0
├── Produkt B
│   └── Version 3.5.0
└── Produkt C
    └── Version 1.0.0
```

Produktseite:

```text
/docs/produkt-a/

Produkt A
Verfügbare Versionen:
- 2.0.0 aktuell
- 1.2.0
- 1.0.0
```

Dokuseite:

```text
/docs/produkt-a/2.0.0/installation/

[Sidebar Navigation]
Produkt A / 2.0.0 / Installation

<h1>Installation</h1>
...
```

---

## 27. Beispiel für interne Linkauflösung

Quelle:

```adoc
Weitere Informationen findest du unter xref:configuration.adoc[Konfiguration].
```

Kontext:

```text
Produkt: produkt-a
Version: 2.0.0
Aktuelle Seite: installation.adoc
```

Ziel:

```html
Weitere Informationen findest du unter <a href="/docs/produkt-a/2.0.0/configuration/">Konfiguration</a>.
```

---

## 28. Beispiel für Bildauflösung

Quelle:

```adoc
image::screenshot-login.png[Login-Screenshot]
```

Suchpfad:

```text
modules/ROOT/images/screenshot-login.png
```

Ziel:

```html
<figure class="kb-image">
  <a href="..." class="kb-lightbox">
    <img src="..." alt="Login-Screenshot">
  </a>
</figure>
```

---

## 29. Erwartetes Ergebnis

Am Ende soll ein installierbares WordPress-Plugin entstehen, das vorhandene GitLab-/Antora-Dokumentationen aus der Gruppe `knowledgebase` importiert und im WordPress-Kundenportal als strukturierte, versionierte Knowledgebase veröffentlicht.

Das Plugin soll technisch sauber, wartbar und erweiterbar sein. Der MVP soll bewusst pragmatisch bleiben, aber die Architektur muss spätere Erweiterungen erlauben, insbesondere:

```text
kundenspezifische Berechtigungen
bessere Suche
GitLab-Webhooks
mehrere Module
mehrsprachige Dokumentation
Gutenberg-Blöcke
externen Render-Service
```

---

## 30. Zusätzliche Hinweise für Codex

- Arbeite inkrementell.
- Nach jeder größeren Änderung soll der Code lauffähig bleiben.
- Keine Platzhalterfunktionen ohne klare TODO-Kommentare.
- Keine unnötigen Framework-Abhängigkeiten.
- WordPress-Kompatibilität priorisieren.
- Fehler lieber sichtbar loggen als still verschlucken.
- Sicherheitsrelevante Eingaben immer validieren, sanitizen und escapen.
- Plugin so entwickeln, dass es später in einem produktiven Kundenportal betrieben werden kann.