264 lines
6.2 KiB
Markdown
264 lines
6.2 KiB
Markdown
# Codex-Anweisung: WordPress-Plugin fuer GitLab-basierte Markdown-Knowledgebase
|
|
|
|
## 1. Projektziel
|
|
|
|
Entwickle ein WordPress-Plugin, das technische Produktdokumentationen aus einer GitLab-Gruppe einliest, verarbeitet und innerhalb eines WordPress-basierten Kundenportals veroeffentlicht.
|
|
|
|
Die neue Dokumentationsstruktur basiert ausschliesslich auf **Markdown (`.md`)**. Die alte Dokumentation wird ausserhalb dieses Plugins als statischer Legacy-Stand weitergehostet. Das Plugin importiert keine Legacy-Dateien und bildet keine Legacy-Strukturen mehr nach.
|
|
|
|
## 2. GitLab-Struktur
|
|
|
|
GitLab enthaelt eine Gruppe, zum Beispiel:
|
|
|
|
```text
|
|
knowledgebase/
|
|
produkt-a/
|
|
Branch: v1.0.0
|
|
Branch: v1.1.0
|
|
produkt-b/
|
|
Branch: v2.0.0
|
|
```
|
|
|
|
Jedes Projekt repraesentiert ein Produkt oder Modul. Jede Branch repraesentiert eine Dokumentationsversion.
|
|
|
|
## 3. Pflichtstruktur pro Version-Branch
|
|
|
|
Jeder Branch muss mindestens enthalten:
|
|
|
|
```text
|
|
doku.md
|
|
stepbystep.md
|
|
images/
|
|
```
|
|
|
|
Empfohlen:
|
|
|
|
```text
|
|
doku.md
|
|
stepbystep.md
|
|
faq.md
|
|
doku.yml
|
|
images/
|
|
produktbild.png
|
|
allgemein.png
|
|
konfiguration.png
|
|
```
|
|
|
|
`doku.md` ist die Startseite der Version. `stepbystep.md` ist immer vorhanden und enthaelt die konkrete Einrichtung und Konfiguration. Weitere Markdown-Dateien auf Root-Ebene sind erlaubt und werden als Unterseiten importiert. `README.md` wird ignoriert.
|
|
|
|
## 4. Optionale Metadaten: doku.yml
|
|
|
|
`doku.yml` kann Produkttitel, Version und Navigationsreihenfolge definieren.
|
|
|
|
```yaml
|
|
title: Testdoku
|
|
version: X.X.X
|
|
revision: vXXX
|
|
starface: "ab STARFACE 9.0.0.0"
|
|
date: 2025-01-01
|
|
start: doku.md
|
|
nav:
|
|
- title: Uebersicht
|
|
file: doku.md
|
|
- title: Schritt fuer Schritt
|
|
file: stepbystep.md
|
|
- title: FAQ
|
|
file: faq.md
|
|
```
|
|
|
|
Wenn `doku.yml` fehlt, nutzt das Plugin den GitLab-Projektnamen als Produkttitel, den Branchnamen als Version und erzeugt die Navigation aus den Markdown-Dateien.
|
|
|
|
## 5. Importlogik
|
|
|
|
Pro Synchronisation:
|
|
|
|
1. Einstellungen laden.
|
|
2. GitLab-Gruppe abrufen.
|
|
3. Projekte abrufen.
|
|
4. Branches nach Pattern filtern, Standard `^v.*`.
|
|
5. Repository Tree pro Branch abrufen.
|
|
6. Branch nur importieren, wenn `doku.md` vorhanden ist.
|
|
7. Warnung loggen, wenn `stepbystep.md` fehlt.
|
|
8. Optional `doku.yml` lesen.
|
|
9. Root-Markdown-Dateien importieren, `README.md` ignorieren.
|
|
10. Bilder aus `images/` in die WordPress Media Library importieren.
|
|
11. Markdown nach HTML rendern.
|
|
12. Interne `.md`-Links auf WordPress-Doku-URLs umschreiben.
|
|
13. Bildreferenzen auf WordPress-Medien-URLs umschreiben.
|
|
14. Seiten als `kb_doc_page` speichern oder aktualisieren.
|
|
15. Importlog schreiben.
|
|
|
|
## 6. Markdown-Regeln
|
|
|
|
Unterstuetzt werden mindestens:
|
|
|
|
- Ueberschriften `#` bis `######`
|
|
- Absaetze
|
|
- ungeordnete und geordnete Listen
|
|
- Blockquotes fuer Hinweise und Warnungen
|
|
- Code-Fences
|
|
- Inline-Code
|
|
- Fett und kursiv
|
|
- Bilder ``
|
|
- Links `[Text](ziel.md)`
|
|
|
|
Hinweise:
|
|
|
|
```md
|
|
> **Hinweis:** Zusatzinformation ohne direkten Einfluss auf die Funktion.
|
|
```
|
|
|
|
Warnungen:
|
|
|
|
```md
|
|
> **Warnung:** Kritischer Punkt oder Fallstrick bei der Konfiguration.
|
|
```
|
|
|
|
## 7. Link- und Bildauflösung
|
|
|
|
Interne Markdown-Links werden umgeschrieben:
|
|
|
|
```md
|
|
[FAQ](faq.md)
|
|
```
|
|
|
|
wird zu:
|
|
|
|
```html
|
|
<a href="/docs/produkt/version/faq/">FAQ</a>
|
|
```
|
|
|
|
`doku.md` und `index.md` verweisen auf die Versions-Startseite.
|
|
|
|
Bilder muessen relativ zum Projektroot unter `images/` liegen:
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
Das Plugin importiert diese Dateien in die WordPress Media Library und ersetzt die Bild-URLs im HTML.
|
|
|
|
## 8. WordPress-Datenmodell
|
|
|
|
Das Plugin nutzt WordPress-nativ:
|
|
|
|
- Custom Post Type `kb_doc_page`
|
|
- Taxonomie `kb_product`
|
|
- Taxonomie `kb_version`
|
|
- optional Taxonomie `kb_component`
|
|
|
|
Wichtige Metadaten:
|
|
|
|
```text
|
|
_kb_gitlab_project_id
|
|
_kb_gitlab_project_path
|
|
_kb_gitlab_branch
|
|
_kb_gitlab_commit_sha
|
|
_kb_markdown_source_path
|
|
_kb_page_checksum
|
|
_kb_last_imported_at
|
|
_kb_nav_order
|
|
_kb_product_slug
|
|
_kb_version_slug
|
|
_kb_page_slug
|
|
_kb_nav_tree
|
|
_kb_renderer_version
|
|
```
|
|
|
|
## 9. Frontend
|
|
|
|
Standard-URL-Struktur:
|
|
|
|
```text
|
|
/docs/
|
|
/docs/{product}/
|
|
/docs/{product}/{version}/
|
|
/docs/{product}/{version}/{page}/
|
|
```
|
|
|
|
Shortcodes:
|
|
|
|
```text
|
|
[kb_docs]
|
|
[kb_docs_index]
|
|
[kb_product_index product="produkt-a"]
|
|
[kb_search]
|
|
```
|
|
|
|
`[kb_docs]` bindet die Dokumentation in eine normale WordPress-Seite ein.
|
|
|
|
## 10. Admin-Einstellungen
|
|
|
|
Backend-Menue:
|
|
|
|
```text
|
|
Knowledgebase
|
|
Uebersicht
|
|
Synchronisation
|
|
Einstellungen
|
|
```
|
|
|
|
Einstellungen:
|
|
|
|
- GitLab Base URL
|
|
- GitLab API Token
|
|
- GitLab Group Path / ID
|
|
- Branch Pattern
|
|
- Frontend Base Slug
|
|
- Bilder mit Lightbox verlinken
|
|
- Dokumentation oeffentlich anzeigen
|
|
- SVG-Import erlauben
|
|
- Automatische Synchronisation
|
|
- Frontend-Design
|
|
- Optionale eigene `theme.css`
|
|
|
|
Es gibt keine Renderer-Modus-Einstellung mehr. Markdown wird direkt im Plugin verarbeitet.
|
|
|
|
## 11. Sicherheit
|
|
|
|
- GitLab-Token niemals ausgeben.
|
|
- Admin-Aktionen mit Capabilities absichern.
|
|
- REST-API mit Berechtigungen schuetzen.
|
|
- Markdown-HTML sanitizen.
|
|
- Keine Shell-Aufrufe fuer Rendering.
|
|
- SVG nur erlauben, wenn die Option aktiv ist.
|
|
- Keine privaten GitLab-URLs im Frontend leaken.
|
|
- Logs ohne Secrets speichern.
|
|
|
|
## 12. Akzeptanzkriterien
|
|
|
|
- Plugin heisst **KB Markdown Importer**.
|
|
- Plugin laesst sich aktivieren.
|
|
- Admin-Menue erscheint.
|
|
- GitLab-Verbindungstest funktioniert.
|
|
- Projekt mit Branch `v...` wird erkannt.
|
|
- Branch mit `doku.md`, `stepbystep.md` und `images/` wird importiert.
|
|
- `doku.md` wird Startseite der Version.
|
|
- `stepbystep.md` wird als Unterseite importiert.
|
|
- Weitere Root-`.md`-Dateien werden als Unterseiten importiert.
|
|
- Bilder aus `images/` werden importiert und im HTML ersetzt.
|
|
- Interne `.md`-Links funktionieren.
|
|
- `/docs/` zeigt die Dokumentationsuebersicht.
|
|
- `/docs/{product}/{version}/` zeigt die Startseite.
|
|
- Synchronisation dupliziert unveraenderte Seiten nicht.
|
|
- Importfehler werden im Backend-Log sichtbar.
|
|
|
|
## 13. Nicht-Ziele
|
|
|
|
- Kein Legacy-Rendering.
|
|
- Keine Legacy-Kompatibilitaet im Importpfad.
|
|
- Kein externer Render-Service.
|
|
- Kein lokaler CLI-Renderer.
|
|
- Kein Live-Rendering aus GitLab bei jedem Seitenaufruf.
|
|
- Kein Gutenberg-Editor fuer Dokumentationsquellen.
|
|
|
|
## 14. Beispielprojekt
|
|
|
|
Ein Beispiel fuer die neue Struktur liegt im Repository unter:
|
|
|
|
```text
|
|
markdown-beispielprojekt/
|
|
```
|
|
|
|
Diese Struktur dient als Vorlage fuer neue GitLab-Dokumentationsprojekte.
|