adocWP/codex.md

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:

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:

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:

v1.0.0
v1.2.0
v2.0.0

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

Beispiel:

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:

kb-antora-importer

Vorgeschlagene Hauptdatei:

kb-antora-importer.php

Vorgeschlagene Struktur:

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:

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

Produkt A
Produkt B
STARFACE Modul X
Yeastar Integration Y

Taxonomie: kb_version

Repräsentiert Dokumentationsversionen.

Beispiele:

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:

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:

Einstellungen → Knowledgebase

Oder als eigener Menüpunkt:

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

Benötigte Einstellungen:

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:

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:

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

Verwendung:

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:

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

Später optional:

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:

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

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:

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

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

Soll werden zu:

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

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

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

Dies soll als Option steuerbar sein:

Bilder automatisch mit Lightbox verlinken: ja/nein

---

10. Frontend-Ausgabe

Die Dokumentation soll unter einem konfigurierbaren Basis-Slug erscheinen.

Standard:

/docs/

URL-Struktur:

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

Beispiele:

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

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

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:

Deaktiviert
Stündlich
Täglich
Wöchentlich

12.3 Webhook später

Optional soll vorbereitet werden:

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

Als veraltet markieren
In Papierkorb verschieben
Hart löschen
Ignorieren

MVP-Standard:

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:

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:

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:

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

15.2 Synchronisationsseite

Anzeigen:

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

15.3 Einstellungen

Felder:

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:

kb-antora/v1

Routen:

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:

INFO
WARNING
ERROR
DEBUG optional

Zu loggende Ereignisse:

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:

Obyte\Knowledgebase\

Oder neutral:

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:

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:

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

/docs/produkt-a/

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

Dokuseite:

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

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

Kontext:

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

Ziel:

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

---

28. Beispiel für Bildauflösung

Quelle:

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

Suchpfad:

modules/ROOT/images/screenshot-login.png

Ziel:

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

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.