diff --git a/codex.md b/codex.md index 472d017..a34926b 100644 --- a/codex.md +++ b/codex.md @@ -1,545 +1,173 @@ -# Codex-Anweisung: WordPress-Plugin für GitLab-/Antora-basierte Knowledgebase +# 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 veröffentlicht. +Entwickle ein WordPress-Plugin, das technische Produktdokumentationen aus einer GitLab-Gruppe einliest, verarbeitet und innerhalb eines WordPress-basierten Kundenportals veroeffentlicht. -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. +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. -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. +## 2. GitLab-Struktur -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: +GitLab enthaelt eine Gruppe, zum Beispiel: ```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 + produkt-a/ + Branch: v1.0.0 + Branch: v1.1.0 + produkt-b/ + Branch: v2.0.0 ``` -Jedes Projekt enthält eine Antora-kompatible Dokumentationsstruktur, zum Beispiel: +Jedes Projekt repraesentiert ein Produkt oder Modul. Jede Branch repraesentiert eine Dokumentationsversion. + +## 3. Pflichtstruktur pro Version-Branch + +Jeder Branch muss mindestens enthalten: ```text -antora.yml -modules/ -└── ROOT/ - ├── pages/ - │ ├── index.adoc - │ ├── installation.adoc - │ └── configuration.adoc - ├── images/ - │ └── screenshot.png - ├── partials/ - └── examples/ +doku.md +stepbystep.md +images/ ``` -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: +Empfohlen: ```text -v1.0.0 -v1.2.0 -v2.0.0 +doku.md +stepbystep.md +faq.md +doku.yml +images/ + produktbild.png + allgemein.png + konfiguration.png ``` -Die eigentliche Anzeigenversion kann zusätzlich aus der jeweiligen `antora.yml` gelesen werden. +`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. -Beispiel: +## 4. Optionale Metadaten: doku.yml + +`doku.yml` kann Produkttitel, Version und Navigationsreihenfolge definieren. ```yaml -name: produkt-a -title: Produkt A -version: 1.2.0 +title: Testdoku +version: X.X.X +revision: vXXX +starface: "ab STARFACE 9.0.0.0" +date: 2025-01-01 +start: doku.md nav: - - modules/ROOT/nav.adoc + - title: Uebersicht + file: doku.md + - title: Schritt fuer Schritt + file: stepbystep.md + - title: FAQ + file: faq.md ``` -Das Plugin soll Branch- und `antora.yml`-Informationen kombinieren. +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 -## 3. Grundanforderungen +Pro Synchronisation: -Das Plugin soll folgende Kernfunktionen bereitstellen: +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. -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. +## 6. Markdown-Regeln ---- +Unterstuetzt werden mindestens: -## 4. Technische Zielarchitektur +- 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)` -Das Plugin soll als eigenständiges WordPress-Plugin entwickelt werden. +Hinweise: -Vorgeschlagener Plugin-Name: - -```text -kb-antora-importer +```md +> **Hinweis:** Zusatzinformation ohne direkten Einfluss auf die Funktion. ``` -Vorgeschlagene Hauptdatei: +Warnungen: -```text -kb-antora-importer.php +```md +> **Warnung:** Kritischer Punkt oder Fallstrick bei der Konfiguration. ``` -Vorgeschlagene Struktur: +## 7. Link- und Bildauflösung -```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 +Interne Markdown-Links werden umgeschrieben: + +```md +[FAQ](faq.md) ``` ---- +wird zu: -## 5. WordPress-Datenmodell +```html +FAQ +``` -Es gibt zwei mögliche Umsetzungswege. Codex soll zunächst Variante A umsetzen, sofern nichts dagegenspricht. +`doku.md` und `index.md` verweisen auf die Versions-Startseite. -### 5.1 Variante A: Custom Post Types +Bilder muessen relativ zum Projektroot unter `images/` liegen: -Verwende Custom Post Types für die Dokumentationsseiten. +```md +![Allgemein](images/allgemein.png) +``` -#### Custom Post Type: `kb_doc_page` +Das Plugin importiert diese Dateien in die WordPress Media Library und ersetzt die Bild-URLs im HTML. -Repräsentiert eine gerenderte Dokumentationsseite. +## 8. WordPress-Datenmodell -Wichtige Meta-Felder: +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_antora_component -_kb_antora_component_title -_kb_antora_version -_kb_antora_module -_kb_antora_page_path -_kb_antora_source_path +_kb_markdown_source_path _kb_page_checksum _kb_last_imported_at _kb_nav_order -_kb_parent_page_path +_kb_product_slug +_kb_version_slug +_kb_page_slug +_kb_nav_tree +_kb_renderer_version ``` -#### Taxonomie: `kb_product` +## 9. Frontend -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//pages/ -modules//images/ -modules//partials/ -modules//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 -Installation -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 - - ... - -``` - -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: +Standard-URL-Struktur: ```text /docs/ @@ -548,615 +176,88 @@ URL-Struktur: /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: +Shortcodes: ```text +[kb_docs] [kb_docs_index] [kb_product_index product="produkt-a"] [kb_search] ``` -Optional später Gutenberg-Blöcke. +`[kb_docs]` bindet die Dokumentation in eine normale WordPress-Seite ein. ---- +## 10. Admin-Einstellungen -## 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: +Backend-Menue: ```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 + Uebersicht + Synchronisation + Einstellungen ``` -Produktseite: +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 -/docs/produkt-a/ - -Produkt A -Verfügbare Versionen: -- 2.0.0 aktuell -- 1.2.0 -- 1.0.0 +markdown-beispielprojekt/ ``` -Dokuseite: - -```text -/docs/produkt-a/2.0.0/installation/ - -[Sidebar Navigation] -Produkt A / 2.0.0 / Installation - -

Installation

-... -``` - ---- - -## 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 Konfiguration. -``` - ---- - -## 28. Beispiel für Bildauflösung - -Quelle: - -```adoc -image::screenshot-login.png[Login-Screenshot] -``` - -Suchpfad: - -```text -modules/ROOT/images/screenshot-login.png -``` - -Ziel: - -```html -
- - Login-Screenshot - -
-``` - ---- - -## 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. - +Diese Struktur dient als Vorlage fuer neue GitLab-Dokumentationsprojekte. diff --git a/debug-doc.html b/debug-doc.html new file mode 100644 index 0000000..143636f --- /dev/null +++ b/debug-doc.html @@ -0,0 +1,8 @@ +
+