fix(site): 图渲染修复 + Claude 主题 + 暗色切换 + 高亮兜底#2
Merged
Conversation
…me + dark mode
Two real bugs found by user review on the deployed page:
1) PlantUML diagrams + source were both invisible on the live site.
Root cause: plantuml.js wrote content into the inner <pre.plantuml>
(CSS display:none) instead of the outer <figure>. So both the success
SVG and the offline source listing were hidden.
Fix:
- Move data-source onto <figure>; keep <pre class="plantuml"> as a
hidden source container only.
- host = figure.figure-wrap; success writes <svg> + caption into it
and toggles .figure-ready; failure writes a visible <details> with
the raw .puml source + an error hint inline, toggles .figure-error.
- bindZoom listens on the figure but ignores clicks inside the
offline <details> block so the fallback source stays clickable.
2) Code blocks were not syntax-highlighted on deploy.
Fix:
- hljs CDN github-dark theme as base; style.css re-declares token
colors per light/dark mode so the look stays consistent.
- jsdelivr first, jsdelivr-fail -> unpkg fallback (auto loads after 4s).
- boot script polls up to 8s for window.hljs before highlighting, so
the page is still readable even if all CDNs are blocked.
Plus a full visual rework to clone the Claude.ai feel:
- Warm beige background + Claude coral/terracotta accent + serif body
font + monospace code; light + dark via <html data-theme>.
- Theme toggle button in sidebar persists to localStorage and follows
prefers-color-scheme on first visit; inline pre-paint bootstrap avoids FOUC.
- Tightened typography, hero, callouts, tables, and the zoom overlay
for both themes.
Verified locally: http.server all assets 200; dom-smoke.cjs confirms
both success (5/5 figure-ready) and offline (5/5 figure-error) paths.
…fline paths tests/dom-smoke.cjs builds a tiny DOM mock + Node zlib-backed CompressionStream/Response shims and exercises McpSite.renderPlantUml() twice (network on -> 5/5 figure-ready; network off -> 5/5 figure-error). Catches regression of the host-target bug fixed in the previous commit.
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
1 participant
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.
问题（你线上看到的）
打开 https://albert-pzy.github.io/mcp-tutorial/ 后：
根因
1) PlantUML 整体被隐藏
plantuml.js把渲染结果写进了内层<pre class="plantuml">，而 CSS 里这个<pre>是display:none（让它只作隐藏的源码容器）。所以无论成功还是失败，图和源码都被一同藏起来了。日志（CI 里跑过一轮）其实提示“没有 SVG”，但人眼只在浏览器里看到一片空，就是这个原因。
2) 代码高亮在不同环境不稳定
jsdelivr CDN 在某些网络下不可达；而我的启动脚本在
DOMContentLoaded直接if(window.hljs)判断，CDN 还没加载完就跳过了高亮，导致代码块裸露。
修复
PlantUML
data-source从内层<pre>移到外层<figure class="figure-wrap">；<pre class="plantuml">退回为隐藏的源码占位容器（CSS 仍
display:none）。plantuml.js干脆把渲染结果写进 外层<figure>：<svg>+figcaption，加figure-ready，整张图可见可点。<figure>内放一个展开式<details>显示原始 PlantUML 源码 +
.figure-error-hint；图区域不再空白。<figure>上，但忽略<details>/<pre>/<code>内的点击，避免误触。代码高亮
style.css又在浅 / 暗两种主题下各自重写 token 颜色，保证视觉一致。
window.hljs就自动加载 unpkg 兜底。hljs就位后再highlightElement；都失败时代码块以纯文本裸露，仍可阅读，不会破坏页面。
Claude 主题 + 暗亮色切换
紧凑侧边导航 + hero + 内容区。
<html data-theme="light|dark">；侧边栏底部「🌗 主题」按钮切换；偏好写入localStorage["mcp-theme"]；首次访问跟随prefers-color-scheme。data-theme，避免刷新闪屏（FOUC）。验证
python -m http.server，全部资源 200；新 HTML 标记数符合预期（5 figure、5 pre.plantuml、theme-toggle、unpkg fallback、github-dark css 都在）。
tests/dom-smoke.cjs（零依赖 node 脚本 + 最小 DOM mock + Node zlib 兜 CompressionStream）：tests/playwright/page.spec.ts继续过测试；现在因为修了真 bug，离线回退用例也会真正断言
<svg>或.figure-error-hint至少有一个（之前因为它被隐藏在display:none的 pre里，该断言其实总是 0）。
合并后
合到 master 即触发
deploy-pages.yml自动重发布到https://albert-pzy.github.io/mcp-tutorial/ —— 线上就会直接看到修复后的效果。