Skip to content

feat(site): Astro 5 museum-style frontend replacing MkDocs#10

Merged
PanQiWei merged 5 commits into
PanQiWei:mainfrom
nanxingw:main
Apr 23, 2026
Merged

feat(site): Astro 5 museum-style frontend replacing MkDocs#10
PanQiWei merged 5 commits into
PanQiWei:mainfrom
nanxingw:main

Conversation

@nanxingw
Copy link
Copy Markdown
Contributor

@nanxingw nanxingw commented Apr 23, 2026

一句话

把现有 MkDocs + Material 文档站替换为一套 Astro 5 + React + MDX 实现的博物馆/展陈风格前端，内容源（patterns/、docs/、wikis/）保持不变，通过 build-time sync pipeline 将 MkDocs 特有语法转成 Astro 可渲染形式。

事前与 @PanQiWei 沟通过方向，这里按讨论的结果提上来。

预览

🔗 https://nanxingw.github.io/advanced-agentic-dev-patterns/zh — 已在我 fork 的 GH Pages 跑着，可以点进去对比。

  • /zh 首页 — 七个展厅 mosaic + README 正文
  • /zh/mm/cybernetics — Reader（朱印 + 章序汉字 + 右侧 TOC + mermaid/callout/代码/表格全支持）
  • /zh/wiki — Knowledge Atlas（134 概念 + 47 实体 + 82 源头 + 抽卡）
  • /zh/wiki/concepts/a2a-protocol — 概念详情页

设计哲学

宣纸底 + 墨 + 朱印 + 淡金 + 青瓷。章节 = 展厅。字体：LXGW 文楷 + Cormorant Garamond 斜体 + IBM Plex Mono。

和 Observatory（原 extra.css 的 teal + IBM Plex Sans）是两套完全不同的气质；我认为博物馆式更契合心智模型的慢读氛围，但这是强产品观点，欢迎讨论。

变更面

新增 site/ 目录（~11k 行）

site/
├── astro.config.mjs            # Astro 5, i18n (en/zh), markdown pipeline, pagefind
├── package.json                # Node 20, deps pinned
├── scripts/
│   ├── sync-content.mjs        # MkDocs → Astro 转换 + 资产复制
│   └── tests/                  # 8 个单元测试覆盖 transform 边界
├── src/
│   ├── content.config.ts       # mm + wiki 内容集合
│   ├── layouts/Hall.astro      # 基础布局 + ClientRouter
│   ├── components/             # Topbar / HomeMosaic / HomeStory / WikiAtlas / Glyph / ComingSoon
│   ├── pages/                  # /en /zh /[lang]/mm /[lang]/wiki /[lang]/lab
│   ├── lib/urls.ts             # BASE-aware URL helper
│   ├── scripts/                # theme-toggle / mermaid-loader (client-side islands)
│   └── styles/                 # tokens / home / reader / callouts / global
└── public/favicon.svg

内容 sync pipeline（scripts/sync-content.mjs）

从 docs/{en,zh}/mental-models/ 和 wikis/ 读源文件，转换后写入 site/src/content/：

MkDocs 语法 转换为
!!! tip \"title\" / ???+ type GFM callout > [!TIP] title
=== \"tab title\" ### tab title + 去缩进
<div class=\"mm-article\" data-card=\"X\" markdown> ![alt](/mm/lang/chapter/X)
../ch-NN-slug/index.md /[lang]/mm/slug
../concepts/X.md (wiki) ../concepts/X（相对，locale-agnostic）
assets/X.png /mm/lang/chapter/X.png 或 /wiki/kind/X.png

Codex review 指出的 edge case 都有测试覆盖（围栏内 admonition 不改、嵌套递归、inline code 屏蔽、div 属性顺序无关）。

URL 结构变化

旧（MkDocs） 新（Astro）
/en/mental-models/ch-01-orthogonality/01-the-forces/ /en/mm/orthogonality#s-01-the-forces
/en/mental-models/ch-01-orthogonality/index/ /en/mm/orthogonality
/zh/wiki/concepts/X/ /zh/wiki/concepts/X（结构未变）

Reader 从多层深改为单章单页长滚+右侧 sticky TOC。锚点跳转仍可用。

CI + Deploy

  • ci.yml：追加 site job（Node 20 + npm ci + test:sync + astro build），保留现有 lint/test/docs-build 不动
  • 新 deploy-site.yml：自动在 CI 成功后发布 Astro 站到 GH Pages
  • deploy-docs.yml 重命名为 deploy-docs.yml.disabled —— ⚠️ 这是 merge 后 Pages 会从 MkDocs 切到 Astro 的触发点

如果你想先观察一段时间，可以把我这个 PR 的 rename 改回来，手动跑 Deploy Site (Astro) workflow 做一次对比再决定。

验证

  • ✅ 8/8 sync transform 单元测试通过
  • ✅ 本地 SITE_BASE=/advanced-agentic-dev-patterns npm run build 产出 549 页 + sitemap + Pagefind 中英双语索引
  • ✅ 10/10 章节页 playwright 审计：0 broken image、0 raw admonition、0 broken anchor、0 .md 链接残留
  • ✅ View Transition：切换章节时暗色模式/TOC 状态保持
  • ✅ 响应式：mobile 窄屏 mosaic 线性降级、table 水平滚动
  • ✅ 已部署到我 fork 的 Pages，连续迭代了一周

未做 / 已知限制（Codex review 剩余 backlog）

这些不是 blocker 但值得知道：

  1. Mermaid 走 jsDelivr CDN（src/scripts/mermaid-loader.ts）—— supply-chain + CSP 风险。本地 bundle 或 SSR-rendered 是后续方向。
  2. 字体走 Google Fonts + LXGW jsDelivr CDN（src/styles/global.css）—— 同上。
  3. Mermaid 主题不随暗色模式切换同步（初始化一次，此后不重渲）。
  4. /en/wiki 展示中文内容 —— 和原 README 里 "wiki 只在中文站可用" 的现状一致，但严格意义上 en 路由下仍是中文。
  5. chapters.ts 元数据仍手写（Codex 建议从源文件派生）—— 尚未做架构收敛。
  6. Lab (patterns) 别馆还是 coming-soon —— 这 PR 没碰 patterns/ 的渲染，等心智模型稳定后再做。

建议的 review / merge 策略

这是个大 PR（+11k 行），但内部是自洽的 site/ 子目录 + 两个 workflow 改动，基本不动原仓库的 patterns/ docs/ wikis/ scripts/ mkdocs.*.yml（MkDocs 栈完整保留可随时回滚，只是 deploy workflow 暂时禁用）。

如果你想分小点 review，commit 已经按主题分好：

  1. 74b3e90 — Astro 骨架 + CI
  2. 8546a95 — Home essay + Knowledge Atlas wiki
  3. 5531411 — Deploy flip + reader 加宽 + atlas v2 + home 重排
  4. 73141f8 — 抽卡弹窗
  5. fadf309 — 暗色模式修复 + Codex P1 清理

已知会引起注意的点

  • .github/workflows/deploy-docs.yml → .disabled 重命名
  • 根 / 会 302 到 /en（原来是 meta-refresh）
  • 搜索改为 Pagefind（客户端索引，工作原理与 MkDocs Material 的 lunr.js 相似但不同实现）

有任何想先看 / 先改 / 不想合进来的子模块，随时说。谢谢 🙏

nanxingw and others added 5 commits April 23, 2026 10:34
@nanxingw @claude
feat(site): add Astro 5 frontend with museum design + CI
74b3e90 
New /site/ directory: Astro 5 + React + MDX replacement for the MkDocs
docs site, carrying over the museum/展陈 design language from 心智七篇/
(paper/ink/vermilion seal/gold tokens, LXGW Wenkai + Cormorant Garamond,
seven-rooms mosaic home, chapter reader with sticky TOC).

Implements:
- Bilingual /en /zh routes with view-transition-backed language toggle
- Content pipeline (scripts/sync-content.mjs) that transforms MkDocs
  syntax from docs/{en,zh}/mental-models/ into Astro-compatible markdown
  (admonitions, pymdownx tabs, mm-article cards, cross-chapter links,
  wiki links) and copies assets into public/mm/
- Unit tests (scripts/tests/sync-transforms.test.mjs) covering the four
  syntax edge cases surfaced by code review (fenced-code isolation,
  nested admonitions, inline-code link masking, card attribute order)
- Museum-style reader typography, callouts (rehype-callouts), tables,
  horizontal rules, and client-side Mermaid rendering
- Pagefind search index bundled in the production build
- /lab and /wiki coming-soon placeholders with noindex (ready for
  technical annex + wiki work in follow-up)
- SITE_BASE env support for deployment under a repo subpath

CI (.github/workflows/):
- ci.yml: new `site` job alongside existing MkDocs jobs — runs
  transform unit tests + production build on every PR
- deploy-site.yml: workflow_dispatch-only GitHub Pages deploy, kept
  dormant until the user is ready to retire MkDocs' deploy-docs.yml

MkDocs remains untouched and continues to build/deploy as before.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nanxingw @claude
feat(site): port home essay + Knowledge Atlas wiki
8546a95 
Home page (/en, /zh) now carries the README body as prose above the
seven-rooms mosaic — "For Non-Human Readers", "For Human Readers",
"Before You Read", "What's Inside", and the "seven rooms below" outro.
New HomeStory.astro component branches on locale.

Wiki (/en/wiki, /zh/wiki) becomes the Knowledge Atlas, replacing the
coming-soon placeholder:
- 263 entries (134 concepts + 47 entities + 82 sources) sourced from
  wikis/ via an extended sync-content.mjs pipeline that parses
  wikis/index.md for descriptions, copies infograph PNGs to public/wiki/,
  and rewrites cross-refs to Astro routes.
- Atlas index renders a card grid with filter buttons (all/concepts/
  entities/sources) and a 抽卡 / Draw button for random exploration.
  Cards show an infograph background on hover where one exists.
- Detail pages at /[lang]/wiki/[kind]/[slug] render each entry as a
  reader with back-link, description, card image, and full markdown body.

trailingSlash set to 'ignore' so GitHub Pages' auto-301 to trailing-slash
no longer costs an extra hop on internal navigation.

Generated wiki/* artifacts (src/content/wiki, public/wiki) added to
site/.gitignore — rebuilt by predev/prebuild just like mm/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nanxingw @claude
fix(site): flip deploy, widen reader, redesign atlas, reorder home
5531411 
- Deploy: rename deploy-docs.yml → .disabled and enable deploy-site.yml
  workflow_run on CI. This resolves the MkDocs/Astro deploy conflict
  that reverted the live site back to MkDocs after every push.
- Home (/en, /zh): HomeStory now renders BELOW the seven-rooms mosaic
  so readers meet the gallery first; story is gated by a top rule and
  100px of breathing room to feel like a signed essay.
- Reader: widen .reader__body from 34rem (544px) to 42rem (672px) and
  tighten the TOC column to 220px; shell max dropped to 1180px so the
  two columns hold the centre of the viewport instead of drifting.
- Wiki atlas (v2): rename zh nav label 索引 → Wiki. Completely redesign
  the Knowledge Atlas: concepts + entities get image-forward cards
  (infograph visible by default, title/desc over a scrim, 3 per row);
  sources move into a dense 2-column list section below. Filter bar is
  now a single segmented control with a Draw pill for random picks.
  Section headers carry "01 展陈 / 02 源头" numerals for museum feel.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nanxingw @claude
feat(wiki): restore gacha modal for the Draw button
73141f8 
The Draw (抽卡) button previously just clicked a random card and
navigated away — no animation, no chance to look at what was drawn, no
"draw again". Restore the original Knowledge Atlas gacha experience:

- Clicking Draw opens a modal with a single card that flips in.
- "再抽一张 / Draw again" flips out and flips a new pick in.
- "前往此页 / Open page" follows the drawn card's href.
- ESC, backdrop click, and explicit close dismiss the overlay.
- The draw respects the currently-active filter (All / concepts /
  entities / sources).
- Sources have no infograph; they render with a "源" vermilion seal
  placeholder instead of a blank panel.

Pool is built once at boot from the rendered cards + list rows, so
there's no second fetch of the manifest and no JSON shipped twice.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@nanxingw @claude
fix(site): dark mode, gacha safety, wiki link locale, + codex review P1s
fadf309 
Dark mode:
- theme-toggle.ts re-applies localStorage theme on astro:after-swap.
  ClientRouter swaps <html> attributes on navigation, pulling the
  hardcoded data-theme="light" from the fetched page — which reset any
  user choice. Re-applying before paint fixes the flash-back to light.

Gacha (from codex review P0):
- Escape listener moved to module scope so repeated wireAtlas() calls
  under ClientRouter don't accumulate handlers.
- Scroll-lock released on astro:before-preparation, pagehide, and the
  CTA click, so navigating away via "Open page" doesn't leak body
  overflow:hidden onto the next page.

Wiki content pipeline (codex review P0):
- transformWikiLinks now emits RELATIVE cross-refs (../kind/slug), not
  /zh/wiki/... hardcoded URLs. The browser resolves them against the
  current locale prefix, so /en/wiki/concepts/X and /zh/wiki/concepts/X
  both route cross-references to the matching sibling instead of always
  bouncing to /zh.
- Asset rewrites know their kind now: ![x](assets/foo.png) → /wiki/
  <kind>/foo.png directly, no UNRESOLVED placeholder dance. Files that
  referenced non-card assets previously left broken /wiki/UNRESOLVED/...
  URLs in the output.

Wiki atlas performance (codex review P1):
- .atlas-card__image was a <span> with a CSS background-image — 181
  infographs all loaded eagerly. Switched to <img loading="lazy"
  decoding="async"> with object-fit:cover; the scrim moved from ::after
  on the image to ::after on the card itself.

Reader (codex review P1):
- .reader__body table now display:block + overflow-x:auto, so genuinely
  wide tables scroll inside the column instead of blowing the layout.

Cleanup (codex review P1):
- Removed unused imports in HomeStory and wiki [slug].astro.
- Dropped redundant `&& pagefind --site dist` from build — the
  astro-pagefind integration already runs pagefind as part of
  `astro build`, and running it twice indexed the output once via each
  pipeline.
- sync-transforms.test.mjs: +3 tests covering transformWikiLinks
  relative emission, asset path resolution, and index-file link style.
  8/8 passing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@PanQiWei PanQiWei self-requested a review April 23, 2026 03:57
@PanQiWei
Copy link
Copy Markdown
Owner

PanQiWei commented Apr 23, 2026

LGTM!

@PanQiWei PanQiWei merged commit ccd6fd3 into PanQiWei:main Apr 23, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@PanQiWei PanQiWei Awaiting requested review from PanQiWei

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@nanxingw @PanQiWei