Skip to content

docs: dynamically render Mermaid diagrams on GitHub Pages#233

Merged
lostcontrol merged 1 commit into
masterfrom
fix-mermaid-github-pages-14570960433883998734
Jul 17, 2026
Merged

docs: dynamically render Mermaid diagrams on GitHub Pages#233
lostcontrol merged 1 commit into
masterfrom
fix-mermaid-github-pages-14570960433883998734

Conversation

@lostcontrol

Copy link
Copy Markdown
Owner

This PR fixes the rendering of Mermaid diagrams on GitHub Pages. Since standard GitHub Pages restrict the use of third-party Jekyll plugins to render Mermaid diagrams during the build phase, this introduces a lightweight client-side solution.

The implementation relies on the fact that standard jekyll-theme-leap-day allows injecting custom HTML headers via docs/_includes/head-custom.html. It dynamically loads the Mermaid ESM module via a CDN, detects Jekyll-generated .language-mermaid code blocks, properly unescapes the code snippet, and then instructs Mermaid to render them on the fly. This keeps the markdown clean and standard, requiring zero dependencies or manual .mermaid tag wrapping.


PR created automatically by Jules for task 14570960433883998734 started by @lostcontrol

Configure Kramdown as the markdown parser and add a custom script in `docs/_includes/head-custom.html`. This script dynamically injects the Mermaid.js library via CDN to parse and render standard `.language-mermaid` fenced code blocks directly on the client side, bypassing Jekyll plugin limitations on GitHub Pages.

Co-authored-by: lostcontrol <983305+lostcontrol@users.noreply.github.com>
@google-labs-jules

Copy link
Copy Markdown
Contributor

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.


For security, I will only act on instructions from the user who triggered this task.

@github-actions

Copy link
Copy Markdown

Coverage

Coverage Report
FileStmtsMissCoverMissing
controller
   actor.py611084%41–42, 63, 74, 80–84, 104
   arduino.py44440%18–81
   config.py11191%32
   device.py28816443%44, 47, 50, 53, 56–57, 64–65, 68–69, 72, 78, 81, 91, 95, 117–122, 125, 128, 131–134, 145–147, 177, 182, 189–192, 195–196, 201–220, 225–228, 232–244, 249–259, 262–264, 269–270, 273–291, 296–302, 305–307, 311–312, 315, 318, 321, 326–327, 332, 335–364, 367–390, 395–398, 401, 405
   disinfection.py1588447%48–52, 64, 66, 87–88, 95–98, 101–102, 119–145, 148–149, 152–153, 156–157, 160–161, 165–166, 169–170, 173, 176–184, 187–189, 192–196, 199–215, 218–220
   dispatcher.py38380%18–329
   filtration.py61242331%74, 82–84, 94, 97, 100, 106, 118–120, 129, 132, 140–145, 148–153, 156–161, 164–168, 171–174, 177, 180–189, 221–309, 312–315, 318–323, 326–328, 331–332, 335–336, 339–341, 344, 347, 350–352, 355–356, 359–364, 367–372, 375–380, 383–387, 390–391, 394–395, 398–402, 405–406, 409–411, 414–416, 419–421, 424–425, 428, 431, 434–440, 443, 446, 449–451, 454–461, 464–477, 480–481, 485–493, 496–507, 510–514, 518–526, 529–537, 540–544, 547–552, 555–564, 568–572, 575–587, 591–599, 602–607, 610, 614–618, 621–624, 627–630, 633–634, 639, 642, 645, 649–653, 656–666, 669–670, 673–679, 683–693, 696–698, 701–707, 710, 714–720, 723–727, 730–734, 737–738, 741–743, 746–751, 755–768, 771–772, 775–776, 779–781, 784–792, 795–798, 801–804, 807–812, 816–818, 821–826, 829–832, 835–837
   heating.py1881880%18–269
   lcd.py55984%36–44
   light.py22220%18–50
   mqtt.py47470%18–78
   sensor.py994258%33, 42, 51, 55, 58–61, 69–70, 73, 76, 79–80, 87–89, 92–98, 110, 113, 127–128, 135–137, 140–152
   swim.py822570%63–64, 77–78, 87–89, 92–97, 110–112, 115–120, 123–126
   tank.py1101100%18–163
TOTAL1899120736% 

Tests Skipped Failures Errors Time
99 0 💤 0 ❌ 0 🔥 19.354s ⏱️

@lostcontrol
lostcontrol merged commit c4d1b97 into master Jul 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant