100ms 以内的导航 : docmd docs

指南
性能
100 毫秒以内的导航

问题

传统的多页导航会在每次点击时触发完整的浏览器刷新。这会产生令人出戏的"白屏闪烁"，打断阅读节奏。浏览器会丢弃当前状态、请求新 HTML、重新解析 CSS 与 JavaScript —— 即使只更新中间的内容区。

为什么重要

用户经常在教程、API 参考与概念指南之间来回跳转。如果切换需要数秒，认知摩擦会阻碍探索。即时导航让文档像原生应用一样，从而显著提升用户满意度与参与度。

方法

docmd 使用一套高性能的 单页应用 (SPA) 路由，构建于预先生成的静态文件之上。浏览器会拦截链接点击、在后台仅取回必要的内容，并动态更新页面，无需完整刷新。这能保留侧边栏、目录与主题设置的状态，从而带来近乎瞬时的切换。

实现

docmd 的 SPA 路由采用多种进阶技术，以达到 100ms 以内的导航速度：

1. 基于意图的预取

当用户悬停在某个导航链接上时，docmd 会识别这一意图，并开始后台获取目标页面。用户真正点击时，数据常常已经位于浏览器缓存中，切换因此显得瞬时。

2. 局部 DOM 更新

docmd 并非整页重渲染，而是智能地只更新必要的功能区域：

主体内容：主要的 Markdown 渲染正文。
目录：与新标题同步刷新。
导航状态：更新侧边栏的激活与展开状态。

3. 用于自定义逻辑的生命周期事件

由于浏览器避免了完整刷新，DOMContentLoaded 这类标准事件只会触发一次。若要在每次导航后执行自定义 JavaScript，请监听 docmd:page-mounted 事件。

document.addEventListener("docmd:page-mounted", (event) => {
  const currentPath = event.detail.path;
  console.log(`已成功导航至：${currentPath}`);
  
  if (currentPath.includes("/api/")) {
    initApiConsole();
  }
});

更多细节请参阅客户端事件文档。

取舍

脚本执行

SPA 路由会自动重新执行新页面 Markdown 正文里的 <script> 标签。但定义在主题中的全局脚本只会在初次加载时运行一次。对于必须在每一页执行的逻辑，请使用 docmd:page-mounted 事件。

SEO 与无障碍

尽管具备 SPA 般的体验，docmd 仍会为每个页面生成一份完整的 .html 文件。这确保搜索引擎爬虫能看到完整内容，也确保禁用 JavaScript 的用户依然可以使用站点。这同时保障了出色的 SEO 与无障碍标准。

问题