Fix Mermaid rendering and FIRST history heading hierarchy - #17
Merged
Conversation
zcohen-nerd
commented
Jul 23, 2026
zcohen-nerd
commented
Owner
- Enable @docusaurus/[email protected] (exact core match) with markdown.mermaid: true; brand theme preserved
- Fusion System Blocks: raw wrapper (Jekyll-era) replaced with a fenced mermaid block; direction LR -> TB so the six-node chain renders legibly at all widths (same nodes/edges)
- validate-build.js: guards against raw Mermaid wrappers in published source, raw flowchart text in built HTML, missing diagram chunk or mermaid runtime, duplicate H1 on /frc/history/, and missing Surfer Fleet draft; runs in existing CI validation step
- /frc/history/: duplicate H1 demoted to H2 (CRLF-matching bug in the Batch D split script); exactly one H1 in built output
- Surfer Fleet verified unpublished: draft preserved, redirect to /projects/ intact, absent from sitemap
- Enable @docusaurus/[email protected] (exact core match) with markdown.mermaid: true; brand theme preserved - Fusion System Blocks: raw <div class="mermaid"> wrapper (Jekyll-era) replaced with a fenced mermaid block; direction LR -> TB so the six-node chain renders legibly at all widths (same nodes/edges) - validate-build.js: guards against raw Mermaid wrappers in published source, raw flowchart text in built HTML, missing diagram chunk or mermaid runtime, duplicate H1 on /frc/history/, and missing Surfer Fleet draft; runs in existing CI validation step - /frc/history/: duplicate H1 demoted to H2 (CRLF-matching bug in the Batch D split script); exactly one H1 in built output - Surfer Fleet verified unpublished: draft preserved, redirect to /projects/ intact, absent from sitemap Co-Authored-By: Claude Fable 5 <[email protected]>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Docusaurus site to properly render Mermaid diagrams (fixing a previously-visible raw diagram source) and corrects the heading hierarchy on the /frc/history/ page, with CI/build-time validation to prevent regressions.
Changes:
- Enables Mermaid support via
@docusaurus/theme-mermaidandmarkdown.mermaid: true, and converts the Fusion System Blocks diagram to a fenced Mermaid block. - Fixes
/frc/history/heading structure by demoting a duplicate H1 to H2 and adds a build validator check to enforce a single H1 in built output. - Extends
scripts/validate-build.jswith Mermaid regression guards and a check that the Surfer Fleet draft remains unpublished/preserved.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| STEP_1_MERMAID_HOTFIX_REPORT.md | Adds an incident-style report documenting the Mermaid + heading fixes and validation approach. |
| src/pages/projects/fusion-system-blocks.md | Replaces legacy raw Mermaid <div> markup with a fenced Mermaid block (and updates flow direction). |
| src/pages/frc/history.md | Demotes an extra in-content H1 to H2 to avoid duplicate H1 output. |
| scripts/validate-build.js | Adds source/build checks to catch Mermaid regressions, single-H1 enforcement, and Surfer Fleet draft preservation. |
| package.json | Adds @docusaurus/theme-mermaid dependency. |
| package-lock.json | Locks Mermaid theme and its transitive dependencies. |
| docusaurus.config.js | Enables Mermaid markdown processing and adds the Mermaid theme to the theme list. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
14
to
18
| "@docusaurus/core": "^3.7.0", | ||
| "@docusaurus/plugin-client-redirects": "^3.10.1", | ||
| "@docusaurus/preset-classic": "^3.7.0", | ||
| "@docusaurus/theme-mermaid": "3.10.1", | ||
| "@mdx-js/react": "^3.0.0", |
Comment on lines
+126
to
+131
| const jsDir = path.join(build, 'assets', 'js'); | ||
| const jsFiles = fs.readdirSync(jsDir).filter((f) => f.endsWith('.js')); | ||
| const hasDiagramChunk = jsFiles.some((f) => fs.readFileSync(path.join(jsDir, f), 'utf8').includes('SYS[System Context]')); | ||
| const hasMermaidRuntime = jsFiles.some((f) => fs.readFileSync(path.join(jsDir, f), 'utf8').includes('docusaurus-mermaid-container')); | ||
| check('Fusion diagram definition present in page chunk', hasDiagramChunk); | ||
| check('Mermaid theme runtime present in build', hasMermaidRuntime); |
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.