fix(block): put the block diagram title in the front matter

.github/workflows/doc_render.yml

@@ -1,9 +1,9 @@
 name: DocRender
 
 # This package exists to emit markdown, so "does the output render" is part of
-# its contract. The Go tests only compare strings; this job runs the real
-# mermaid parser over every diagram committed here, which is the closest thing
-# to what a reader's browser does with them.
+# its contract. The Go tests only compare strings; this job draws every diagram
+# committed here with the real mermaid renderer in a real browser, which is what
+# a reader's browser does with them.
 on:
   workflow_dispatch:
   push:
@@ -16,7 +16,7 @@ permissions:
 
 jobs:
   mermaid:
-    name: Parse committed mermaid diagrams
+    name: Render committed mermaid diagrams
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
@@ -30,11 +30,24 @@ jobs:
           cache: npm
           cache-dependency-path: scripts/mermaid-check/package-lock.json
 
-      - name: Install the mermaid parser
+      # Rendering needs the layout and text measurement only a browser has, so
+      # npm ci pulls the Chrome build puppeteer pins. It lands in ~/.cache and
+      # the download is the slow part, hence the cache.
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/puppeteer
+          key: puppeteer-${{ runner.os }}-${{ hashFiles('scripts/mermaid-check/package-lock.json') }}
+
+      - name: Install the mermaid renderer
         run: npm ci
         working-directory: scripts/mermaid-check
 
-      - name: Parse every mermaid block
+      # A checker that catches nothing looks like a checker with nothing to
+      # catch, so the fixtures run first.
+      - name: Check the checker
+        run: node scripts/mermaid-check/selftest.mjs
+
+      - name: Render every mermaid block
         # NUL-delimited so a path containing whitespace stays one argument.
         run: git ls-files -z '*.md' | node scripts/mermaid-check/check.mjs --stdin0
 

CONTRIBUTING.md

@@ -2,6 +2,7 @@
 - When creating a bug report: Please follow the template and provide detailed information.
 - When fixing a feature: Create a Pull Request (PR) with accompanying test code.
 - When adding a feature: First, propose the feature in an Issue.
+- When touching a mermaid builder: Run `make generate` to refresh the samples under `doc/`, then `make render-check`. The latter draws every diagram committed here with the real mermaid renderer, which is the only thing that catches a diagram that ships, parses, and still shows the reader something else.
 
 ## Contributing Outside of Coding
 The following actions help boost my motivation:

Makefile

@@ -28,8 +28,9 @@ lint: ## Run linter
 generate: ## Regenerate the sample documents under doc/ (CheckAutoGenerateFiles verifies these)
 	$(GO) generate ./...
 
-render-check: ## Parse every mermaid diagram committed in this repository (requires node)
+render-check: ## Render every mermaid diagram committed in this repository (requires node)
 	cd scripts/mermaid-check && npm ci
+	node scripts/mermaid-check/selftest.mjs
 	git ls-files -z '*.md' | node scripts/mermaid-check/check.mjs --stdin0
 
 .DEFAULT_GOAL := help

README.md

@@ -501,7 +501,7 @@ Plain text output: [markdown is here](./doc/gitgraph/generated.md)
 ## Git Graph
 ```mermaid
 ---
-title: Release Flow
+title: "Release Flow"
 ---
 gitGraph
     commit id: "init" tag: "v0.1.0"
@@ -516,7 +516,7 @@ gitGraph
 Mermaid output:
 ```mermaid
 ---
-title: Release Flow
+title: "Release Flow"
 ---
 gitGraph
     commit id: "init" tag: "v0.1.0"
@@ -571,7 +571,7 @@ Plain text output: [markdown is here](./doc/mindmap/generated.md)
 ## Mindmap
 ```mermaid
 ---
-title: Product Strategy Mindmap
+title: "Product Strategy Mindmap"
 ---
 mindmap
     Product Strategy
@@ -587,7 +587,7 @@ mindmap
 Mermaid output:
 ```mermaid
 ---
-title: Product Strategy Mindmap
+title: "Product Strategy Mindmap"
 ---
 mindmap
     Product Strategy
@@ -665,7 +665,7 @@ Plain text output: [markdown is here](./doc/requirement/generated.md)
 ## Requirement Diagram
 ```mermaid
 ---
-title: Checkout Requirements
+title: "Checkout Requirements"
 ---
 requirementDiagram
     direction TB
@@ -695,7 +695,7 @@ requirementDiagram
 Mermaid output:
 ```mermaid
 ---
-title: Checkout Requirements
+title: "Checkout Requirements"
 ---
 requirementDiagram
     direction TB
@@ -892,8 +892,10 @@ Plain text output: [markdown is here](./doc/block/generated.md)
 ````text
 ## Block Diagram
 ```mermaid
+---
+title: "Checkout Architecture"
+---
 block
-    title Checkout Architecture
     columns 3
     Frontend toBackend<["calls"]>(right) Backend
     space:2 toDB<["&nbsp;"]>(down)
@@ -905,8 +907,10 @@ block
 
 Mermaid output:
 ```mermaid
+---
+title: "Checkout Architecture"
+---
 block
-    title Checkout Architecture
     columns 3
     Frontend toBackend<["calls"]>(right) Backend
     space:2 toDB<["&nbsp;"]>(down)
@@ -962,7 +966,7 @@ Plain text output: [markdown is here](./doc/kanban/generated.md)
 ## Kanban Diagram
 ```mermaid
 ---
-title: Sprint Board
+title: "Sprint Board"
 config:
   kanban:
     ticketBaseUrl: 'https://example.com/tickets/'
@@ -979,7 +983,7 @@ kanban
 Mermaid output:
 ```mermaid
 ---
-title: Sprint Board
+title: "Sprint Board"
 config:
   kanban:
     ticketBaseUrl: 'https://example.com/tickets/'
@@ -1222,7 +1226,7 @@ Plain text output: [markdown is here](./doc/flowchart/generated.md)
 ## Flowchart
 ```mermaid
 ---
-title: mermaid flowchart builder
+title: "mermaid flowchart builder"
 ---
 flowchart TB
 	A["Node A"]
@@ -1504,7 +1508,7 @@ Plain text output: [markdown is here](./doc/state/generated.md)
 ## State Diagram
 ```mermaid
 ---
-title: Order State Machine
+title: "Order State Machine"
 ---
 stateDiagram-v2
     [*] --> Pending
@@ -1527,7 +1531,7 @@ stateDiagram-v2
 Mermaid output:
 ```mermaid
 ---
-title: Order State Machine
+title: "Order State Machine"
 ---
 stateDiagram-v2
     [*] --> Pending
@@ -1611,7 +1615,7 @@ Plain text output: [markdown is here](./doc/class/generated.md)
 ## Class Diagram
 ```mermaid
 ---
-title: Checkout Domain
+title: "Checkout Domain"
 ---
 classDiagram
     direction LR
@@ -1637,7 +1641,7 @@ classDiagram
 Mermaid output:
 ```mermaid
 ---
-title: Checkout Domain
+title: "Checkout Domain"
 ---
 classDiagram
     direction LR

doc/block/generated.md

@@ -1,8 +1,10 @@
 ## Block Diagram
 
 ```mermaid
+---
+title: "Checkout Architecture"
+---
 block
-    title Checkout Architecture
     columns 3
     Frontend toBackend<["calls"]>(right) Backend
     space:2 toDB<["&nbsp;"]>(down)

doc/class/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: Checkout Domain
+title: "Checkout Domain"
 ---
 classDiagram
     direction LR

doc/flowchart/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: mermaid flowchart builder
+title: "mermaid flowchart builder"
 ---
 flowchart TB
     A["Node A"]

doc/gitgraph/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: Release Flow
+title: "Release Flow"
 ---
 gitGraph
     commit id: "init" tag: "v0.1.0"

doc/kanban/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: Sprint Board
+title: "Sprint Board"
 config:
   kanban:
     ticketBaseUrl: 'https://example.com/tickets/'

doc/mindmap/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: Product Strategy Mindmap
+title: "Product Strategy Mindmap"
 ---
 mindmap
     Product Strategy

doc/requirement/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: Checkout Requirements
+title: "Checkout Requirements"
 ---
 requirementDiagram
     direction TB

doc/state/generated.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 ---
-title: Order State Machine
+title: "Order State Machine"
 ---
 stateDiagram-v2
     [*] --> Pending

internal/frontmatter.go

@@ -0,0 +1,31 @@
+// Package internal package is used to store the internal implementation of the mermaid package.
+package internal
+
+import (
+	"fmt"
+	"strconv"
+)
+
+// FrontMatterTitle returns the `title:` line of a mermaid front matter block.
+//
+// The value is always a double quoted YAML scalar, because mermaid runs the
+// front matter through a YAML parser before it draws anything and a bare scalar
+// is not safe to build from arbitrary text. "Checkout: API" and "*ref" make that
+// parser throw, which loses the whole diagram; "Checkout # API" is truncated at
+// the comment, and "~", "# Checkout" and "&anchor" resolve to something that is
+// not the title at all. Quoting removes every one of those readings.
+func FrontMatterTitle(title string) string {
+	return fmt.Sprintf("title: %s", quoteYAML(title))
+}
+
+// quoteYAML returns value as a double quoted YAML scalar.
+//
+// strconv.Quote does the escaping because Go's double quoted form and YAML's
+// agree on every escape it emits: \\, \", the \a \b \f \n \r \t \v shorthands,
+// and the \xNN, \uNNNN and \UNNNNNNNN forms for everything else. Hand rolling
+// the replacements misses the control characters that have no shorthand, and a
+// literal control character inside a quoted scalar is a parse error, which loses
+// the whole diagram rather than mangling one line of it.
+func quoteYAML(value string) string {
+	return strconv.Quote(value)
+}