perf(infra): shorten doc-sync critical path

.agents/notes/implemented/process/2026-07-13-documentation-site-projection.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
-2026-07-13-documentation-site-projection.md: 10b8ac8761ef6cc522e752780324c11dfda23622
-2026-07-13-documentation-site-projection.zh.md: 4a03a47e6293b613822e034c710cba6ed7084008
+2026-07-13-documentation-site-projection.md: e8e3070164d9e90dea6406b545067d5fc221550a
+2026-07-13-documentation-site-projection.zh.md: 50862ad79cf8b1099c6ef940a12d09098baa0524

.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md

@@ -26,6 +26,8 @@ The projector parses Markdown links without reserializing the document. A link t
 
 Mermaid renders the canonical diagrams. The website workspace explicitly declares the five packages that `vitepress-plugin-mermaid` asks Vite to prebundle because pnpm's strict dependency isolation otherwise makes those transitive packages unavailable to the local development server; Knip records this runtime-only use as an intentional dependency exception.
 
+The configured Markdown renderer keeps a build-local cache for non-Mermaid code fences, keyed by the exact content, info string, delimiter, and token attributes. The bilingual projection repeats 886 of its 1,748 code fences, so Shiki renders each distinct representation once. Mermaid fences bypass the cache because the plugin output includes a token-position id. The cache is discarded with the renderer after each build and preserves the emitted fence HTML.
+
 Site publication remains separate from site construction. A dedicated GitHub Actions workflow runs the existing documentation gates, uploads `website/.dist` as a Pages artifact, and deploys only after the build succeeds. `actions/configure-pages` supplies the destination's base path to VitePress at build time, so the private Pages origin, a later public project path, and a custom domain do not require distinct checked-in configurations. Pages visibility remains a repository hosting setting rather than a workflow permission.
 
 ## Alternatives considered

.agents/notes/implemented/process/2026-07-13-documentation-site-projection.zh.md

@@ -26,6 +26,8 @@ Status: implemented
 
 Mermaid 渲染权威图表。网站工作区显式声明 `vitepress-plugin-mermaid` 要求 Vite 预打包的 5 个包，因为 pnpm 的严格依赖隔离会使本地开发服务器无法使用这些传递依赖；Knip 将这种仅运行时使用记录为有意的依赖例外。
 
+配置后的 Markdown 渲染器会在单次构建期间缓存非 Mermaid 代码围栏，缓存键包含确切正文、info string、分隔符和 token 属性。双语投影的 1748 个代码围栏中有 886 个是重复内容，因此 Shiki 只渲染一次每种不同表示。Mermaid 围栏不会进入缓存，因为插件输出包含 token 位置 id。每次构建后，缓存会随渲染器一同丢弃，并且不会改变生成的围栏 HTML。
+
 网站发布与网站构建保持分离。专用 GitHub Actions 工作流运行现有文档门禁，将 `website/.dist` 作为 Pages 产物上传，并只在构建成功后部署。`actions/configure-pages` 在构建时向 VitePress 提供目标位置的 base path，因此私有 Pages 源站、未来的公开项目路径和自定义域名不需要各自的检入配置。Pages 可见性仍是仓库托管设置，而不是工作流权限。
 
 ## 考虑过的替代方案

scripts/run-gates.spec.ts

@@ -83,6 +83,15 @@ describe('gate graph validation', () => {
     expect(ids).toContain('public-repository-links')
   })
 
+  it('schedules the longest documentation leaves before short checks', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids.slice(0, 10)).toEqual([
+      'doc-typecheck', 'docs-site-build', 'doc-graphs', 'markdown-links', 'type-equivalence',
+      'cordis-catalog', 'mermaid', 'scoped-events', 'translation-pairing', 'markdown-wrap',
+    ])
+  })
+
   it.each(['ci-primary', 'ci-static', 'check-all'] as const)(
     'keeps the DSH package license policy in %s',
     (mode) => {

scripts/run-gates.ts

@@ -636,38 +636,38 @@ function docSyncLeafGates(options: {
   if (options.docTypecheckNeeds !== undefined) docTypecheckOptions.needs = options.docTypecheckNeeds
   if (options.docTypecheckEnv !== undefined) docTypecheckOptions.env = options.docTypecheckEnv
   return [
+    // Stable FIFO starts the longest leaves first; only docs-site-build writes website/.generated.
     ...options.includeDocTypecheck === false
       ? []
       : [pnpmScript('doc-typecheck', options.docTypecheckScript ?? 'doc-typecheck', docTypecheckOptions)],
+    pnpmScript('docs-site-build', options.docsBuildScript ?? 'docs:build', { label: 'documentation build' }),
+    pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
+    pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
+    pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence' }),
     pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
+    pnpmScript('mermaid', 'verify-mermaid'),
+    pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
+    pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing' }),
+    pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('client-catalog', 'verify-client-catalog', { label: 'client catalog' }),
     pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
     pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),
     pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
-    pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
-    pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
-    pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
-    pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links' }),
     pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs' }),
     pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }),
     pnpmScript('config-source-ownership', 'verify-config-source-ownership', { label: 'config source ownership' }),
     pnpmScript('package-readme-model-experience', 'verify-package-readme-model-experience', { label: 'package README model experience' }),
-    pnpmScript('mermaid', 'verify-mermaid'),
     pnpmScript('agent-note-classification', 'verify-agent-note-classification', { label: 'agent note classification' }),
     pnpmScript('agent-note-format', 'verify-agent-note-format', { label: 'agent note format' }),
     pnpmScript('archived-agent-notes', 'verify-archived-agent-notes', { label: 'archived agent notes' }),
-    pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence' }),
     pnpmScript('skill-invocation-metadata', 'verify-skill-invocation-metadata', { label: 'skill invocation metadata' }),
     pnpmScript('translation-prompt', 'verify-translation-prompt', { label: 'translation prompt' }),
-    pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing' }),
     pnpmScript('doc-budgets', 'verify-doc-budgets', { label: 'doc budgets' }),
     pnpmExec('docs-site-projection', ['vitest', 'run', 'scripts/project-doc-site.spec.ts', 'scripts/verify-doc-site-fragments.spec.ts'], {
       label: 'documentation site checks',
     }),
-    // Keep the VitePress build itself in one gate because projection rewrites website/.generated.
-    pnpmScript('docs-site-build', options.docsBuildScript ?? 'docs:build', { label: 'documentation build' }),
     pnpmScript('package-readme-limitations', 'verify-package-readme-limitations', { label: 'package README limitations' }),
   ]
 }

website/.vitepress/config.ts

@@ -330,11 +330,26 @@ export default withMermaid({
     config(md) {
       const renderText = md.renderer.rules.text
       const renderCode = md.renderer.rules.code_inline
-      if (renderText === undefined || renderCode === undefined) {
-        throw new Error('VitePress Markdown renderer is missing its text or inline-code rule.')
+      const renderFence = md.renderer.rules.fence
+      if (renderText === undefined || renderCode === undefined || renderFence === undefined) {
+        throw new Error('VitePress Markdown renderer is missing a required rendering rule.')
       }
       md.renderer.rules.text = (...args) => escapeVueInterpolation(renderText(...args))
       md.renderer.rules.code_inline = (...args) => escapeVueInterpolation(renderCode(...args))
+      const renderedFences = new Map<string, string>()
+      md.renderer.rules.fence = (...args) => {
+        const [tokens, index] = args
+        const token = tokens[index]
+        if (token === undefined) throw new Error('VitePress code-fence renderer received no token.')
+        // Mermaid output embeds the token position, so only Shiki fences are reusable.
+        if (['mermaid', 'mmd'].includes(token.info.trim().split(/\s+/, 1)[0] ?? '')) return renderFence(...args)
+        const key = JSON.stringify([token.content, token.info, token.markup, token.attrs])
+        const cached = renderedFences.get(key)
+        if (cached !== undefined) return cached
+        const html = renderFence(...args)
+        renderedFences.set(key, html)
+        return html
+      }
     },
   },
   mermaid: {},