Seite kopieren

Inhalte pflegen

Zuletzt geändert am 17. Oktober 2026

Das Portal entsteht aus Markdown-Dateien im GitLab-Repository splendidinternet/ospo/devportal. Jeder Push auf main baut die Seite mit MkDocs und dem Theme Material for MkDocs neu und stellt sie automatisch in die Vorschau. Live unter ecommerce-hub.sh geht ein Stand erst, wenn jemand den Job deploy-live der Pipeline von Hand startet.

docs/*.md bearbeiten
    ↓ git push origin main
GitLab-Pipeline: Prüfungen, mkdocs build
    ↓ automatisch
Vorschau: https://devportal.ospo.splendid-sandbox.de (mit Passwortschutz)
    ↓ von Hand: Job deploy-live
https://ecommerce-hub.sh/developer-portal/

Repository klonen

Von außen über den öffentlichen Spiegel auf Codeberg, intern über unser GitLab:

git clone https://codeberg.org/OSPO/OSPO-Developer-Portal.git                              # von außen
git clone https://gitlab.splendid-dev.de/splendidinternet/ospo/devportal.git  # intern

Wie Beiträge von außen ins Portal kommen, steht unter Beiträge von außen.

Aufbau

devportal/
├── mkdocs.yml              Konfiguration und Navigation, baut die Vorschau
├── mkdocs-live.yml         Abweichungen für ecommerce-hub.sh
├── hooks/                  Markdown für „Seite kopieren“, Prüfdatum, llms.txt
├── overrides/              Ergänzungen am Theme, Navigation und Footer des Hubs
├── tools/                  Prüfungen für die Pipeline
└── docs/
    ├── index.md            Startseite
    ├── allgemein/          Architektur, Glossar, diese Anleitung
    ├── konfigurator/       Konfigurations-Assistent
    ├── woocommerce/        je Thema eine Seite
    ├── shopware/
    └── mageos/

Neue Seite anlegen

1. Markdown-Datei unter docs/ anlegen, zum Beispiel docs/shopware/api.md.

2. In mkdocs.yml unter nav: eintragen. Seiten, die dort fehlen, erscheinen nicht im Menü.

   nav:
     - Shopware:
         - Übersicht: shopware/index.md
         - API: shopware/api.md
   

3. Committen und pushen, die Pipeline stellt den Stand in die Vorschau:

   git add .
   git commit -m "Add Shopware API docs"
   git push
   

Interne Links immer relativ auf die Markdown-Datei setzen ([Betrieb](../woocommerce/betrieb.md)), nicht auf die fertige URL. MkDocs rechnet sie um und meldet beim Bauen, wenn ein Ziel fehlt.

Lokal ansehen

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/mkdocs serve
# → http://127.0.0.1:8000, Änderungen erscheinen sofort

requirements.txt legt die Versionen fest, mit denen auch die Pipeline baut. Wer aktualisieren will, ändert sie dort. MkDocs bleibt auf 1.x: Material verlangt mkdocs<2, und MkDocs 2.0 schafft das System für Plugins und Theme-Anpassungen ab.

Die Pipeline baut mit --strict. Ein toter interner Link oder ein fehlender Anker bricht den Build ab, statt eine fehlerhafte Seite zu veröffentlichen. Lokal prüft man das genauso mit .venv/bin/mkdocs build --strict.

Automatische Prüfungen

Vor dem Veröffentlichen laufen in der Pipeline vier Prüfungen, auch bei Merge Requests:

Prüfung	Was sie findet	Bei einem Treffer
mkdocs build --strict	tote interne Links, Seiten außerhalb der Navigation, Fehler in der Prüfangabe	nichts wird veröffentlicht
tools/vollstaendig_pruefen.py	Seiten, auf denen nach dem Bauen Abschnitte fehlen. Python-Markdown hält etwa < vor einem Buchstaben für ein HTML-Tag, auch in Backticks, und verschluckt dann den Rest der Seite	nichts wird veröffentlicht
tools/inhalt_pruefen.py	Zugangsdaten, Schlüssel und Tokens, Server-Adressen, SSH-Ports, interne Pfade, HTML außerhalb von Code sowie Links auf javascript: und data:	nichts wird veröffentlicht
tools/links_pruefen.py	externe Links, die ins Leere führen (404, 410, Serverfehler, keine Verbindung)	nur eine Warnung, weil fremde Seiten auch einmal ausfallen

Lokal laufen sie genauso:

.venv/bin/mkdocs build --strict
python3 tools/vollstaendig_pruefen.py docs site
python3 tools/inhalt_pruefen.py docs
python3 tools/links_pruefen.py site

Die Inhaltsprüfung kennt keine Ausnahmen. Für Beispiele deshalb Adressen nehmen, die dafür reserviert sind: example.org und seine Subdomains, 127.0.0.1 und für IP-Adressen die Bereiche 192.0.2.0/24, 198.51.100.0/24 und 203.0.113.0/24. Namen von Kunden findet sie nicht, darauf bleibt beim Schreiben selbst zu achten.

Eingebettetes HTML ist gesperrt, weil Markdown es unverändert in die Seite übernimmt: Ein Beitrag könnte sonst ein Skript mitbringen, das nach dem Zusammenführen bei jedem Besucher läuft. HTML-Beispiele gehören deshalb in Backticks oder einen Codeblock. Automatische Links wie <https://example.org> sind erlaubt.

Geprüft am

Eine Seite kann angeben, wann sie zuletzt gegen eine laufende Instanz geprüft wurde und mit welchen Versionen. Das Datum steht dann oben rechts neben „Seite kopieren“, die Versionen im Tooltip und in der kopierten Fassung unter dem Titel.

---
geprueft:
  am: 2026-10-08
  mit: WordPress 7.1.3, WooCommerce 11.2.0 und PHP 8.4.26
---

# WooCommerce

Davon getrennt steht unter dem Titel jeder Seite klein „Zuletzt geändert am …“. Das Datum kommt aus dem letzten Commit an der Markdown-Datei (hooks/geaendert.py) und zieht bei jeder Änderung von selbst nach, auch wenn nur ein Satz dazukommt. Es sagt also nichts darüber, ob die Seite geprüft ist.

Das Prüfdatum nur setzen, wenn die Aussagen der Seite wirklich an einer laufenden Instanz nachvollzogen sind, und dabei mit auf die Versionen bringen, die dort liefen. Wer eine Seite nur umformuliert, lässt die Angabe stehen, wie sie ist. Eine unvollständige Angabe, etwa ohne mit, bricht den Build ab.

Was hier hingehört und was nicht

Das Portal richtet sich an Entwicklerinnen und Entwickler, auch außerhalb von Splendid, und ist öffentlich. Deshalb:

• Hinein: Aufbau, Entscheidungen mit Begründung, Fallstricke, wiederverwendbare Lösungen.
• Nicht hinein: Zugangsdaten, Server-Adressen und SSH-Ports, interne Pfade einzelner Instanzen, Namen von Kunden. Das gehört in die Projektdoku des jeweiligen Repositories.

Beiträge von außen

Führend ist das interne Repository. Die Pipeline spiegelt jeden Stand von main nach dem Deploy in die Vorschau auf Codeberg ↗ (öffnet in neuem Tab), mit eigener Historie und ohne Pipeline und Spiegel-Skript. Wie Externe beitragen, beschreibt dort die CONTRIBUTING.md. Unter jeder Seite stehen dafür diese Wege, auf der Startseite nur die beiden für neue Seiten:

Weg	Wer	Wo es landet
„Feedback geben“	alle, ohne Konto	vertrauliches Issue mit dem Label Feedback im internen Repository
„Auf Codeberg bearbeiten“	mit Codeberg-Konto	Pull Request auf Codeberg
„Als Issue melden“	mit Codeberg-Konto	öffentliches Issue auf Codeberg
„Neue Seite vorschlagen“	alle, ohne Konto	vertrauliches Issue mit dem Label Seitenvorschlag im internen Repository
„Auf Codeberg schreiben“	mit Codeberg-Konto	neue Datei im Bereich der aktuellen Seite, als Pull Request auf Codeberg

„Auf Codeberg bearbeiten“ und „Auf Codeberg schreiben“ führen auf die Ansicht der Datei beziehungsweise des Ordners, nicht in den Editor. Den Editor öffnet Codeberg nur für Mitglieder der Organisation, alle anderen bekommen dort eine 404. Externe forken deshalb zuerst, ändern in ihrer Kopie und stellen von dort den Pull Request. Mitglied der Organisation muss dafür niemand sein. Bei einer neuen Seite den Eintrag unter nav: in mkdocs.yml beim Übernehmen ergänzen, falls er fehlt, sonst bricht der strikte Build ab.

Beide Formulare senden an den Activepieces-Flow „Developer Portal: Feedback“, dessen Adresse in mkdocs.yml unter extra.feedback_url steht. Der Flow unterscheidet sie am Feld art (hinweis oder seite), prüft die Angaben (Länge, Thema, Köderfeld, Mindestdauer, nur Seiten des Portals) und legt das Issue mit einem Projekt-Token an, das nur Issues anlegen darf. Vertraulich ist es, weil eine E-Mail-Adresse darin stehen kann. Das Token läuft nach einem Jahr ab. Danach meldet das Formular einen Fehler, bis ein neues Token im Flow eingetragen ist.

Pull Requests kommen automatisch herüber:

1. Codeberg meldet jeden neuen oder aktualisierten Pull Request über einen Webhook an den Pipeline-Trigger dieses Projekts.
2. Der Job codeberg-pr (tools/codeberg_pr.py) übernimmt ihn mit git am auf einen Zweig codeberg/pr-<nummer>. Die Commits behalten ihre Autorin oder ihren Autor, fehlende Navigationseinträge für neue Seiten ergänzt der Job selbst. Dann öffnet er einen Merge Request mit dem Label Codeberg.
3. Auf dem Merge Request laufen die Prüfungen. Zusammenführen geht nur, wenn sie grün sind.
4. Nach dem Zusammenführen stellt die Pipeline den Stand in die Vorschau, und der Spiegel schreibt ihn nach Codeberg, mit der Autorin des Beitrags. Dann markiert er den Pull Request dort als zusammengeführt und bedankt sich im Kommentar.

Wird der Pull Request auf Codeberg ohne Übernahme geschlossen, schließt der Job auch den Merge Request.

Nur Markdown unter docs/ geht automatisch. Die Pipeline eines Merge Requests läuft mit dem Inhalt seines Zweigs. Ein Beitrag, der Hooks, Skripte, die Pipeline oder mkdocs.yml ändert, würde fremden Code auf unserem Runner ausführen. Für solche Pull Requests legt der Job stattdessen ein Issue „braucht Handprüfung“ an. Übernehmen lässt er sich dann von Hand:

curl -sL https://codeberg.org/OSPO/OSPO-Developer-Portal/pulls/<nummer>.patch | git am
git push origin main

Danach im Pull Request „Als manuell zusammengeführt markieren“ wählen und den Commit aus dem Spiegel angeben.

Live geht ein übernommener Beitrag wie jede andere Änderung erst mit dem Job deploy-live.

Was dafür eingerichtet ist: ein Webhook auf Codeberg mit dem Pipeline-Trigger-Token dieses Projekts, die CI-Variable GITLAB_PR_TOKEN (Projekt-Token, Rolle Developer, Bereiche api und write_repository) und die CI-Variable CODEBERG_TOKEN (Codeberg-Token mit Schreibrecht für Repository und Issues). Beide Tokens laufen nach spätestens einem Jahr ab.

Auf Codeberg nicht zusammenführen

Der Spiegel legt bei jedem Lauf den internen Stand ab. Was nur auf Codeberg zusammengeführt würde, wäre nach dem nächsten Lauf wieder verschwunden. Deshalb ist dort als einzige Art „Manually merged“ erlaubt.

Anker für den Konfigurations-Assistenten

Der Assistent verlinkt auf das Portal. Die Abschnitte der Seite Konfigurations-Assistent tragen deshalb feste Anker, die den Schritt-Schlüsseln im Assistenten entsprechen, etwa #modell oder #stammdaten. Diese Anker beim Überarbeiten bitte nicht umbenennen. Gesetzt werden sie so:

## Geschäftsmodell {#modell}

Markdown-Hilfen

Code mit Hervorhebung:

```php
<?php
$response = wp_remote_get( 'https://example.org/wp-json/wc/v3/products' );
```

Hinweisboxen:

!!! note "Hinweis"
    Dieser Endpunkt erfordert einen API-Schlüssel.

!!! warning "Achtung"
    Diese Einstellung wirkt erst nach einem Neustart.

Reiter, etwa für den Vergleich zweier Shopsysteme:

=== "WooCommerce"
    REST-API unter `/wp-json/wc/v3/`

=== "Shopware"
    REST-API unter `/api/`