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 ``
+- 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
+
+```
-#### 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
-
-```
-
-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
-
-
-
-
-
-```
-
----
-
-## 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 @@
+
+
+ Dieser Styleguide übersetzt den Markenauftritt von o-byte.com in klare Regeln
+ für Design, Sprache und Anwendung. Technisch stark, visuell fokussiert und
+ konsequent serviceorientiert.
+
+ Positionierung und Kernbotschaft als inhaltlicher Rahmen für Website, Vertrieb,
+ Support und Produktkommunikation.
+
+
+
+
+
Positionierung
+
+ o-byte.com ist ein spezialisiertes ITK-Systemhaus für moderne Business-
+ Kommunikation mit Fokus auf IP-basierte Telefonie, STARFACE und
+ integrationsgetriebene Erweiterungen.
+
+
+
Von Planung und Umsetzung bis Support aus einer Hand.
+
Partnerorientiert mit konkretem Kundennutzen statt Buzzwords.
+
Technisch tief, in der Kommunikation trotzdem verständlich.
+
+
+
+
Markenversprechen
+
+ Wir liefern lösungsorientierte Telekommunikation, die im Tagesgeschäft messbar
+ entlastet: bessere Erreichbarkeit, weniger Reibung, klare Prozesse.
+
+
+
"Gemeinsam erfolgreich" ist Leitmotiv, nicht Claim-Dekoration.
+
+
+
+
+
+
Werte
+
Verlässlichkeit, Erreichbarkeit, Pragmatismus und Qualität.
+
+
+
Zielgruppen
+
KMU, Kanzleien, Praxen, Industrie und Partner mit Integrationsbedarf.
+
+
+
Markenton
+
Sachlich positiv, kompetent, auf Augenhöhe.
+
+
+
+
+
+
+
Tonalität
+
Wie o-byte.com spricht: serviceorientiert, klar und lösungsfokussiert.
+
+
+
+
Do
+
+
Konkrete Ergebnisse und Nutzen zuerst benennen.
+
Aktive Sprache und direkte Handlungsangebote verwenden.
+
Technik erklären, ohne Überheblichkeit oder Jargon-Last.
+ Clean: ohne Kennzeichnung der registrierten Marke und ohne
+ "Telekommunikation". Nur für technische Sonderfälle, wenn das reguläre Logo
+ prozessbedingt nicht nutzbar ist, und ausschließlich nach Rücksprache mit der
+ Marketingabteilung von o-byte.com.
+
+ Web-App: Kennzeichnung der Plattform innerhalb von Webanwendungen
+ (z. B. Portal, OLM, Dashboard), um den aktuellen Produktkontext sichtbar zu machen.
+
Schutzzone: mindestens 0.5x der Signethöhe rund um das Zeichen.
+
Mindestbreite Logo digital: 140 px.
+
Mindestgröße Favicon digital: 24 x 24 px, empfohlen ab 32 px.
+
Nie auf unruhigen Hintergründen ohne Kontrastfläche platzieren.
+
+
+
+
Unzulässige Nutzung
+
+
Kein Verzerren, Kippen oder Rotieren.
+
Keine freien Umfärbungen außer den definierten Varianten.
+
Keine Schatten-, Glow- oder 3D-Effekte.
+
Keine Transparenzreduktion, die die Lesbarkeit mindert.
+
+
+
+
+
+
+
+
Farbsystem
+
+ o-byte Blue basiert auf festen Shades und Tints. Hauptfarbe, Hilfsfarbe und
+ Hintergrund sind auf die definierte Blau-Skala abgestimmt.
+
+
+
+
+
+
+ Hauptfarbe: o-byte Blue
+ #00A7E6
+
+
+
+
+
+
+ Hilfsfarbe: Blue Tint 1
+ #33B9EB
+
+
+
+
+
+
+ Hintergrund
+ #F5FBFE
+
+
+
+
+
+
+ Akzentfarbe
+ #F59C00
+
+
+
+
+
+
+ Slate
+ #343537
+
+
+
+
+
+
+ White
+ #FFFFFF
+
+
+
+
+
+
+
20% Shades von #00A7E6
+
+
+
+
+
+
+
+
+
20% Tints von #00A7E6
+
+
+
+
+
+
+
+
+
+
Einsatzlogik
+
+
+
+
+
+
+
+
Shades nur für mehr Tiefe und Kontrast, Tints nur für leichte Flächen nutzen.
+
+
+
+
+
+
Typografie
+
Fließ- und Sekundärüberschriften in Nunito, Primär-Akzente weiterhin in URW Gothic L Demi.
+
+
+
+
Nunito live in der Anwendung
+
+
Einsatzbereich: H2-H4 + Fließtext
+
Stabiler Betrieb im Tagesgeschäft
+
+ Nunito ist die Standardschrift für längere Inhalte. Sie bleibt bei normaler
+ Lesedistanz ruhig, gut scanbar und belastet die Augen auch in längeren Texten nicht.
+
+
Empfohlen: 17 px / 1.58 Zeilenhöhe / linksbündig
+
+
+
+
URW Demi live in der Anwendung
+
+
Einsatzbereich: H1 + CTA + Primärakzent
+
Kommunikation, die entlastet.
+
+
+
+
+
URW Demi bewusst punktuell nutzen, nicht für lange Lesetexte.
+
+
+
+
+
Direkter Schriftvergleich
+
+
+
Nunito (Body/H2-H4)
+
Kommunikation auf Augenhöhe. Klar, direkt, verlässlich.
+
Aa Bb Cc Dd Ee Ff Gg ÄÖÜ äöü ß 0123456789
+
+
+
URW Gothic L Demi (H1/CTA)
+
Kommunikation auf Augenhöhe. Klar, direkt, verlässlich.
+
Aa Bb Cc Dd Ee Ff Gg ÄÖÜ äöü ß 0123456789
+
+
+
+
+
Typografische Skala
+
+
+
+
+
Element
+
Größe
+
Gewicht
+
Zeilenhöhe
+
+
+
+
+
H1
+
40-60 px (responsive)
+
600 (URW Gothic L Demi)
+
1.03
+
+
+
H2
+
30 px
+
700 (Nunito)
+
1.15
+
+
+
H3
+
21 px
+
700 (Nunito)
+
1.2
+
+
+
Body
+
17 px
+
400-700 (Nunito)
+
1.58
+
+
+
+
+
+
+
+
Verbindliche Satzregeln
+
+
Fließtext standardmäßig 17 px in Nunito, niemals kleiner als 16 px.
+
Lesetexte mit Zeilenhöhe 1.5 bis 1.65 setzen; Headlines enger führen (1.03 bis 1.2).
+
Zeilenlänge für längere Texte zwischen 45 und 75 Zeichen halten.
+
Text linksbündig, kein Blocksatz in Fließtexten.
+
Versalien nur für kurze Labels/Kicker einsetzen, nicht für ganze Absätze.
+
Fettungen sparsam nutzen: maximal ein Fokuspunkt pro Satz oder UI-Element.
+
+
+
+
Hierarchie-Definition
+
+
H1 ist der einzige visuelle Primäranker einer Seite und bleibt in URW Gothic L Demi.
+
H2 strukturiert Hauptabschnitte in Nunito 700 und muss inhaltlich scanbar formuliert sein.
+
H3 benennt konkrete Teilthemen, Komponenten oder Arbeitsschritte.
+
Body trägt die Information: neutral, klar, ohne dekorative Effekte.
+
Buttons und CTAs bleiben in URW Gothic L Demi, damit Handlungsaufforderungen sofort auffallen.
+
In einer Card nie mehr als drei Hierarchieebenen kombinieren (z. B. H3, Body, Label).
+
+
+
+
+
Do / Don't Beispiele
+
+
+
+
+
Kontext
+
Do
+
Don't
+
+
+
+
+
Absatz
+
Kurze, klare Sätze mit 1-2 Kernaussagen pro Absatz.
+
Verschachtelte Satzkonstruktionen mit vielen Nebensätzen.
+
+
+
Headline
+
Nutzenorientiert und konkret, z. B. "Support in unter 2 Stunden".
+
Abstrakt oder werblich, z. B. "Kommunikation neu gedacht".
+
+
+
CTA
+
Verb + Ergebnis, z. B. "Angebot anfordern".
+
Unklare Labels wie "Mehr" oder "Weiter".
+
+
+
Hervorhebung
+
Wichtige Begriffe punktuell fett markieren.
+
Ganze Absätze dauerhaft fett setzen.
+
+
+
+
+
+
+
Implementierungsbeispiele
+
Beispiel für saubere Text-Hierarchie mit den festgelegten Schriftrollen.
+
<section>
+ <h2>Service-Level und Erreichbarkeit</h2>
+ <p>Unser Support reagiert werktags innerhalb von zwei Stunden.</p>
+ <button class="btn btn--primary">Anfrage senden</button>
+</section>
Stark entsättigte oder dramatisch dunkle Bildlooks ohne Markenbezug.
+
Beliebige Handschlag-Stockfotos ohne realen Kontext.
+
Unruhige Hintergründe, die Textlesbarkeit reduzieren.
+
+
+
+
+
Bildbearbeitung und Overlay
+
+ Nur dezente Korrekturen: Kontrast +5 bis +10, Sättigung maximal +6, kein harter
+ Farbstich. Text auf Bildern immer mit Kontrastfläche (hell/dunkel) absichern.
+
+
+
+
+
+
+
UI-Komponenten
+
Robuste Standardbausteine für Website, Landingpages und Kundenportal.
+
+
+
Hero
+
+
Einstiegskomponente
+
Kommunikation, die im Alltag spürbar entlastet.
+
+ Der Hero transportiert Nutzen, Positionierung und klare Handlungsoptionen innerhalb
+ der ersten Bildschirmansicht.
+
+ Einsatz: immer als erste inhaltliche Komponente einer Seite, mit 1 Primär-CTA und
+ maximal 1-2 Sekundäraktionen.
+
+
+
+
+
Buttons
+
+
+
+
+
+
+
+
Status
+
+ Standard
+ Aktiv
+ Priorität
+ Verfügbar
+
+
+
+
+
+
Kontaktformular
+
+
+
+
Hinweis-Box
+
+ Service-Hinweis:
+ Support-Anfragen immer mit Erreichbarkeit und kurzer Problembeschreibung einreichen.
+
+
Alerts werden sachlich formuliert, ohne Alarmismus.
+
+
+
+
Card-Prinzip
+
+ Cards nutzen weiße Flächen, feine Linien und moderate Tiefe. Inhalte bleiben
+ strukturiert, ohne visuelle Überladung. Keine dekorativen Verläufe in
+ Content-Flächen.
+
+
+
+
+
+
+
Accessibility und UX-Regeln
+
Verbindliche Mindeststandards für digitale Touchpoints.
+
+
+
+
Kontrast und Lesbarkeit
+
+
Textkontrast mindestens WCAG AA (4.5:1 bei normalem Text).
+
Keine hellblauen Fließtexte auf weißem Hintergrund.
+
Interaktive Elemente mit klarer Fokusmarkierung versehen.
+
Alternativtexte für Grafiken und Bilder bereitstellen.
+
+
+
+
Interaktion
+
+
Klickflächen mindestens 40 x 40 px.
+
Buttons eindeutig benennen (Verb + Nutzen).
+
Navigation logisch und auf mobilen Geräten ohne Brüche.
+
+
+
+
+
MUSS-Checkliste (Release-Gate)
+
+
Jede Seite MUSS genau eine h1, eine sinnvolle Überschriften-Hierarchie und semantische Landmarks (header, nav, main, footer) haben.
+
Jede Seite MUSS ein korrektes lang-Attribut und einen eindeutigen, aussagekräftigen title haben.
+
Alle Funktionen MÜSSEN vollständig per Tastatur bedienbar sein (Tab, Shift+Tab, Enter, Space, Escape) und dürfen keine Keyboard-Falle erzeugen.
+
Der Fokus MUSS immer sichtbar sein, logisch durch die Seite laufen und darf nie per CSS entfernt werden.
+
Textkontrast MUSS mindestens 4.5:1 betragen; Kontrast von UI-Komponenten/Fokusindikatoren MUSS mindestens 3:1 betragen.
+
Information darf NIE nur über Farbe vermittelt werden; es MUSS immer ein zweiter Hinweis vorhanden sein (Text, Icon, Muster oder Statuslabel).
+
Interaktive Elemente MÜSSEN einen eindeutigen Accessible Name haben (keine Buttons/Links nur mit "Hier" oder nur Icon ohne Label).
+
Klick- und Touch-Ziele MÜSSEN mindestens 44 x 44 px gross sein oder gleichwertig grossen Abstand besitzen.
+
Formulare MÜSSEN programmatisch verknüpfte Labels besitzen; Pflichtfelder, Fehler und Hilfetexte MÜSSEN für Screenreader auslesbar sein.
+
Fehlermeldungen MÜSSEN konkret sagen, was falsch ist und wie es zu korrigieren ist; der Fokus MUSS nach Submit zur Fehlerzusammenfassung springen.
+
Statusänderungen (z. B. "gespeichert", "geladen", "Fehler") MÜSSEN per aria-live oder gleichwertig angekündigt werden.
+
Bilder mit Informationswert MÜSSEN sinnvolle Alt-Texte haben; rein dekorative Bilder MÜSSEN als dekorativ markiert sein.
+
Video mit Sprache MUSS Untertitel haben; reine Audioinhalte MÜSSEN ein Transkript haben; Autoplay mit Ton ist nicht zulässig.
+
Inhalte MÜSSEN bei 200 % Zoom und bei 320 CSS-Pixel Breite ohne horizontalen Pflicht-Scroll funktionieren (ausser technisch notwendige Ausnahmen wie Datentabellen).
+
Animationen/Bewegungen MÜSSEN reduzierbar sein (prefers-reduced-motion); Inhalte dürfen nicht mehr als 3-mal pro Sekunde blinken.
+
Authentifizierung darf keine unzumutbare kognitive Hürde erzeugen; es MUSS eine barrierefreie Alternative zu rein visuellen Aufgaben geben.
+
Release-Freigabe nur, wenn Kernpfade bestanden sind: Navigation, Suche, Login, Formulare, Checkout, Zahlung und Fehlerszenarien.
+
+
Definition of Done: Kein Release ohne bestandenen Keyboard-Test, Screenreader-Schnelltest und dokumentierte Behebung aller kritischen A11y-Defekte.
+
+
+
+
+
+
Design Tokens
+
Copy-ready Basis für Webprojekte und UI-Implementierung.
+
+
+
+
+
diff --git a/vorlage.adoc b/vorlage.adoc
new file mode 100644
index 0000000..40c89a5
--- /dev/null
+++ b/vorlage.adoc
@@ -0,0 +1,219 @@
+// Doku Workflow:
+// Im ersten Durchgang Doku schreiben, als PDF Exportieren und Seitenumbrüche kontrollieren. Umbrüche im Paragraphen vermeiden
+// Inhaltliche Plausibilität prüfen
+// Schreibweisen und gängige Rechtschreibfehler und Syntax prüfen
+
+= Testdoku
+:imagesdir: ../images
+:date: 01.01.2025
+:revision: X.X.X vXXX ab Starface 9.0.0.0
+
+//(Ab hier soll im idealfall aus SAP kommen)
+== Dokumentation für Modulversion X.X.X ab STARFACE 9.0.0.0
+
+== Produktbeschreibung
+
+// Schreibstil ist hier die neutrale Form
+
+* Idealfall SAP Schnittstelle, Produktbeschreibung, vertrieblicher Input
+* Produktbild rechts einfügen und *verweis auf den Shop*
+
+== Anwendungsbeispiel
+
+* Beispiel, wofür das Modul in der Praxis verwendet (im Zweifel mit DN absprechen)
+
+== Technische Voraussetzungen
+
+* *ab STARFACE 9.0.0.0*
+* Für dieses Modul stehen legacy Versionen ab STARFACE 7.0.0.2 zur Verfügung.
+* Cloud anforderungen bsp. SSH-Tunnel
+* Anforderungen an Drittsysteme/Anbieter
+* Optionale anfdorderungen für bestimmte Funktionen
+* Anforderungen für Hardware
+* getestet mit Versionierung X von externer Software/API
+
+//Dieser Bereich wird in Abstimmung mit Devs, Vertrieb und Support bei Bedarf eingefügt.
+
+// === (Technische Limitierung(en))
+
+// * Welche technischen Faktoren gibt es, die die Modulfunktion einschränken (Maximale Importzahl usw.)
+
+== Vertriebsmodell(e)
+
+* Kauf/Inkl. SPV
+* Managed Service
+* ...
+
+
+//== Modulvarianten
+
+//* Modulvarianen für verschiedene Drittsysteme (z.b Google bei AKI, XML-Monitoring, ...)
+
+
+//(Bis hier soll im idealfall aus SAP kommen)
+
+//Seitenumbruch
+<<<
+
+// Schreibstil ab hier ist das "imparative-DU", ein direktes Du ist zu vermeiden, wird der Nutzer nicht direkt angesprochen verwenden wir die neutrale Form (man). "Du", "Dich", "Dein", ... schreiben wir GROß!
+
+// Benutzung von TIP: und WARNING: - Tip ist immer, wenn man zusätzliche Infos bereitstellt, die aber keinen direkten Einfluss auf die Funktion des Moduls haben. Mit WARNING: Werden in der Regel besonders kritische Punkte (Fallstricke) bei der Konfiguration des Moduls hervorgehoben.
+
+== Vorbereitung der IT-Umgebung:
+
+* Infrastruktur für den Betrieb des Moduls aufsetzen und konfigurieren (ggf. Exkurs in die Partnersysteme)
+
+=== Konfiguration der Drittsysteme
+
+* Was muss an Drittsystemen eingestellt werden
+
+== STARFACE-Konfiguration
+
+=== Menüpunkt
+
+==== Tab
+
+image:sf_tab1.png[]
+
+//Namenskonvention für Bilder: Dateiname = Tab-Überschrift, bei SF Konfiguration mit dem Präfix "sf_"
+
+===== Unterpunkt
+
+* Einstellungen, die an der STARFACE selber vorgenommen werden (z.b am SF Internen Adressbuch oder am Netzwerk etc.)
+* Es muss vorab keine Konfiguration in der STARFACE vorgenommen werden.
+
+== Modulkonfiguration
+
+=== Allgemein
+
+image::allgemein.png[]
+
+//Namenskonvention für Bilder: Dateiname = Tab-Überschrift, bei SF Konfiguration mit dem Präfix "sf_"
+
+* *Name*
+
+** Wähle hier den Namen der Modulinstanz. Dieser Name sollte möglichst beschreibend vergeben werden, ein guter Ausgangspunkt ist der Name des Moduls. Sollen mehrere Instanzen des selben Moduls aktiv sein, muss für jede Instanz ein einmaliger Name vergeben werden.
+
+* *Beschreibung*
+
+** Dieses Feld bietet Raum für eine detailliertere Dokumentation der Instanz. Hier kann beispielsweise dokumentiert werden, auf welche Nutzer/Gruppen das Modul zugreift.
+
+* *Logdatei*
+
+** Jedes Modul informiert in den Levels "ERROR, WARN, INFO, DEBUG, TRACE" in den jeweils verschiedenen Abstufungen über Prozesse, die im Modulbetrieb ablaufen. Falls ein Fehler auftritt hat man hier die Möglichkeit, die Logdatei zu speichern. Standardeinstellung ist das Level "INFO".
+
+TIP: Das Log aktualisiert sich nicht automatisch, sondern nur, wenn die entsprechende Schaltfläche betätigt wird.
+
+=== Konfiguration
+
+image::konfiguration.png[]
+
+//Namenskonvention für Bilder: Dateiname = Tab-Überschrift, bei SF Konfiguration mit dem Präfix "sf_"
+
+==== Unterpunkt in Tab
+
+* *Auf einzelne Punkte eingehen*
+** Text
+
+TIP: In den meisten Fällen werden die Rufnummern in das Format 00492515906850 normalisiert. Es können in Ausnahmefällen aber auch Formate wie +492515906850 oder 02515906850 signalisiert werden. Daher empfehlen wir grundsätzlich die Verwendung von Wildcards bei der Quellrufnummer, also zum Beispiel *2515906850.
+
+* Legende:
+** ? - Platzhalter für eine Ziffer
+** * - Platzhalter für eine, mehrere oder keine Ziffer/n
+
+== Bekannte Probleme
+
+* Bei diesem Modul liegen keine bekannten Probleme vor.
+* Problem entdeckt? Schicke eine E-Mail an support@o-byte.com, um Fehler zu melden!
+
+ODER
+
+* Problem1:
+** Problem schildern
+*** Lösung anbieten
+
+//== FAQ
+
+//* Wenn von einem Modul sehr viele Supportanfragen zum gleichen Thema kommen, kann man das hier abhandeln und so ggf. viele unnötige Supportfälle vermeiden
+
+== Versionshinweis
+
+* Versionsnummer
+** *Bugfix:*
+*** Welcher Fehler wurde behoben?
+** *Neue Funktion:*
+*** Welche neue Funktion wurde eingebaut?
+
+// Beim Bugfix immer daran denken, ggfs. den "Bekannte Probleme" Bereich zu editieren.
+
+== Download
+
+=== Modul testen:
+
+* Für dieses Modul steht kein Testzeitraum von 14 Tagen zur Verfügung. Das Modul wird erst mit Kauf aktiv. Unser Vertriebsteam hilft gerne weiter unter vertrieb@o-byte.com.
+
+*ODER*
+
+Bitte achte beim Download auf die Kompatibilität zur STARFACE Version!
+
+Mit Klick auf den Downloadlink einer Modulversion öffnen sich ein Fenster mit Installationshinweisen und ein Pop-up-Fenster.
+
+=== Modul testen:
+
+* Wir stellen unser Modul 14 Tage kostenfrei zum Testen zur Verfügung.
+* Nach dem Kauf oder Update: Mit E-Mail-Adresse verifizieren. Für die Inbetriebnahme/das Update ist kein Lizenzschlüssel nötig.
+* Wir stellen das Modul als .sfm Datei zur Verfügung.
+
+*ODER*
+
+Bitte achte beim Download auf die Kompatibilität zur STARFACE Version!
+
+Mit Klick auf den Downloadlink einer Modulversion öffnen sich ein Fenster mit Installationshinweisen und ein Pop-up-Fenster.
+
+* Kostenfreies Modul laden: Bitte trage deine Mailadresse ein, stimme der Datenschutzbestimmung zu und klicke auf „Download“. Der Downloadlink wird per Mail zur Verfügung gestellt.
+
+* Nach dem Kauf oder Update: Mit E-Mail-Adresse verifizieren. Für die Inbetriebnahme/das Update ist kein Lizenzschlüssel nötig.
+
+* Wir stellen das Modul als .sfm Datei zur Verfügung.
+
+++++
+
+
+