Zed 文档构建体系解析mdBook、自定义预处理管线与按键绑定动态模板【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed本文以 Zed 仓库中的文档工程说明docs/README.md为主体系统讲解 Zed 官方文档的本地构建与发布管线如何使用固定版本 mdBook 预览文档、如何通过 docs_preprocessor 这套自定义 mdBook 预处理/后处理程序动态渲染按键绑定{#kb}、动作名{#action}、全量动作表{#ACTIONS_TABLE#}并校验文档中的 JSON 配置片段与页面 front matter。读完本文你可以独立在本地复现 Zed 文档的构建过程并理解其按键绑定永不写死的文档工程设计与实现细节。一、文档管线总览Zed 的文档源码位于 docs/src全部为 Markdown基于 mdBook 构建但并非裸用默认 HTML 渲染器。整体管线由三个环节组成预处理器preprocessor注册为 book.toml 中的[preprocessor.zed-docs-preprocessor]命令是cargo run -p docs_preprocessor --作用于html与zed-html两种渲染器之前负责模板替换与内容校验自定义渲染器zed-htmlmdBook 本身不支持 post-processingZed 用一个名为zed-html的自定义渲染器包装内置 HTML 渲染器命令为cargo run -p docs_preprocessor -- postprocess在渲染完成后修改每个 HTML 文件的head页面标题、meta 描述等客户端插件静态 JS如 docs/theme/plugins.js负责根据读者所在平台展示对应的按键绑定。book.toml 中的关键配置如下[output.zed-html] command cargo run -p docs_preprocessor -- postprocess default-description Learn how to use and customize Zed, the fast, collaborative code editor. ... default-title Zed Code Editor Documentation additional-css [theme/page-toc.css, theme/plugins.css, theme/highlight.css, theme/consent-banner.css] additional-js [redirects/legacy-fragment-redirects.js, theme/page-toc.js, theme/plugins.js, theme/c15t2.0.0-rc.3.js, theme/analytics.js] [preprocessor.zed-docs-preprocessor] command cargo run -p docs_preprocessor -- renderer [html, zed-html][build] extra-watch-dirs [../crates/docs_preprocessor]这一行让mdbook serve在文档或预处理器源码变化时都会触发重新构建便于文档开发者调试。二、本地预览与构建步骤2.1 标准流程手动安装 mdBook按 docs/README.md 的说法本地预览需要script/generate-action-metadata mdbook serve docs第一条命令script/generate-action-metadata实际执行cargo run -p zed -- --dump-all-actions crates/docs_preprocessor/actions.json即运行一次 zed 二进制把所有动作action的元数据导出为清单。没有这个清单预处理器无法校验文档中的按键绑定与动作引用会报错只有当动作发生变化时才需要重新生成。第二条命令启动 mdBook 的 watch 模式边改文档边刷新。版本锁定很重要README 明确要求安装mdbook0.4.40cargo install mdbook0.4.40。文档特别注明截至 2025-04-23使用 0.4.48 会出现未知原因导致的异常 URL 行为并破坏文档因此版本必须钉住。2.2 Nix 流程免编译如果使用 Nix开发 shell 已提供固定版本的mdbook0.4.40和预编译好的文档预处理器可直接构建而无需每次编译预处理器nix develop -c mdbook build docs一个细节当actions.json尚未生成时动作/按键绑定校验会被跳过并只打印警告而不是让构建失败——这一行为在 main.rs 中对应load_all_actions()本地非 CI 环境读不到actions.json时打印 Warning: actions.json not found, action validation will be skipped 并返回空清单而 CI 环境中会直接panic!保证 CI 上校验必定生效。2.3 提交前的 Prettier 格式化文档 Markdown 需要符合 Prettier 的格式规范提交前运行cd docs pnpm dlx prettier3.5.0 . --write cd ..三、预处理器深度解析crates/docs_preprocessor预处理器入口在 crates/docs_preprocessor/src/main.rs。它通过子命令区分三种角色supports renderermdBook 的 preprocessor 协议探测除not-supported外一律返回支持无参数即预处理从 stdin 读取 mdBook 序列化的 Book JSON执行模板替换与校验把结果写回 stdoutpostprocess后处理子命令见第五节。handle_preprocessing()按顺序执行五个步骤任何一步收集到错误PreprocessorError集合都会以红色 ERROR 输出并整体报错退出handle_frontmatter—— 解析并转存 front mattertemplate_big_table_of_actions—— 展开{#ACTIONS_TABLE#}template_and_validate_keybindings—— 处理并校验{#kb ...}template_and_validate_actions—— 处理并校验{#action ...}template_and_validate_json_snippets—— 校验并清理带标签的 JSON 代码块。3.1 按键绑定模板{#kb scope::Action}在文档中写{#kb zed::OpenSettings}预处理器用正则\{#kb(?::(\w))?\s(.*?)\}匹配查出该动作在 macOS 默认键表与 Linux 默认键表中的实际按键输出形如kbd classkeybinding⌘,|Ctrl,/kbdmacOS 与 Linux 的绑定用#124;竖线拼在同一个kbd内随后由客户端插件plugins.js 中的detectOS()根据读者所在操作系统只显示其中一半。这就是文档用动作名引用按键、而非硬编码按键的原因——键表改动后文档自动保持最新。键表解析规则find_binding_in_keymap配套测试见 crates/docs_preprocessor/src/tests.rs从键表文件后往前扫描 section 与绑定后定义的 section 覆盖先定义的精确匹配优先于参数化匹配如果键表里同时有ctrl-tab: agents_sidebar::ToggleThreadSwitcher和ctrl-shift-tab: [agents_sidebar::ToggleThreadSwitcher, {...}]解析结果固定是ctrl-tab无论两者在文件中的顺序如何test_find_binding_prefers_exact_match_regardless_of_order专门验证了这一点若 macOS 与 Linux 都查不到绑定输出divNo default binding/div查不到动作名时若该名字命中某动作的deprecated_aliases会给出 Deprecated action used: X should be Y 的定向报错而不是笼统的 Action not found。3.2 键表覆盖层{#kb:keymap_name scope::Action}带冒号前缀的语法{#kb:jetbrains editor::GoToDefinition}表示优先从指定键表覆盖层解析。当前支持的覆盖层仅jetbrains一个KeymapOverlay::parse它从 assets/keymaps/macos/jetbrains.json 等文件加载 JetBrains 风格键表查不到时回退到默认键表find_binding_with_overlay。这适用于文档中假定读者已配置某基础键表的章节。传入未知覆盖层名会产生UnknownKeymapOverlay错误并提示支持的取值。3.3 动作名模板{#action scope::Action}{#action zed::OpenSettings}被替换为动作清单里的human_name人读版本例如 zed: open settings渲染为code classhljs.../code。动作清单按名字排序后用二分查找find_action_by_name。若清单未生成本地未跑generate-action-metadata动作模板降级为原样输出code{name}/code而不报错——与校验跳过只警告的策略一致。3.4 全量动作表{#ACTIONS_TABLE#}template_big_table_of_actions在文档中查找{#ACTIONS_TABLE#}占位符如 docs/src/all-actions.md 这类页面调用generate_big_table_of_actions()生成一个dl定义列表每个动作一条dthuman_name加一条dd文档说明 Keymap Name 可选的 Deprecated Alias 列表说明文本做 HTML 转义。这样所有动作一览页面无需人工维护动作新增/废弃时重新生成actions.json即可自动同步。3.5 front matter 转存handle_frontmatter用正则(?s)^\s*---(.*?)---捕获文件头部的 front matter逐行按第一个冒号拆成name: value对拆不出就报InvalidFrontmatterLine序列化为 JSON 后替换为注释标记!-- ZED_META {...} --。这个标记会随 Markdown 一路渲染进 HTML留给后处理器消费见第五节。注意它只能出现在文件顶部前面只能有空白值不支持双引号与多行——这是有意为之的简化见 5.3。3.6 JSON 片段校验json [tag]文档中大量使用带标签的 JSON 代码块如json [settings] { theme: One Dark } template_and_validate_json_snippets会扫描每个章节里所有 json [开头的代码块根据标签选择校验器校验通过后**把[tag] 标签从源码中剥掉**避免渲染进页面。支持的标签与校验逻辑标签校验方式settings包上{}后用SettingsStore::json_schema编译的 JSON Schema 逐条校验settingscrate 的 schema 与编辑器设置定义同源保证文档示例与真实设置一致keymap基于动作清单动态生成 keymap JSON Schemakeymap_schema_for_actions含各动作参数 schema、文档与废弃别名校验失败给出文件、行号与片段debug按task::DebugTaskFile反序列化tasks按task::TaskTemplates反序列化icon-theme按theme::IconThemeFamilyContent反序列化semantic_token_rules按settings::SemanticTokenRules反序列化所有标签都容忍文档写作习惯首行//注释行会被剥掉片段不写外层{}/[]时自动补齐。出现未知标签直接报Unexpected JSON code block tag。错误通过PreprocessorError::InvalidSettingsJson携带file:line、片段与原因便于定位到具体文档行。四、客户端插件与目录TOC平台化按键显示{#kb}输出里同时携带 macOS 与 Linux 两种键位docs/theme/plugins.js 运行时检测操作系统只保留对应一半。页面目录theme/page-toc.js与theme/page-toc.css由 additional-css 注入构成页面内 TOC。README 说明这两个文件最初由mdbook-pagetoc生成因为该 preprocessor 只产出静态资源生成后就不再需要依赖它。五、后处理器zed-html与每页 title / description5.1 为什么需要后处理mdBook 不支持 post-processing且整本书只能配置一个全局meta description。Zed 的解法把全局 description 设成一个标记值#description#再用zed-html这个假渲染器包装内置 HTML 渲染器在渲染结束后逐个改写 HTML 文件。5.2 后处理做了什么handle_postprocessing()main.rs的工作流从 mdBook 传入的上下文中取出zed-html配置原样改名为html后调用内置HtmlHandlebars渲染器完成实际渲染遍历产物目录下所有.html文件跳过toc.html用正则提取!-- ZED_META (.*) --标记中的title/description将#description#、#amplitude_key#、#consent_io_instance#、#noindex#等占位符替换为实际值DOCS_CHANNELnightly/preview时会插入noindexmeta防止未发布频道被搜索引擎收录重写文档内部链接rewrite_docs_links按site-url与频道决定/docs/、/docs/nightly/等前缀并添加 Markdown alternate linkLLM/Agent 可抓取.md源把title替换为{页面标题} | {front matter title}的组合例如 docs/src/git.md 的 front mattermd --- title: Some more detailed title for this page description: A page-specific description --- # Editor 最终产出titleEditor | Some more detailed title for this page/title与meta namedescription ...。若某页缺少 front matter或某个键则回退到 book.toml 中的default-titleZed Code Editor Documentation与default-description并打印 warn/debug 日志提示哪一页缺 meta。5.3 已知限制front matter 解析刻意做简单避免引入完整 YAML 解析依赖键值必须同一行、值不加双引号多行值与带引号值都不支持front matter 必须位于文件最顶部前面只能有空白title/description内容不做 HTML 转义应使用纯 ASCII 文本不要包含 Unicode 符号或 emoji。六、重定向Redirectsbook.toml 的[output.zed-html.redirect]维护了一张旧文档 URL 到新 URL 的映射表例如/ai.html /docs/ai/overview.html /assistant/context-servers.html /docs/ai/mcp.html /contribute-to-zed.html /docs/development.html#contributor-links约定源 URL 相对 mdBook 站点不能以/docs开头、必须以.html结尾目标 URL 相对 zed.dev 站点根指向其他文档页要带.html后缀要跳到 Zed 站点非文档页则省略/docs前缀。后处理器在渲染完成后调用write_markdown_redirect_aliases与write_pages_redirects把这张表落成静态站点可识别的跳转文件Cloudflare Pages_redirects风格保证文档改版后旧链接仍然可达。七、静态资源约定图片与视频README 明确要求不要把二进制图片放进 Git 仓库会持续膨胀仓库体积应上传到外部图床如 zed.dev 的资产存储后在文档中外链引用。Consent Banner 的c15t打包文档管线不含 JS bundler因此把c15t预打包成 IIFE bundle 提交进仓库当前为 docs/theme/c15t2.0.0-rc.3.js与 book.toml 中additional-js引用一致。升级步骤是本地npm install c15tversion esbuild写一个只导出getOrCreateConsentRuntime的entry.js用npx esbuild --bundle --formatiife --minify打出 bundle 后拷入docs/theme/并更新book.toml引用。八、发布链路部署备注根据 docs/README.md 的内部备注文档在每次 push 到main后由 CI 工作流.github/workflows/deploy_docs.yml构建并上传到 Cloudflare Pages 的 docs 项目Cloudflare 上有一个名为docs-proxy的路由器拦截zed.dev/docs的访问并转发到该 Pages 项目。九、为文档体系新增能力如何写模板README 给出的扩展路径很明确模板template本质是修改文档页面源码的函数通常是正则匹配替换。要新增类似{#kb}的语法参照 main.rs 中template_and_validate_keybindings/template_and_validate_actions的写法在handle_preprocessing()里挂入自己的步骤并把错误并入PreprocessorError集合即可。相关参考客户端插件入口docs/theme/plugins.js默认键表数据源assets/keymaps/default-macos.json、assets/keymaps/default-linux.json预处理器实现与测试crates/docs_preprocessor/src/main.rs、crates/docs_preprocessor/src/tests.rs需要绕过预处理器排查问题时按 README 的提示注释掉 book.toml 中的[preprocessor.zed-docs-preprocessor]段即可。小结Zed 的文档管线展示了文档即代码的完整工程实践mdBook 负责静态站点骨架docs_preprocessor以 Rust 二进制同时充当 preprocessor模板 校验与 post-processorHTML head 改写配合运行时 JS 实现一份文档、多平台按键。其核心保障来自三点动作/键表数据与 zed 本体同源--dump-all-actions导出 默认键表文件JSON 示例与设置 Schema 同源校验以及 CI 中缺失actions.json即 fail 的严格策略。理解了这套机制后无论是贡献文档、新增文档模板还是排查文档构建报错都能直接定位到 crates/docs_preprocessor 中对应的处理函数。【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Zed 文档构建体系解析：mdBook、自定义预处理管线与按键绑定动态模板
Zed 文档构建体系解析mdBook、自定义预处理管线与按键绑定动态模板【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed本文以 Zed 仓库中的文档工程说明docs/README.md为主体系统讲解 Zed 官方文档的本地构建与发布管线如何使用固定版本 mdBook 预览文档、如何通过 docs_preprocessor 这套自定义 mdBook 预处理/后处理程序动态渲染按键绑定{#kb}、动作名{#action}、全量动作表{#ACTIONS_TABLE#}并校验文档中的 JSON 配置片段与页面 front matter。读完本文你可以独立在本地复现 Zed 文档的构建过程并理解其按键绑定永不写死的文档工程设计与实现细节。一、文档管线总览Zed 的文档源码位于 docs/src全部为 Markdown基于 mdBook 构建但并非裸用默认 HTML 渲染器。整体管线由三个环节组成预处理器preprocessor注册为 book.toml 中的[preprocessor.zed-docs-preprocessor]命令是cargo run -p docs_preprocessor --作用于html与zed-html两种渲染器之前负责模板替换与内容校验自定义渲染器zed-htmlmdBook 本身不支持 post-processingZed 用一个名为zed-html的自定义渲染器包装内置 HTML 渲染器命令为cargo run -p docs_preprocessor -- postprocess在渲染完成后修改每个 HTML 文件的head页面标题、meta 描述等客户端插件静态 JS如 docs/theme/plugins.js负责根据读者所在平台展示对应的按键绑定。book.toml 中的关键配置如下[output.zed-html] command cargo run -p docs_preprocessor -- postprocess default-description Learn how to use and customize Zed, the fast, collaborative code editor. ... default-title Zed Code Editor Documentation additional-css [theme/page-toc.css, theme/plugins.css, theme/highlight.css, theme/consent-banner.css] additional-js [redirects/legacy-fragment-redirects.js, theme/page-toc.js, theme/plugins.js, theme/c15t2.0.0-rc.3.js, theme/analytics.js] [preprocessor.zed-docs-preprocessor] command cargo run -p docs_preprocessor -- renderer [html, zed-html][build] extra-watch-dirs [../crates/docs_preprocessor]这一行让mdbook serve在文档或预处理器源码变化时都会触发重新构建便于文档开发者调试。二、本地预览与构建步骤2.1 标准流程手动安装 mdBook按 docs/README.md 的说法本地预览需要script/generate-action-metadata mdbook serve docs第一条命令script/generate-action-metadata实际执行cargo run -p zed -- --dump-all-actions crates/docs_preprocessor/actions.json即运行一次 zed 二进制把所有动作action的元数据导出为清单。没有这个清单预处理器无法校验文档中的按键绑定与动作引用会报错只有当动作发生变化时才需要重新生成。第二条命令启动 mdBook 的 watch 模式边改文档边刷新。版本锁定很重要README 明确要求安装mdbook0.4.40cargo install mdbook0.4.40。文档特别注明截至 2025-04-23使用 0.4.48 会出现未知原因导致的异常 URL 行为并破坏文档因此版本必须钉住。2.2 Nix 流程免编译如果使用 Nix开发 shell 已提供固定版本的mdbook0.4.40和预编译好的文档预处理器可直接构建而无需每次编译预处理器nix develop -c mdbook build docs一个细节当actions.json尚未生成时动作/按键绑定校验会被跳过并只打印警告而不是让构建失败——这一行为在 main.rs 中对应load_all_actions()本地非 CI 环境读不到actions.json时打印 Warning: actions.json not found, action validation will be skipped 并返回空清单而 CI 环境中会直接panic!保证 CI 上校验必定生效。2.3 提交前的 Prettier 格式化文档 Markdown 需要符合 Prettier 的格式规范提交前运行cd docs pnpm dlx prettier3.5.0 . --write cd ..三、预处理器深度解析crates/docs_preprocessor预处理器入口在 crates/docs_preprocessor/src/main.rs。它通过子命令区分三种角色supports renderermdBook 的 preprocessor 协议探测除not-supported外一律返回支持无参数即预处理从 stdin 读取 mdBook 序列化的 Book JSON执行模板替换与校验把结果写回 stdoutpostprocess后处理子命令见第五节。handle_preprocessing()按顺序执行五个步骤任何一步收集到错误PreprocessorError集合都会以红色 ERROR 输出并整体报错退出handle_frontmatter—— 解析并转存 front mattertemplate_big_table_of_actions—— 展开{#ACTIONS_TABLE#}template_and_validate_keybindings—— 处理并校验{#kb ...}template_and_validate_actions—— 处理并校验{#action ...}template_and_validate_json_snippets—— 校验并清理带标签的 JSON 代码块。3.1 按键绑定模板{#kb scope::Action}在文档中写{#kb zed::OpenSettings}预处理器用正则\{#kb(?::(\w))?\s(.*?)\}匹配查出该动作在 macOS 默认键表与 Linux 默认键表中的实际按键输出形如kbd classkeybinding⌘,|Ctrl,/kbdmacOS 与 Linux 的绑定用#124;竖线拼在同一个kbd内随后由客户端插件plugins.js 中的detectOS()根据读者所在操作系统只显示其中一半。这就是文档用动作名引用按键、而非硬编码按键的原因——键表改动后文档自动保持最新。键表解析规则find_binding_in_keymap配套测试见 crates/docs_preprocessor/src/tests.rs从键表文件后往前扫描 section 与绑定后定义的 section 覆盖先定义的精确匹配优先于参数化匹配如果键表里同时有ctrl-tab: agents_sidebar::ToggleThreadSwitcher和ctrl-shift-tab: [agents_sidebar::ToggleThreadSwitcher, {...}]解析结果固定是ctrl-tab无论两者在文件中的顺序如何test_find_binding_prefers_exact_match_regardless_of_order专门验证了这一点若 macOS 与 Linux 都查不到绑定输出divNo default binding/div查不到动作名时若该名字命中某动作的deprecated_aliases会给出 Deprecated action used: X should be Y 的定向报错而不是笼统的 Action not found。3.2 键表覆盖层{#kb:keymap_name scope::Action}带冒号前缀的语法{#kb:jetbrains editor::GoToDefinition}表示优先从指定键表覆盖层解析。当前支持的覆盖层仅jetbrains一个KeymapOverlay::parse它从 assets/keymaps/macos/jetbrains.json 等文件加载 JetBrains 风格键表查不到时回退到默认键表find_binding_with_overlay。这适用于文档中假定读者已配置某基础键表的章节。传入未知覆盖层名会产生UnknownKeymapOverlay错误并提示支持的取值。3.3 动作名模板{#action scope::Action}{#action zed::OpenSettings}被替换为动作清单里的human_name人读版本例如 zed: open settings渲染为code classhljs.../code。动作清单按名字排序后用二分查找find_action_by_name。若清单未生成本地未跑generate-action-metadata动作模板降级为原样输出code{name}/code而不报错——与校验跳过只警告的策略一致。3.4 全量动作表{#ACTIONS_TABLE#}template_big_table_of_actions在文档中查找{#ACTIONS_TABLE#}占位符如 docs/src/all-actions.md 这类页面调用generate_big_table_of_actions()生成一个dl定义列表每个动作一条dthuman_name加一条dd文档说明 Keymap Name 可选的 Deprecated Alias 列表说明文本做 HTML 转义。这样所有动作一览页面无需人工维护动作新增/废弃时重新生成actions.json即可自动同步。3.5 front matter 转存handle_frontmatter用正则(?s)^\s*---(.*?)---捕获文件头部的 front matter逐行按第一个冒号拆成name: value对拆不出就报InvalidFrontmatterLine序列化为 JSON 后替换为注释标记!-- ZED_META {...} --。这个标记会随 Markdown 一路渲染进 HTML留给后处理器消费见第五节。注意它只能出现在文件顶部前面只能有空白值不支持双引号与多行——这是有意为之的简化见 5.3。3.6 JSON 片段校验json [tag]文档中大量使用带标签的 JSON 代码块如json [settings] { theme: One Dark } template_and_validate_json_snippets会扫描每个章节里所有 json [开头的代码块根据标签选择校验器校验通过后**把[tag] 标签从源码中剥掉**避免渲染进页面。支持的标签与校验逻辑标签校验方式settings包上{}后用SettingsStore::json_schema编译的 JSON Schema 逐条校验settingscrate 的 schema 与编辑器设置定义同源保证文档示例与真实设置一致keymap基于动作清单动态生成 keymap JSON Schemakeymap_schema_for_actions含各动作参数 schema、文档与废弃别名校验失败给出文件、行号与片段debug按task::DebugTaskFile反序列化tasks按task::TaskTemplates反序列化icon-theme按theme::IconThemeFamilyContent反序列化semantic_token_rules按settings::SemanticTokenRules反序列化所有标签都容忍文档写作习惯首行//注释行会被剥掉片段不写外层{}/[]时自动补齐。出现未知标签直接报Unexpected JSON code block tag。错误通过PreprocessorError::InvalidSettingsJson携带file:line、片段与原因便于定位到具体文档行。四、客户端插件与目录TOC平台化按键显示{#kb}输出里同时携带 macOS 与 Linux 两种键位docs/theme/plugins.js 运行时检测操作系统只保留对应一半。页面目录theme/page-toc.js与theme/page-toc.css由 additional-css 注入构成页面内 TOC。README 说明这两个文件最初由mdbook-pagetoc生成因为该 preprocessor 只产出静态资源生成后就不再需要依赖它。五、后处理器zed-html与每页 title / description5.1 为什么需要后处理mdBook 不支持 post-processing且整本书只能配置一个全局meta description。Zed 的解法把全局 description 设成一个标记值#description#再用zed-html这个假渲染器包装内置 HTML 渲染器在渲染结束后逐个改写 HTML 文件。5.2 后处理做了什么handle_postprocessing()main.rs的工作流从 mdBook 传入的上下文中取出zed-html配置原样改名为html后调用内置HtmlHandlebars渲染器完成实际渲染遍历产物目录下所有.html文件跳过toc.html用正则提取!-- ZED_META (.*) --标记中的title/description将#description#、#amplitude_key#、#consent_io_instance#、#noindex#等占位符替换为实际值DOCS_CHANNELnightly/preview时会插入noindexmeta防止未发布频道被搜索引擎收录重写文档内部链接rewrite_docs_links按site-url与频道决定/docs/、/docs/nightly/等前缀并添加 Markdown alternate linkLLM/Agent 可抓取.md源把title替换为{页面标题} | {front matter title}的组合例如 docs/src/git.md 的 front mattermd --- title: Some more detailed title for this page description: A page-specific description --- # Editor 最终产出titleEditor | Some more detailed title for this page/title与meta namedescription ...。若某页缺少 front matter或某个键则回退到 book.toml 中的default-titleZed Code Editor Documentation与default-description并打印 warn/debug 日志提示哪一页缺 meta。5.3 已知限制front matter 解析刻意做简单避免引入完整 YAML 解析依赖键值必须同一行、值不加双引号多行值与带引号值都不支持front matter 必须位于文件最顶部前面只能有空白title/description内容不做 HTML 转义应使用纯 ASCII 文本不要包含 Unicode 符号或 emoji。六、重定向Redirectsbook.toml 的[output.zed-html.redirect]维护了一张旧文档 URL 到新 URL 的映射表例如/ai.html /docs/ai/overview.html /assistant/context-servers.html /docs/ai/mcp.html /contribute-to-zed.html /docs/development.html#contributor-links约定源 URL 相对 mdBook 站点不能以/docs开头、必须以.html结尾目标 URL 相对 zed.dev 站点根指向其他文档页要带.html后缀要跳到 Zed 站点非文档页则省略/docs前缀。后处理器在渲染完成后调用write_markdown_redirect_aliases与write_pages_redirects把这张表落成静态站点可识别的跳转文件Cloudflare Pages_redirects风格保证文档改版后旧链接仍然可达。七、静态资源约定图片与视频README 明确要求不要把二进制图片放进 Git 仓库会持续膨胀仓库体积应上传到外部图床如 zed.dev 的资产存储后在文档中外链引用。Consent Banner 的c15t打包文档管线不含 JS bundler因此把c15t预打包成 IIFE bundle 提交进仓库当前为 docs/theme/c15t2.0.0-rc.3.js与 book.toml 中additional-js引用一致。升级步骤是本地npm install c15tversion esbuild写一个只导出getOrCreateConsentRuntime的entry.js用npx esbuild --bundle --formatiife --minify打出 bundle 后拷入docs/theme/并更新book.toml引用。八、发布链路部署备注根据 docs/README.md 的内部备注文档在每次 push 到main后由 CI 工作流.github/workflows/deploy_docs.yml构建并上传到 Cloudflare Pages 的 docs 项目Cloudflare 上有一个名为docs-proxy的路由器拦截zed.dev/docs的访问并转发到该 Pages 项目。九、为文档体系新增能力如何写模板README 给出的扩展路径很明确模板template本质是修改文档页面源码的函数通常是正则匹配替换。要新增类似{#kb}的语法参照 main.rs 中template_and_validate_keybindings/template_and_validate_actions的写法在handle_preprocessing()里挂入自己的步骤并把错误并入PreprocessorError集合即可。相关参考客户端插件入口docs/theme/plugins.js默认键表数据源assets/keymaps/default-macos.json、assets/keymaps/default-linux.json预处理器实现与测试crates/docs_preprocessor/src/main.rs、crates/docs_preprocessor/src/tests.rs需要绕过预处理器排查问题时按 README 的提示注释掉 book.toml 中的[preprocessor.zed-docs-preprocessor]段即可。小结Zed 的文档管线展示了文档即代码的完整工程实践mdBook 负责静态站点骨架docs_preprocessor以 Rust 二进制同时充当 preprocessor模板 校验与 post-processorHTML head 改写配合运行时 JS 实现一份文档、多平台按键。其核心保障来自三点动作/键表数据与 zed 本体同源--dump-all-actions导出 默认键表文件JSON 示例与设置 Schema 同源校验以及 CI 中缺失actions.json即 fail 的严格策略。理解了这套机制后无论是贡献文档、新增文档模板还是排查文档构建报错都能直接定位到 crates/docs_preprocessor 中对应的处理函数。【免费下载链接】zedCode at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.项目地址: https://gitcode.com/GitHub_Trending/ze/zed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
