1163 lines
24 KiB
Markdown
1163 lines
24 KiB
Markdown
# 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.
|
|
|