Skill: docs-site

Die Skill für die Doku der Miragon-Repos. Jedes Tool-Repo hat seine Doku als VitePress-Seite in docs/, veröffentlicht auf GitHub Pages unter https://miragon.github.io/<repo>/, und alle sehen gleich aus: Sie nehmen dasselbe Kit aus dieser Skill. Kundenprojekte folgen der Marke des Kunden, dort gilt die Skill nicht.

Plugin	miragon-brand
Aufruf	/miragon-brand:docs-site
Quelle	plugins/miragon-brand/skills/docs-site
Braucht	Ein Repo mit docs/ und Node 20 oder neuer. Das Kit liegt in der Skill.

Was die Skill macht

Aufgabe	Was passiert
Doku einrichten	Kopiert das Kit unverändert nach docs/.vitepress/miragon/ und die Logos nach docs/public/logo/, schreibt config.ts, Theme, package.json, den Workflow für GitHub Pages und .miragon/brand.json aus den Vorlagen.
Auf das Kit umstellen	Ersetzt ein altes Theme mit eigener custom.css durch das Kit, übernimmt nur Navigation, Seitenleiste und Titel und stellt #anker-Links auf die Anker von GitHub um.
Auf ein neues Release heben	Vergleicht das Kit im Repo mit einem Klon dieses Repos (check.mjs --ci) und vendort neu, wenn sich etwas geändert hat.
Prüfen	Kit unverändert, Build ohne tote Links, Anker, Sichtprüfung hell und dunkel, brand-lint.

Das Kit

Eine Funktion für die Konfiguration, ein Theme und die CSS der CI. Das Repo schreibt nur Name, Beschreibung, Navigation und Seitenleiste:

// docs/.vitepress/config.ts
import { miragonDocs } from "./miragon/config"

export default miragonDocs({
  repo: "Miragon/bpmn-cli",
  title: "Miragon BPMN CLI",
  description: "Validate, lint and render BPMN files from the command line.",
  productPage: "https://miragon.ai/tools/bpmn-cli/",
  nav: [{ text: "Getting started", link: "/getting-started" }],
  sidebar: [{ text: "Start", items: [{ text: "Getting started", link: "/getting-started" }] }],
})

Den Rest legt das Kit fest:

• Farben hell und dunkel aus den Rollen --cd-ui-*. miragon.css ist dieselbe Datei, die auch diese Doku lädt. Es gibt sie genau einmal.
• Geist und Geist Mono aus dem Bundle, Wortmarke und Produktname in der Navigation, der Komet als Icon, zwei theme-color.
• Anker wie auf GitHub. Die Doku wird auch auf GitHub gelesen, ein Link auf #changes-from-06 trifft dort und auf der Seite.
• Mermaid in den Rollen der CI: Knoten, Kanten und Text hell und dunkel.
• Rechtsleiste mit Copyright, Impressum und Datenschutz auf jeder Seite, auch auf Seiten mit Seitenleiste und der 404. Diese Doku zeigt dieselbe Leiste auf Deutsch.
• Englisch als Standard, lang: "de-DE" stellt die festen Texte auf Deutsch.
• Prüfskript: check.mjs vergleicht die Kopie im Repo mit dem Manifest und läuft in der CI jedes Repos. Mit --ci <Pfad> vergleicht es zusätzlich mit einem Klon dieses Repos.

Die Pins (VitePress 1.6.4, Geist 5.3.0, Mermaid 11.17.2, vitepress-plugin-mermaid 2.0.17) stehen in der Vorlage für docs/package.json. Alle Optionen von miragonDocs und das Vorgehen Schritt für Schritt stehen in der Skill.

Wann sie triggert

Wenn du in einem Miragon-Repo eine Doku-Seite anlegst, umstellst, prüfst oder auf ein neues Release hebst, den Workflow für GitHub Pages schreibst oder an Konfiguration, Theme oder Farben einer Miragon-Doku arbeitest. Stichworte: „Doku“, „docs site“, „VitePress“, „GitHub Pages“, „docs.yml“. Nicht für Kundenprojekte und nicht für miragon.ai oder miragon.io.

So nutzt du sie

# Marketplace + Plugin (einmalig)
/plugin marketplace add Miragon/corporate-identity
/plugin install miragon-brand@miragon

# Skill gezielt aufrufen
/miragon-brand:docs-site

Oder einfach sagen, was du vorhast: „Stell die Doku von bpmn-cli auf das Kit der CI um“ oder „Heb die Doku auf das neue CI-Release“.

Aufbau

docs-site/
├── SKILL.md                  # Was das Kit festlegt, Optionen, Einrichten, Release, Prüfen
└── assets/
    ├── miragon/              # das Kit, unverändert nach docs/.vitepress/miragon/
    │   ├── config.ts         # miragonDocs(): die ganze VitePress-Konfiguration
    │   ├── legal.ts          # Texte und Links der Rechtsleiste (miragonLegal)
    │   ├── slug.mjs          # Anker wie auf GitHub (Typen in slug.d.mts)
    │   ├── check.mjs         # prüft die Kopie im Repo
    │   ├── manifest.json     # jede Datei mit sha256 und Version (generiert)
    │   └── theme/            # index.ts, LegalRow.vue, miragon.css, cd-tokens.generated.css
    ├── logo/                 # Wortmarke Grün und Weiß, Komet auf Blau (synchronisiert)
    └── vorlagen/             # config.ts, theme-index.ts, package.json, docs.yml, brand.json

Die Token-CSS (Doku-Variante, dunkel über html.dark) und die Logos kopiert npm run assets:sync ins Kit und schreibt das Manifest. Die übrigen Dateien des Kits sind von Hand geschrieben. npm test baut damit eine Beispielseite mit Mermaid, Ankern und 404.

Verwandt

• Dark Mode: die Rollen, aus denen die Farben der Doku kommen.
• corporate-design: Logo, Farben und Webseiten außerhalb der Doku.
• brand-tone: die Texte der Doku.
• brand-review: prüft eine fertige Doku-Seite in beiden Modi.