ci(docs): add mermaid render lint to catch diagram syntax regressions - #233
Merged
Conversation
Add an isolated Mermaid render check (mmdc) that runs only on PRs touching READMEs/docs. Unlike the text-only label linter, it renders every mermaid block and fails fast on invalid syntax. Kept in its own workflow to isolate the headless-Chromium dependency. Closes #214
There was a problem hiding this comment.
Pull request overview
Adds an isolated GitHub Actions workflow to render-check Mermaid diagrams in Markdown, catching syntax regressions that text-only checks can miss, without introducing Chromium dependencies into the main docs build.
Changes:
- Add
scripts/render_mermaid.pyto extract and render all fenced ```mermaid blocks viammdc, failing CI on render errors. - Add
scripts/puppeteer-config.jsonto run Chromium in CI containers (no-sandbox flags). - Add
.github/workflows/mermaid-lint.ymlto run the render lint on PRs that touch docs/READMEs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| scripts/render_mermaid.py | Implements Mermaid extraction + mmdc render-lint for Markdown docs. |
| scripts/puppeteer-config.json | Puppeteer args for Chromium execution in CI. |
| .github/workflows/mermaid-lint.yml | New isolated workflow to run the Mermaid render-lint on relevant PRs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+4
to
+6
| Unlike ``lint_mermaid.py`` (label-hygiene only), this script actually renders | ||
| every ```mermaid``` fenced block with the Mermaid CLI (``mmdc``). Invalid | ||
| syntax that a text linter cannot detect will fail the render, and therefore CI. |
Comment on lines
+37
to
+38
| # Puppeteer config so Chromium runs in sandboxed CI containers. | ||
| PUPPETEER_CONFIG = REPO_ROOT / "scripts" / "puppeteer-config.json" |
Comment on lines
+70
to
+71
| buffer.append(raw) | ||
| return blocks |
Comment on lines
+112
to
+115
| for path in targets: | ||
| for start_line, source in _extract_blocks(path): | ||
| if not source.strip(): | ||
| continue |
Comment on lines
+88
to
+92
| cmd += ["--puppeteerConfigFile", str(PUPPETEER_CONFIG)] | ||
| proc = subprocess.run(cmd, capture_output=True, text=True) | ||
| if proc.returncode != 0: | ||
| detail = (proc.stderr or proc.stdout or "").strip() | ||
| return False, detail |
Comment on lines
+40
to
+41
| - name: Install mermaid-cli | ||
| run: npm install -g @mermaid-js/mermaid-cli |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
scripts/render_mermaid.py: renders everymermaidblock viammdcand fails on invalid syntax (catches errors the text-only label linter cannot).scripts/puppeteer-config.json:--no-sandboxconfig so Chromium runs in CI containers..github/workflows/mermaid-lint.yml: isolated workflow triggered only on PRs touchingREADME*/docs/**, keeping the headless-Chromium dependency out of the main docs build.Verification
file:lineon a deliberately broken diagram → exit 1.Closes #214