feat(mermaid): interactive Mermaid diagrams (0.6.0)

CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here. Format loosely
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions
 track `packages/framework`'s own `package.json`.
 
+## [0.6.0] — 2026-09-27
+
+### Added
+
+- **Mermaid diagrams** (`@inkform/framework/mermaid`) — ` ```mermaid ` fences
+  (or `<Mermaid chart="…" />`) render as interactive diagrams: Ctrl/⌘ + scroll,
+  pinch, double-click, or keyboard to zoom; drag to pan; a fullscreen view with a
+  minimap for large graphs; copy source and SVG download. Colors come from the
+  `--fw-*` tokens and follow light/dark switches. A caption goes in the fence
+  meta: ` ```mermaid title="…" `.
+- **Opt-in by design** — `mermaid` is an optional peer dependency. Sites that
+  never draw diagrams don't install it; unregistered fences render as a plain
+  source block. The scaffolded templates ship with it on. Readers only download
+  mermaid (and the viewer) on pages that have a diagram, when it nears the
+  viewport.
+- `remarkMermaid`, exported from `@inkform/framework/mdx`, for hosts with their
+  own MDX pipeline.
+
+### Changed
+
+- Templates and examples now depend on `@inkform/framework@^0.6.0`.
+
+### Fixed
+
+- **Inline colons no longer vanish.** remark-directive read any `:word` in
+  running text ("re:Work", "Note:this") as a text directive, which `<Mdx>`
+  rendered as an empty `<div>` inside the paragraph: the text after the colon
+  disappeared and React threw a hydration error. Unknown text directives now go
+  back to literal text, in both `<Mdx>` and the per-page Markdown output.
+
 ## [0.5.0] — 2026-08-30
 
 ### Added

README.md

@@ -79,6 +79,7 @@ To embed the engine in an existing Next.js app or build a custom theme from scra
 | **AI ask-box** | BYO model (Anthropic, OpenAI, or Google) and API key. Answers are grounded in your actual content with cited sources. |
 | **`/llms.txt` out of the box** | The [llms.txt](https://llmstxt.org) convention — a curated index and full-corpus export for LLMs and agentic tools. |
 | **Full-text search** | [Pagefind](https://pagefind.app/) indexes your built HTML at deploy time. Fast, client-side, no server required. |
+| **Diagrams** | ` ```mermaid ` fences become zoomable, pannable diagrams themed to your site — with a fullscreen view, minimap, and SVG download. Mermaid only loads on pages that have one. |
 | **Blog & changelog** | Drop files in `content/blog/` or `content/changelog/` — routes and nav links appear automatically. |
 | **Own your deployment** | A normal Next.js app. Ship to Vercel, AWS Amplify, a container, or a subpath on an existing site. |
 | **Genuinely open** | MIT licensed. No telemetry, no required account, no lock-in. |

examples/inkform-docs/content/docs/docs.json

@@ -35,6 +35,7 @@
         { "title": "Add a Blog to an Existing Site", "slug": "guides/blog-in-existing-site", "file": "guides/blog-in-existing-site.mdx", "icon": "layers" },
         { "title": "Changelog", "slug": "guides/changelog", "file": "guides/changelog.mdx", "icon": "map" },
         { "title": "Widgets", "slug": "guides/widgets", "file": "guides/widgets.mdx", "icon": "blocks" },
+        { "title": "Diagrams", "slug": "guides/diagrams", "file": "guides/diagrams.mdx", "icon": "image" },
         { "title": "Comments, Reactions & Subscribe Forms", "slug": "guides/interactive", "file": "guides/interactive.mdx", "icon": "heart" },
         { "title": "Claude Code Skill", "slug": "guides/claude-code-skill", "file": "guides/claude-code-skill.mdx", "icon": "sparkles" }
       ]

examples/inkform-docs/content/docs/guides/diagrams.mdx

@@ -0,0 +1,182 @@
+---
+title: Diagrams
+description: Mermaid diagrams in any MDX page — written as a fenced code block, rendered as a zoomable, pannable figure.
+---
+
+# Diagrams
+
+Write a fenced code block with the language set to `mermaid` and it renders as a diagram:
+
+````md
+```mermaid
+flowchart LR
+  Draft --> Review --> Publish
+```
+````
+
+```mermaid title="The smallest useful diagram"
+flowchart LR
+  Draft --> Review --> Publish
+```
+
+Hover a diagram (or tab to it) for the toolbar: zoom, copy the source, download an SVG, or open it fullscreen. In fullscreen there's a minimap for finding your way around large graphs.
+
+## Setup
+
+Diagrams are opt-in, because `mermaid` is a large install and plenty of docs sites never draw one. The scaffolded templates already have it on. For an existing site:
+
+```bash
+npm i mermaid
+```
+
+```ts
+// mdx-components.tsx
+import { mdxComponents } from '@inkform/framework/components';
+import { Mermaid } from '@inkform/framework/mermaid';
+
+export const siteMdxComponents = mdxComponents({ Mermaid });
+```
+
+Without that registration, `mermaid` fences still build — they render as a plain block of source, so nothing breaks while you decide.
+
+Readers only download mermaid on pages that have a diagram, and only when one is about to scroll into view. Pages without diagrams ship none of it.
+
+## Captions
+
+Put `title="…"` (or `caption="…"`) after the language. It shows under the diagram, names the fullscreen view and the downloaded file, and is what screen readers announce.
+
+````md
+```mermaid title="Request lifecycle"
+sequenceDiagram
+  ...
+```
+````
+
+```mermaid title="Request lifecycle"
+sequenceDiagram
+  participant B as Browser
+  participant E as Edge
+  participant A as App
+  participant D as Database
+  B->>E: GET /docs/quickstart
+  E->>E: Cache lookup
+  alt cache hit
+    E-->>B: 200 (cached HTML)
+  else cache miss
+    E->>A: Render page
+    A->>D: Load content
+    D-->>A: MDX source
+    A-->>E: HTML
+    E-->>B: 200
+  end
+```
+
+The JSX form works too, if you're building the source in an expression:
+
+```mdx
+<Mermaid caption="Build pipeline" chart={`flowchart LR
+  A --> B`} />
+```
+
+## Moving around
+
+| Where | Zoom | Pan |
+| --- | --- | --- |
+| In the page | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + scroll, trackpad pinch, double-click, or `+` / `-` | Drag once zoomed in, or arrow keys |
+| Fullscreen | Scroll, pinch, double-click | Drag, arrow keys, or click the minimap |
+| Touch | Pinch | One finger once zoomed in |
+
+A plain scroll over an inline diagram scrolls the page, not the diagram, so long posts don't trap the reader. `0` resets to fit.
+
+## Theming
+
+Diagrams take their colors from the site's `--fw-*` tokens, so they match whichever theme you run, and they redraw when the reader switches between light and dark. Styles written in the diagram itself (`style A fill:#111,color:#fff`) still win.
+
+## Big graphs
+
+Large diagrams are where the viewer earns its keep. Open this one fullscreen and use the minimap:
+
+```mermaid title="Content pipeline, end to end"
+flowchart TD
+  subgraph Authoring
+    A1[Write MDX] --> A2[Preview locally]
+    A2 --> A3{Looks right?}
+    A3 -- no --> A1
+    A3 -- yes --> A4[Open PR]
+  end
+  subgraph Review
+    A4 --> R1[CI: typecheck + tests]
+    R1 --> R2[CI: link check]
+    R2 --> R3[Preview deploy]
+    R3 --> R4{Approved?}
+    R4 -- changes --> A1
+  end
+  subgraph Build
+    R4 -- merge --> B1[Load content]
+    B1 --> B2[Parse frontmatter]
+    B2 --> B3[Compile MDX]
+    B3 --> B4[Highlight code]
+    B3 --> B5[Collect headings]
+    B5 --> B6[Build TOC]
+    B1 --> B7[Parse OpenAPI]
+    B7 --> B8[Operation pages]
+    B4 --> B9[Static HTML]
+    B6 --> B9
+    B8 --> B9
+  end
+  subgraph Ship
+    B9 --> S1[Pagefind index]
+    B9 --> S2[llms.txt]
+    B9 --> S3[Per-page .md]
+    S1 --> S4[Deploy]
+    S2 --> S4
+    S3 --> S4
+    S4 --> S5((Live))
+  end
+```
+
+## Other diagram types
+
+Anything Mermaid supports renders — state machines, ER diagrams, Gantt charts, mindmaps, and more.
+
+```mermaid title="Subscription states"
+stateDiagram-v2
+  [*] --> Trial
+  Trial --> Active: pays
+  Trial --> Expired: 14 days
+  Active --> PastDue: card fails
+  PastDue --> Active: retry succeeds
+  PastDue --> Canceled: 3 failures
+  Active --> Canceled: cancels
+  Canceled --> [*]
+```
+
+```mermaid title="What a docs site needs"
+mindmap
+  root((Docs site))
+    Content
+      Guides
+      API reference
+      Changelog
+    Discovery
+      Search
+      llms.txt
+      Per-page Markdown
+    Trust
+      Versioning
+      Examples that run
+```
+
+```mermaid title="Where the time goes"
+pie
+  "Writing" : 45
+  "Review" : 25
+  "Diagrams" : 20
+  "Deploy" : 10
+```
+
+## Writing diagrams with AI
+
+Mermaid is plain text, and it's the diagram format language models write most reliably — ask for "a Mermaid flowchart of …" and paste the result into a fence. The source stays in your MDX, so it diffs, reviews, and renders on GitHub too. The per-page Markdown (any URL + `.md`) and `llms.txt` output keep the fence as-is, so agents reading your docs see the diagram source rather than an image.
+
+If the source has a syntax error, the page shows mermaid's error message next to the source instead of an empty box.

examples/inkform-docs/content/docs/reference/framework-api.mdx

@@ -66,7 +66,8 @@ Types: `OpenApiModel`, `ApiOperation`, `ApiParam`, `ApiBody`, `ApiResponse`,
 
 | Export | Notes |
 | --- | --- |
-| `Mdx({ source, components? })` | Async server component. Renders an MDX string with GFM, `:::callout` directives, Shiki-highlighted code, heading slugs, and all built-in blocks. Self-wraps output in `.fw-prose`. |
+| `Mdx({ source, components? })` | Async server component. Renders an MDX string with GFM, `:::callout` directives, Shiki-highlighted code, ` ```mermaid ` fences as `<Mermaid>`, heading slugs, and all built-in blocks. Self-wraps output in `.fw-prose`. |
+| `remarkMermaid` | The remark plugin behind the fence → `<Mermaid chart="…" caption="…">` conversion, for hosts running their own MDX pipeline. |
 
 ## `@inkform/framework/docs-shell`
 
@@ -86,10 +87,20 @@ The built-in MDX block library — `Note`, `Tip`, `Info`, `Warning`, `Danger`,
 `Check` (callout variants), `Card`, `CardGroup`, `Columns`, `Steps`/`Step`,
 `Tabs`/`Tab`, `CodeGroup`, `Accordion`/`AccordionGroup`, `ParamField`,
 `ResponseField`, `Expandable`, `Frame`, `Tooltip`, `Embed`, `Hero`,
-`AuthorBio`, `RelatedPosts`, `NewsletterCTA`, and `ApiLink`. Also exports
+`AuthorBio`, `RelatedPosts`, `NewsletterCTA`, `ApiLink`, and `Mermaid` (the static
+source-block fallback — see `./mermaid` below). Also exports
 `mdxComponents(customWidgets)` — merges your `widgets/index.ts` registry with
 every built-in block into the map `<Mdx components={...} />` expects.
 
+## `@inkform/framework/mermaid`
+
+Opt-in; needs the `mermaid` package installed (an optional peer dependency). See
+[Diagrams](/guides/diagrams).
+
+| Export | Notes |
+| --- | --- |
+| `Mermaid({ chart, caption? })` | Client component. Register with `mdxComponents({ Mermaid })`. Lazy-loads mermaid and the viewer when the diagram nears the viewport; themed from `--fw-*` tokens; pan/zoom, fullscreen with minimap, copy source, SVG download. |
+
 ## `@inkform/framework/scalar-theme`
 
 | Export | Notes |

examples/inkform-docs/mdx-components.tsx

@@ -1,4 +1,5 @@
 import { mdxComponents } from '@inkform/framework/components';
+import { Mermaid } from '@inkform/framework/mermaid';
 import widgets from '@/widgets';
 
 /**
@@ -7,5 +8,9 @@ import widgets from '@/widgets';
  * Tabs, CodeGroup, Accordion, ParamField, …). Custom widgets registered in
  * widgets/index.ts are merged in here, so <YourWidget /> in MDX/CMS content
  * resolves to the real component instead of the unknown-component fallback.
+ *
+ * Mermaid makes ```mermaid fences interactive diagrams (pan, zoom,
+ * fullscreen). Not drawing diagrams? Drop this import and the `mermaid`
+ * dependency — fences then render as a plain source block.
  */
-export const siteMdxComponents = mdxComponents(widgets);
+export const siteMdxComponents = mdxComponents({ Mermaid, ...widgets });

examples/inkform-docs/package.json

@@ -12,8 +12,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@inkform/framework": "^0.5.0",
+    "@inkform/framework": "^0.6.0",
     "lucide-react": "^0.483.0",
+    "mermaid": "^12.0.0",
     "next": "16.3.6",
     "react": "19.2.1",
     "react-dom": "19.2.1"

examples/markdown-docs/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@inkform/framework": "^0.5.0",
+    "@inkform/framework": "^0.6.0",
     "lucide-react": "^0.483.0",
     "next": "16.3.6",
     "react": "19.2.1",

examples/pokeapi-docs/package.json

@@ -13,7 +13,7 @@
     "test:e2e": "playwright test"
   },
   "dependencies": {
-    "@inkform/framework": "^0.5.0",
+    "@inkform/framework": "^0.6.0",
     "lucide-react": "^0.483.0",
     "next": "16.3.6",
     "react": "19.2.1",