docs: add an architecture page for contributors, move the syntax reference under Using the CLI, vendor docs kit 1.26.0

.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
         if: env.CI_SOURCE_TOKEN != ''
         with:
           repository: Miragon/corporate-identity
-          ref: v1.10.0
+          ref: v1.26.0
           token: ${{ env.CI_SOURCE_TOKEN }}
           path: .ci-source
           sparse-checkout: plugins/miragon-brand

README.md

@@ -114,7 +114,7 @@ Details: [library use](https://miragon.github.io/bpmn-cli/library), [validators]
 The docs site, [miragon.github.io/bpmn-cli](https://miragon.github.io/bpmn-cli/), is built from [docs/](docs/):
 
 - [Command reference](https://miragon.github.io/bpmn-cli/commands): every command with its options
-- [Reference](https://miragon.github.io/bpmn-cli/reference): ids, kinds, triggers, placement, set keys, output, errors and exit codes
+- [Syntax and output](https://miragon.github.io/bpmn-cli/reference): ids, kinds, triggers, placement, set keys, output, errors and exit codes
 - [Ops JSON](https://miragon.github.io/bpmn-cli/ops): the batch format of `bpmn apply`
 - [Layout and formatting](https://miragon.github.io/bpmn-cli/layout): layout modes and the diagram-only commands
 - [The contract and its limits](https://miragon.github.io/bpmn-cli/contract): what the CLI guarantees, what a write changes, limitations

docs/.vitepress/config.ts

@@ -23,9 +23,8 @@ export default miragonDocs({
       link: "/getting-started",
       activeMatch: "^/(getting-started|claude-code-plugin|walkthrough|contract)",
     },
-    { text: "Commands", link: "/commands", activeMatch: "^/(commands|ops|camunda|layout|bpmnlint)" },
+    { text: "Commands", link: "/commands", activeMatch: "^/(commands|reference|ops|camunda|layout|bpmnlint)" },
     { text: "Library", link: "/library", activeMatch: "^/(library|validators)" },
-    { text: "Reference", link: "/reference", activeMatch: "^/reference" },
   ],
 
   // One sidebar for every page: the CLI is small enough to show it all.
@@ -43,6 +42,7 @@ export default miragonDocs({
       text: "Using the CLI",
       items: [
         { text: "Commands", link: "/commands" },
+        { text: "Syntax and output", link: "/reference" },
         { text: "Ops JSON (bpmn apply)", link: "/ops" },
         { text: "Camunda 7 and Camunda 8", link: "/camunda" },
         { text: "Layout and formatting", link: "/layout" },
@@ -57,9 +57,9 @@ export default miragonDocs({
       ],
     },
     {
-      text: "Reference",
+      text: "Contributing",
       items: [
-        { text: "Ids, kinds and keys", link: "/reference" },
+        { text: "Architecture", link: "/architecture" },
       ],
     },
   ],

docs/.vitepress/miragon/manifest.json

@@ -1,6 +1,6 @@
 {
   "$kommentar": "Generiert von scripts/sync-assets.mjs in Miragon/corporate-identity, nicht von Hand ändern. Jede Datei, die ein Repo aus der Skill docs-site vendort: Pfad im Repo, Quelle unter plugins/miragon-brand/skills/docs-site/assets/ und sha256. check.mjs prüft die Kopie damit.",
-  "version": "1.25.1",
+  "version": "1.26.0",
   "dateien": [
     {
       "pfad": "docs/.vitepress/miragon/check.mjs",
@@ -42,6 +42,11 @@
       "quelle": "miragon/theme/StarPrompt.vue",
       "sha256": "38a7de32637193b43f9eb3dedd79584a9f11ee1a0ffd4f428aa2f30ba3af18fa"
     },
+    {
+      "pfad": "docs/.vitepress/miragon/theme/ZoomOverlay.vue",
+      "quelle": "miragon/theme/ZoomOverlay.vue",
+      "sha256": "387a2ecd0465e4b158431f34edb7dea2feff5a62cf84b5622520c43829c290c7"
+    },
     {
       "pfad": "docs/.vitepress/miragon/theme/cd-tokens.generated.css",
       "quelle": "miragon/theme/cd-tokens.generated.css",
@@ -50,12 +55,12 @@
     {
       "pfad": "docs/.vitepress/miragon/theme/index.ts",
       "quelle": "miragon/theme/index.ts",
-      "sha256": "dda90b8c056e558ac01f2de1a4f38c918d50339af5d59c87ddd710e09195ccd9"
+      "sha256": "450a3ab3603426b0b7aa1d751976998b5e52341ed110245ada6658f9d1097b99"
     },
     {
       "pfad": "docs/.vitepress/miragon/theme/miragon.css",
       "quelle": "miragon/theme/miragon.css",
-      "sha256": "5c43dc675cf7d718e42f7089e1bb274f1198bf1049d7997b108fe3724f05a4df"
+      "sha256": "3253247af1fb53006694a2db7a3a1d001cb6875dfb64fbb55a840c062df74344"
     },
     {
       "pfad": "docs/.vitepress/miragon/theme/useStars.ts",

docs/.vitepress/miragon/theme/ZoomOverlay.vue

@@ -0,0 +1,81 @@
+<!--
+  Miragon-Doku-Kit: Bilder und Diagramme im Vollbild. Ein Klick auf ein Bild, ein Mermaid-Diagramm
+  oder ein Element mit data-zoom in einer Seite öffnet eine Kopie davon in einem Overlay über der
+  ganzen Seite. Esc, ein Klick daneben oder × schließt es. data-zoom="off" nimmt ein Element aus,
+  Bilder in Links bleiben Links. Aussehen in theme/miragon.css (Abschnitt ZOOM).
+
+  Quelle: Miragon/corporate-identity, Skill docs-site. Im Repo unverändert unter
+  docs/.vitepress/miragon/theme/ZoomOverlay.vue.
+-->
+<script setup lang="ts">
+import { nextTick, onBeforeUnmount, onMounted, ref } from "vue"
+
+const ZOOMBAR = ".vp-doc img, .vp-doc .mermaid, .vp-doc [data-zoom]"
+
+const offen = ref(false)
+const buehne = ref<HTMLElement>()
+const schliessen = ref<HTMLButtonElement>()
+let vorher: HTMLElement | null = null
+
+function zoombar(ziel: EventTarget | null): HTMLElement | undefined {
+  if (!(ziel instanceof Element)) return undefined
+  const element = ziel.closest<HTMLElement>(ZOOMBAR)
+  if (!element || element.closest('[data-zoom="off"]') || element.closest("a")) return undefined
+  if (element.matches(".mermaid") && !element.querySelector("svg")) return undefined
+  return element.closest<HTMLElement>(".vp-doc [data-zoom]") ?? element
+}
+
+async function oeffne(element: HTMLElement) {
+  vorher = document.activeElement as HTMLElement | null
+  offen.value = true
+  await nextTick()
+  const kopie = element.cloneNode(true) as HTMLElement
+  kopie.removeAttribute("id")
+  kopie.classList.add("miragon-zoom-kopie")
+  buehne.value?.replaceChildren(kopie)
+  document.body.classList.add("miragon-zoom-offen")
+  schliessen.value?.focus()
+}
+
+function zu() {
+  offen.value = false
+  buehne.value?.replaceChildren()
+  document.body.classList.remove("miragon-zoom-offen")
+  vorher?.focus()
+}
+
+function beiKlick(event: MouseEvent) {
+  if (offen.value || event.defaultPrevented || event.button !== 0) return
+  const element = zoombar(event.target)
+  if (!element) return
+  event.preventDefault()
+  void oeffne(element)
+}
+
+function beiTaste(event: KeyboardEvent) {
+  if (offen.value && event.key === "Escape") zu()
+}
+
+onMounted(() => {
+  document.addEventListener("click", beiKlick)
+  document.addEventListener("keydown", beiTaste)
+})
+onBeforeUnmount(() => {
+  document.removeEventListener("click", beiKlick)
+  document.removeEventListener("keydown", beiTaste)
+  if (offen.value) zu()
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="offen" class="miragon-zoom" role="dialog" aria-modal="true" @click.self="zu">
+      <div ref="buehne" class="miragon-zoom-buehne" @click.self="zu" />
+      <button ref="schliessen" class="miragon-zoom-zu" type="button" aria-label="Close" @click="zu">
+        <svg viewBox="0 0 16 16" aria-hidden="true">
+          <path d="M3 3l10 10M13 3L3 13" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+        </svg>
+      </button>
+    </div>
+  </Teleport>
+</template>

docs/.vitepress/miragon/theme/index.ts

@@ -29,6 +29,7 @@ import "./miragon.css"
 import LegalRow from "./LegalRow.vue"
 import GitHubStars from "./GitHubStars.vue"
 import StarPrompt from "./StarPrompt.vue"
+import ZoomOverlay from "./ZoomOverlay.vue"
 
 // Im Titel jeder Seite steht der Komet statt der Wortmarke, daneben der Produktname
 // (theme/miragon.css, Abschnitt TITEL: KOMET UND PRODUKTNAME).
@@ -40,15 +41,16 @@ const Komet: FunctionalComponent = () =>
     h("path", { d: KOMET, fill: "#00E676" }),
   ])
 // Das Layout von VitePress mit GitHub und Sternen im Header, der Bitte um einen Stern am
-// Seitenende und der Rechtsleiste ganz unten. Slots von außen reicht es weiter,
+// Seitenende, der Rechtsleiste ganz unten und dem Vollbild für Bilder und Diagramme
+// (ZoomOverlay.vue). Slots von außen reicht es weiter,
 // auch einen eigenen layout-bottom, der dann über der Rechtsleiste steht.
 const Layout: FunctionalComponent = (_, { slots }) =>
   h(DefaultTheme.Layout, null, {
     ...slots,
     "nav-bar-title-before": () => [slots["nav-bar-title-before"]?.(), h(Komet)],
     "nav-bar-content-after": () => [slots["nav-bar-content-after"]?.(), h(GitHubStars)],
     "doc-footer-before": () => [slots["doc-footer-before"]?.(), h(StarPrompt)],
-    "layout-bottom": () => [slots["layout-bottom"]?.(), h(LegalRow)],
+    "layout-bottom": () => [slots["layout-bottom"]?.(), h(LegalRow), h(ZoomOverlay)],
   })
 
 const MiragonTheme: Theme = {

docs/.vitepress/miragon/theme/miragon.css

@@ -643,6 +643,76 @@
   color: var(--cd-gruen);
 }
 
+/* =========================================================
+   ZOOM
+   Bilder, Mermaid-Diagramme und Elemente mit data-zoom öffnen sich im
+   Vollbild (ZoomOverlay.vue). Das Overlay ist die Seite selbst, ohne
+   Deckkraft, damit die Farben des Diagramms hell und dunkel bleiben. Die
+   Kopie wächst bis an den Rand, das Seitenverhältnis bleibt.
+   ========================================================= */
+.vp-doc :is(img, .mermaid, [data-zoom]):not([data-zoom="off"], [data-zoom="off"] *, a *) {
+  cursor: zoom-in;
+}
+.miragon-zoom-offen {
+  overflow: hidden;
+}
+.miragon-zoom {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: flex;
+  background: var(--cd-ui-seite);
+  cursor: zoom-out;
+}
+.miragon-zoom-buehne {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  padding: 56px 24px 24px;
+  overflow: auto;
+}
+.miragon-zoom-kopie {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  cursor: default;
+}
+.miragon-zoom-kopie svg,
+img.miragon-zoom-kopie,
+.miragon-zoom-kopie img {
+  width: 100%;
+  height: 100%;
+  max-width: none !important;
+  object-fit: contain;
+}
+.miragon-zoom-zu {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border: 1px solid var(--cd-ui-linie);
+  border-radius: 999px;
+  background: var(--cd-ui-seite);
+  color: var(--cd-ui-text);
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+.miragon-zoom-zu:hover {
+  border-color: var(--cd-ui-kontur);
+}
+.miragon-zoom-zu svg {
+  width: 14px;
+}
+
 /* =========================================================
    FOKUS
    Sichtbarer Tastatur-Fokus über die Rolle: hell blau-link, dunkel blau-hell.