TigerBeetle 文档站生成器源码解析从 Markdown 到 docs.tigerbeetle.com 的 Zig 构建流水线【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle本篇技术指南围绕 TigerBeetle 仓库中的文档网站生成器位于 src/docs_website展开深入讲解它是如何把docs/目录与各语言客户端 README 的 Markdown 文件通过zig build流水线转换为静态 HTML 站点、全站搜索索引与单页版本并在发布时推送到 GitHub Pages 托管的 docs.tigerbeetle.com。读完本文你将掌握该生成器的完整构建链路、目录树解析、链接检查、拼写校验与 CI/发布触发机制并能据此本地构建和调试该文档站。一、项目定位一个用 Zig 实现的静态文档生成器TigerBeetle 的官方文档站 docs.tigerbeetle.com 并不是由现成的 Hugo、Docusaurus 等工具生成而是在仓库内部用 Zig 编写的一整套文档生成流水线。src/docs_website/README.md开宗明义地说明这是一个Documentation generator文档生成器目标输出是 docs.tigerbeetle.com静态网站通过zig build生成渲染结果被推送到独立的 docs 发布仓库再由GitHub Pages托管上线也可以直接从仓库根目录用./zig/zig build docs在本地构建其中./zig/zig是仓库内托管的 Zig 工具链见 zig/download.sh。整个生成器的源码集中在src/docs_website/目录从源码结构看它主要由以下模块协作完成详见 src/docs_website/src模块文件职责docs.zig构建入口遍历文档树、调用 pandoc、生成导航、输出页面content.zig递归解析docs/目录结构与各 README构建目录树ToCpage_writer.zig把每个页面的标题、导航、正文套入page.html模板html.zig极简模板引擎$snake_case变量替换single_page_writer.zig把全部页面合并成一个 single-page 版本并重写锚点链接search_index_writer.zig汇总所有页面 HTML输出search-index.jsonfile_checker.zig后置校验文件大小、类型、尾随换行、链接与锚点有效性redirects.zig生成旧 URL 到新 URL 的 HTML 重定向页website.zig公共配置url_prefix、pandoc 路径、页面写出二、构建入口与整体流程从构建系统的视角看文档站是以嵌套构建的形式接入主build.zig的src/docs_website/目录会被作为独立的构建上下文处理见 build.zig 与 build.zig 中对./src/docs_website/的 cwd 设置。文档站自身在docs.zig的build()函数中组织全部流水线见 src/docs_website/src/docs.zig核心步骤如下解析文档树以docs/为根调用content.load()递归加载所有页面Page并让每个页面持有其子页面逐页转换对每个页面执行 pandoc把 Markdowngfmsmart-tex_math_dollars语法转换为 HTML5同时插入四个 Lua 过滤器生成导航基于目录树渲染左侧导航栏details/summary折叠结构并高亮当前页面组装页面通过page_writer把标题、导航、正文注入page.html模板写出为page_path/index.html构建搜索索引把每个页面的 URL 与 HTML 交给search_index_writer汇总输出search-index.json生成单页版本single_page_writer把所有页面拼接为一页并把各页内链接改写成#slug-锚点形式生成 404 页把html/404.html模板渲染为站点根部的404.html。三、输入内容docs/与各客户端 READMEREADME 明确列出了两类输入docs/目录下的所有 Markdown如 docs/README.md、docs/start.md、docs/coding/README.md 等子目录src/clients/$lang/README.md即各语言客户端的说明文档C、Dotnet、Go、Java、Node、Python、Ruby、Rust见 src/clients。有意思的是客户端文档在最终站点中并不出现在它们源码所在的位置而是被搬移到文档站的一个特定分类下。docs.zig的page_url()中有专门的特判逻辑见 src/docs_website/src/docs.zigconst url cut_suffix(page.path, /README.md) orelse cut_suffix(page.path, .md).?; if (cut_prefix(url, ../src/clients/)) |client| { // Special case: docs for clients are in /src/clients/$lang, not under /docs. return std.mem.concat(arena, u8, .{ coding/clients/, client }) catch panic(OOM); }即src/clients/go/README.md会被映射为站点 URL 前缀coding/clients/go/...与docs/coding/下的开发指南放在同一分类下便于读者在同一导航树内找到语言客户端文档。四、目录树ToC构建content.zigcontent.zig承担了站点骨架的解析工作。它把每个目录的README.md当作该目录的索引页并从其中的列表链接- 标题递归地发现子页面构建出Page树见 src/docs_website/src/content.zig。几个值得注意的解析规则子页面发现只有形如- title且以.md或/结尾的链接才会被识别为 ToC 子项parse_page_child()见 content.zig链接必须以./开头唯一例外是/src/clients/开头的绝对路径孤儿页面检测如果某个目录下存在既不是README.md也没有在任何 ToC 链接中出现的 Markdown 文件构建会以error.OrphanedPage失败并打印orphaned page日志——这保证了站点导航不会遗漏任何页面见 content.zig显式排除internals/、TIGER_STYLE.md、ARCHITECTURE.md等不会被当作导航节点加载标题解析每页的 H1#开头作为页面标题客户端 README 开头的自动生成注释!--会被跳过见 content.zig。五、Markdown → HTML 转换pandoc 与 Lua 过滤器每个页面的内容转换由run_pandoc()完成见 src/docs_website/src/docs.zig。实际执行的命令等价于pandoc --from gfmsmart-tex_math_dollars --to html5 \ --lua-filterpandoc/markdown-links.lua \ --lua-filterpandoc/anchor-links.lua \ --lua-filterpandoc/table-wrapper.lua \ --lua-filterpandoc/code-block-buttons.lua \ --reference-locationsection四个 Lua 过滤器分别位于 src/docs_website/pandoc作用如下过滤器职责markdown-links.lua处理 Markdown 内链在 HTML 中的语义anchor-links.lua为标题生成可跳转的锚点链接table-wrapper.lua把表格包进可横向滚动的容器适配移动端code-block-buttons.lua为代码块添加复制按钮转换结果通过--outputpandoc-out.html以构建产物形式传入后续步骤确保整个流水线都受 Zig 构建系统缓存管理。六、页面模板引擎html.zig 与 page_writer.zig页面组装基于两件事一个自研的微型模板引擎和一个页面生成器可执行文件。6.1$dollar_name模板引擎html.zig实现的Html.write()用$snake_case变量替换代替常见的{curly_braces}语法——代码注释解释了原因避免与模板内 JavaScript 函数语法产生歧义见 src/docs_website/src/html.zig。替换逻辑是编译期的如果模板中引用了替换结构体中不存在的标识符或替换结构体中存在模板未使用的字段都会以编译错误失败error.IdentifierNotFound/error.UnusedIdentifiers从源头杜绝拼写错误。6.2 page_writer注入模板并计算脚本哈希page_writer.zig是一个独立编译、以命令行参数驱动的可执行文件见 src/docs_website/src/page_writer.zig它接收标题、作者、url_prefix、页面路径、是否包含搜索框、导航 HTML 等 9 个参数把内容注入 src/docs_website/src/html/page.html 模板。其中有一个值得注意的安全细节page.html中写入了Content-Security-Policyscript-src self plausible.io sha256-$page_script_hash而页面脚本哈希是page_writer对实际注入的内联脚本做SHA-256 摘要并 Base64 编码后动态计算的见 page_writer.zig。这意味着内联脚本内容一旦变化CSP 哈希自动同步更新避免策略与脚本失配。page.html模板本身见 src/docs_website/src/html/page.html还包含了完整的 SEO 与分享元信息description、twitter:card、og:title、og:image、canonical链接、favicon 等并在底部内联page-script.js与搜索脚本$search_script。七、左侧导航栏的生成逻辑导航由nav_fill()递归生成见 src/docs_website/src/docs.zig有子节点的目录渲染为details/summary折叠项子项递归填充若当前目标页位于该节点之下details会自动加上open属性展开叶子页面渲染为普通li classitem链接若正是当前页追加classtarget高亮URL 生成统一走page_url()普通页面直接使用目录路径加尾斜杠并拼接url_prefix。这套逻辑保证了无论从站点哪个页面进入导航树都能定位并展开到当前页所在的层级。八、搜索索引search-index.json搜索能力由search_index_writer提供。docs.zig在遍历页面时把每个页面的站点路径与 pandoc 输出的 HTML 路径收集起来search_index随后以命令行成对参数喂给search_index_writer见 src/docs_website/src/docs.zig。该程序把所有(path, html)条目序列化为 JSON 数组并输出到标准输出最终写为站点根部的search-index.json见 src/docs_website/src/search_index_writer.zig。前端侧src/docs_website/assets/js/search.js 负责加载该索引并实现站内搜索 UIpage.html模板中的$search_box与$search_results由 src/docs_website/src/html/search-box.html 与 src/docs_website/src/html/search-results.html 渲染并为 single-page 模式关闭搜索框include_search false。九、单页single-page版本与锚点重写single_page_writer把所有页面的 HTML 按序拼接到一个页面输出single-page/index.html见 src/docs_website/src/docs.zig。拼接时它逐字符扫描 HTML 中的href与id属性AttributeIterator见 src/docs_website/src/single_page_writer.zig并做两件关键转换链接重写把page_path 相对链接解析为绝对 slug形如#coding-debit-credit路径中的/替换为-带片段的目标重写为#slug-fragmentID 重写为每个页面的锚点 ID 加上页面 slug 前缀防止不同页面之间的锚点冲突H1 特殊处理H1 后紧跟的链接会被清空clear_h1_link避免首页链接污染单页导航。同时单页模式的导航不再使用多页 URL而是通过url2slug()变为#coding-debit-credit/形式的页面内锚点见 docs.zig。十、404 页面与 URL 重定向404 页write_404_page()把 src/docs_website/src/html/404.html 模板渲染为站点根部的404.html交给 GitHub Pages 在访问不存在的路径时展示见 docs.zig重定向redirects.zig内置了一张旧 URL → 新 URL 的映射表如quick-start/→start/、about/→concepts/、about/vopr/→concepts/safety/、about/oltp/→concepts/oltp/为每个旧路径生成包含link relcanonical、meta http-equivrefresh与 JSlocation跳转的 HTML 页见 src/docs_website/src/redirects.zig确保文档改版后旧链接依然可用。十一、质量保障file_checker.zig 链接检查器README 特别强调链接由./src/file_checker.zig检查。file_checker.zigsrc/docs_website/src/file_checker.zig是一个独立验证程序对zig-out生成的站点做多维度校验1. 文件分类与大小按扩展名把文件分为 text.css/.html/.js/.json/.svg/.xml、binary.avif/.gif/.jpg/.png/.ttf/.webp/.woff2、exceptionCNAME、.nojekyll三类出现未知扩展名直接报error.UnsupportedFileType普通文件上限 166 KiBsearch-index.json与single-page/index.html上限 2 MiB见 file_checker.zig。2. 文本格式所有文本文件必须以换行符结尾否则报error.MissingNewline见 file_checker.zig。3. 链接检查check_links()逐条扫描 HTML 中的href属性检查协议安全普通http://链接会报error.InsecureLink除非在http_exceptions白名单内mailto:被忽略冗余斜杠含//或/./的链接报error.RedundantSlash目标存在性相对链接以当前文件所在目录解析后必须存在目录目标会自动补index.html否则报error.TargetNotFound锚点存在性带#fragment的链接会在目标 HTML 中查找idfragment找不到报error.AnchorNotFound见 file_checker.zig外部链接默认关闭实网探测check_links_external false但保留了两组针对 TLS 握手问题的https_exceptions白名单如 kernel.dk 的 io_uring 论文等 PDF 链接开启后可对白名单外的外部 URL 发起GET并要求返回 200。这解释了为什么 README 说 CI 触发该流程主要是为了检测坏链接任何文档改版导致的死链或失效锚点都会让构建失败。十二、拼写校验vale 与 accept.txt除了链接检查构建流程还引入vale做拼写与风格检查。仓库内维护了一份接受词表 src/docs_website/styles/config/vocabularies/docs/accept.txt——技术文档中不可避免的专有名词如 Zig、TigerBeetle、UInt128、LSM 等都会登记在这里避免被误报为拼写错误。新增技术词汇时需要同步更新该文件才能通过 vale 校验。十三、CI 与发布触发机制README 最后点明了两条自动化触发路径CIci.zig在合并队列merge queue中运行构建主要目的是检测坏链接——也就是说任何合并进主干的分支都必须能完整构建出文档站并通过链接校验发布release.zig在发版时执行构建并把渲染产物推送到独立的 docs 发布仓库随后由 GitHub Pages 托管上线到 docs.tigerbeetle.com。这与仓库中 src/scripts/ci.zig 与 src/scripts/release.zig 的整体 CI/发布体系保持一致文档站构建作为其中的一个环节被调度。十四、本地构建与调试如果你想在本地构建并检查文档站流程如下仓库为只读状态以下仅涉及本地构建产物# 从仓库根目录构建文档站使用仓库内托管的 Zig 工具链 ./zig/zig build docs构建完成后静态站点产物输出在仓库根目录下的zig-out目录中README 明确写到 Outputs are static HTML files in the./zig-outdirectory。你可以直接用任意静态文件服务器预览python3 -m http.server --directory zig-out 8080若改动文档后构建失败file_checker会给出精确的报错类别TargetNotFound、AnchorNotFound、InsecureLink、OrphanedPage、FileSizeExceeded等及出错文件路径按错误类型修正链接、锚点或文件格式即可。十五、设计要点小结纵观整个生成器可以提炼出几个值得借鉴的设计决策单一来源输入目录树完全由各目录的README.md的链接清单推导配合孤儿页面检测保证站点结构与文档仓库严格一致构建阶段即校验链接检查、锚点检查、文件大小/格式检查全部发生在构建期坏链接在 CI 阶段就被拦截而不是等部署后由用户发现零依赖模板引擎自研$dollar_name替换引擎配合编译期字段校验避免引入重型模板框架的同时保证安全性多形态输出同一份 Markdown 同时产出多页站点、单页版便于离线阅读与全文检索与 JSON 搜索索引三种形态共享同一套 pandoc 转换结果静态化部署产物是纯静态 HTML JSON可无状态地托管在任何静态服务本仓库选用 GitHub Pages并支持 404 页与旧链接重定向。对希望在 TigerBeetle 仓库中贡献文档的开发者而言理解上述流水线意味着新增页面时只要遵循在父级 README 中以- 标题形式登记链接并保证文中链接与锚点真实有效其余导航、搜索索引、单页、校验都会自动完成。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TigerBeetle 文档站生成器源码解析：从 Markdown 到 docs.tigerbeetle.com 的 Zig 构建流水线
TigerBeetle 文档站生成器源码解析从 Markdown 到 docs.tigerbeetle.com 的 Zig 构建流水线【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle本篇技术指南围绕 TigerBeetle 仓库中的文档网站生成器位于 src/docs_website展开深入讲解它是如何把docs/目录与各语言客户端 README 的 Markdown 文件通过zig build流水线转换为静态 HTML 站点、全站搜索索引与单页版本并在发布时推送到 GitHub Pages 托管的 docs.tigerbeetle.com。读完本文你将掌握该生成器的完整构建链路、目录树解析、链接检查、拼写校验与 CI/发布触发机制并能据此本地构建和调试该文档站。一、项目定位一个用 Zig 实现的静态文档生成器TigerBeetle 的官方文档站 docs.tigerbeetle.com 并不是由现成的 Hugo、Docusaurus 等工具生成而是在仓库内部用 Zig 编写的一整套文档生成流水线。src/docs_website/README.md开宗明义地说明这是一个Documentation generator文档生成器目标输出是 docs.tigerbeetle.com静态网站通过zig build生成渲染结果被推送到独立的 docs 发布仓库再由GitHub Pages托管上线也可以直接从仓库根目录用./zig/zig build docs在本地构建其中./zig/zig是仓库内托管的 Zig 工具链见 zig/download.sh。整个生成器的源码集中在src/docs_website/目录从源码结构看它主要由以下模块协作完成详见 src/docs_website/src模块文件职责docs.zig构建入口遍历文档树、调用 pandoc、生成导航、输出页面content.zig递归解析docs/目录结构与各 README构建目录树ToCpage_writer.zig把每个页面的标题、导航、正文套入page.html模板html.zig极简模板引擎$snake_case变量替换single_page_writer.zig把全部页面合并成一个 single-page 版本并重写锚点链接search_index_writer.zig汇总所有页面 HTML输出search-index.jsonfile_checker.zig后置校验文件大小、类型、尾随换行、链接与锚点有效性redirects.zig生成旧 URL 到新 URL 的 HTML 重定向页website.zig公共配置url_prefix、pandoc 路径、页面写出二、构建入口与整体流程从构建系统的视角看文档站是以嵌套构建的形式接入主build.zig的src/docs_website/目录会被作为独立的构建上下文处理见 build.zig 与 build.zig 中对./src/docs_website/的 cwd 设置。文档站自身在docs.zig的build()函数中组织全部流水线见 src/docs_website/src/docs.zig核心步骤如下解析文档树以docs/为根调用content.load()递归加载所有页面Page并让每个页面持有其子页面逐页转换对每个页面执行 pandoc把 Markdowngfmsmart-tex_math_dollars语法转换为 HTML5同时插入四个 Lua 过滤器生成导航基于目录树渲染左侧导航栏details/summary折叠结构并高亮当前页面组装页面通过page_writer把标题、导航、正文注入page.html模板写出为page_path/index.html构建搜索索引把每个页面的 URL 与 HTML 交给search_index_writer汇总输出search-index.json生成单页版本single_page_writer把所有页面拼接为一页并把各页内链接改写成#slug-锚点形式生成 404 页把html/404.html模板渲染为站点根部的404.html。三、输入内容docs/与各客户端 READMEREADME 明确列出了两类输入docs/目录下的所有 Markdown如 docs/README.md、docs/start.md、docs/coding/README.md 等子目录src/clients/$lang/README.md即各语言客户端的说明文档C、Dotnet、Go、Java、Node、Python、Ruby、Rust见 src/clients。有意思的是客户端文档在最终站点中并不出现在它们源码所在的位置而是被搬移到文档站的一个特定分类下。docs.zig的page_url()中有专门的特判逻辑见 src/docs_website/src/docs.zigconst url cut_suffix(page.path, /README.md) orelse cut_suffix(page.path, .md).?; if (cut_prefix(url, ../src/clients/)) |client| { // Special case: docs for clients are in /src/clients/$lang, not under /docs. return std.mem.concat(arena, u8, .{ coding/clients/, client }) catch panic(OOM); }即src/clients/go/README.md会被映射为站点 URL 前缀coding/clients/go/...与docs/coding/下的开发指南放在同一分类下便于读者在同一导航树内找到语言客户端文档。四、目录树ToC构建content.zigcontent.zig承担了站点骨架的解析工作。它把每个目录的README.md当作该目录的索引页并从其中的列表链接- 标题递归地发现子页面构建出Page树见 src/docs_website/src/content.zig。几个值得注意的解析规则子页面发现只有形如- title且以.md或/结尾的链接才会被识别为 ToC 子项parse_page_child()见 content.zig链接必须以./开头唯一例外是/src/clients/开头的绝对路径孤儿页面检测如果某个目录下存在既不是README.md也没有在任何 ToC 链接中出现的 Markdown 文件构建会以error.OrphanedPage失败并打印orphaned page日志——这保证了站点导航不会遗漏任何页面见 content.zig显式排除internals/、TIGER_STYLE.md、ARCHITECTURE.md等不会被当作导航节点加载标题解析每页的 H1#开头作为页面标题客户端 README 开头的自动生成注释!--会被跳过见 content.zig。五、Markdown → HTML 转换pandoc 与 Lua 过滤器每个页面的内容转换由run_pandoc()完成见 src/docs_website/src/docs.zig。实际执行的命令等价于pandoc --from gfmsmart-tex_math_dollars --to html5 \ --lua-filterpandoc/markdown-links.lua \ --lua-filterpandoc/anchor-links.lua \ --lua-filterpandoc/table-wrapper.lua \ --lua-filterpandoc/code-block-buttons.lua \ --reference-locationsection四个 Lua 过滤器分别位于 src/docs_website/pandoc作用如下过滤器职责markdown-links.lua处理 Markdown 内链在 HTML 中的语义anchor-links.lua为标题生成可跳转的锚点链接table-wrapper.lua把表格包进可横向滚动的容器适配移动端code-block-buttons.lua为代码块添加复制按钮转换结果通过--outputpandoc-out.html以构建产物形式传入后续步骤确保整个流水线都受 Zig 构建系统缓存管理。六、页面模板引擎html.zig 与 page_writer.zig页面组装基于两件事一个自研的微型模板引擎和一个页面生成器可执行文件。6.1$dollar_name模板引擎html.zig实现的Html.write()用$snake_case变量替换代替常见的{curly_braces}语法——代码注释解释了原因避免与模板内 JavaScript 函数语法产生歧义见 src/docs_website/src/html.zig。替换逻辑是编译期的如果模板中引用了替换结构体中不存在的标识符或替换结构体中存在模板未使用的字段都会以编译错误失败error.IdentifierNotFound/error.UnusedIdentifiers从源头杜绝拼写错误。6.2 page_writer注入模板并计算脚本哈希page_writer.zig是一个独立编译、以命令行参数驱动的可执行文件见 src/docs_website/src/page_writer.zig它接收标题、作者、url_prefix、页面路径、是否包含搜索框、导航 HTML 等 9 个参数把内容注入 src/docs_website/src/html/page.html 模板。其中有一个值得注意的安全细节page.html中写入了Content-Security-Policyscript-src self plausible.io sha256-$page_script_hash而页面脚本哈希是page_writer对实际注入的内联脚本做SHA-256 摘要并 Base64 编码后动态计算的见 page_writer.zig。这意味着内联脚本内容一旦变化CSP 哈希自动同步更新避免策略与脚本失配。page.html模板本身见 src/docs_website/src/html/page.html还包含了完整的 SEO 与分享元信息description、twitter:card、og:title、og:image、canonical链接、favicon 等并在底部内联page-script.js与搜索脚本$search_script。七、左侧导航栏的生成逻辑导航由nav_fill()递归生成见 src/docs_website/src/docs.zig有子节点的目录渲染为details/summary折叠项子项递归填充若当前目标页位于该节点之下details会自动加上open属性展开叶子页面渲染为普通li classitem链接若正是当前页追加classtarget高亮URL 生成统一走page_url()普通页面直接使用目录路径加尾斜杠并拼接url_prefix。这套逻辑保证了无论从站点哪个页面进入导航树都能定位并展开到当前页所在的层级。八、搜索索引search-index.json搜索能力由search_index_writer提供。docs.zig在遍历页面时把每个页面的站点路径与 pandoc 输出的 HTML 路径收集起来search_index随后以命令行成对参数喂给search_index_writer见 src/docs_website/src/docs.zig。该程序把所有(path, html)条目序列化为 JSON 数组并输出到标准输出最终写为站点根部的search-index.json见 src/docs_website/src/search_index_writer.zig。前端侧src/docs_website/assets/js/search.js 负责加载该索引并实现站内搜索 UIpage.html模板中的$search_box与$search_results由 src/docs_website/src/html/search-box.html 与 src/docs_website/src/html/search-results.html 渲染并为 single-page 模式关闭搜索框include_search false。九、单页single-page版本与锚点重写single_page_writer把所有页面的 HTML 按序拼接到一个页面输出single-page/index.html见 src/docs_website/src/docs.zig。拼接时它逐字符扫描 HTML 中的href与id属性AttributeIterator见 src/docs_website/src/single_page_writer.zig并做两件关键转换链接重写把page_path 相对链接解析为绝对 slug形如#coding-debit-credit路径中的/替换为-带片段的目标重写为#slug-fragmentID 重写为每个页面的锚点 ID 加上页面 slug 前缀防止不同页面之间的锚点冲突H1 特殊处理H1 后紧跟的链接会被清空clear_h1_link避免首页链接污染单页导航。同时单页模式的导航不再使用多页 URL而是通过url2slug()变为#coding-debit-credit/形式的页面内锚点见 docs.zig。十、404 页面与 URL 重定向404 页write_404_page()把 src/docs_website/src/html/404.html 模板渲染为站点根部的404.html交给 GitHub Pages 在访问不存在的路径时展示见 docs.zig重定向redirects.zig内置了一张旧 URL → 新 URL 的映射表如quick-start/→start/、about/→concepts/、about/vopr/→concepts/safety/、about/oltp/→concepts/oltp/为每个旧路径生成包含link relcanonical、meta http-equivrefresh与 JSlocation跳转的 HTML 页见 src/docs_website/src/redirects.zig确保文档改版后旧链接依然可用。十一、质量保障file_checker.zig 链接检查器README 特别强调链接由./src/file_checker.zig检查。file_checker.zigsrc/docs_website/src/file_checker.zig是一个独立验证程序对zig-out生成的站点做多维度校验1. 文件分类与大小按扩展名把文件分为 text.css/.html/.js/.json/.svg/.xml、binary.avif/.gif/.jpg/.png/.ttf/.webp/.woff2、exceptionCNAME、.nojekyll三类出现未知扩展名直接报error.UnsupportedFileType普通文件上限 166 KiBsearch-index.json与single-page/index.html上限 2 MiB见 file_checker.zig。2. 文本格式所有文本文件必须以换行符结尾否则报error.MissingNewline见 file_checker.zig。3. 链接检查check_links()逐条扫描 HTML 中的href属性检查协议安全普通http://链接会报error.InsecureLink除非在http_exceptions白名单内mailto:被忽略冗余斜杠含//或/./的链接报error.RedundantSlash目标存在性相对链接以当前文件所在目录解析后必须存在目录目标会自动补index.html否则报error.TargetNotFound锚点存在性带#fragment的链接会在目标 HTML 中查找idfragment找不到报error.AnchorNotFound见 file_checker.zig外部链接默认关闭实网探测check_links_external false但保留了两组针对 TLS 握手问题的https_exceptions白名单如 kernel.dk 的 io_uring 论文等 PDF 链接开启后可对白名单外的外部 URL 发起GET并要求返回 200。这解释了为什么 README 说 CI 触发该流程主要是为了检测坏链接任何文档改版导致的死链或失效锚点都会让构建失败。十二、拼写校验vale 与 accept.txt除了链接检查构建流程还引入vale做拼写与风格检查。仓库内维护了一份接受词表 src/docs_website/styles/config/vocabularies/docs/accept.txt——技术文档中不可避免的专有名词如 Zig、TigerBeetle、UInt128、LSM 等都会登记在这里避免被误报为拼写错误。新增技术词汇时需要同步更新该文件才能通过 vale 校验。十三、CI 与发布触发机制README 最后点明了两条自动化触发路径CIci.zig在合并队列merge queue中运行构建主要目的是检测坏链接——也就是说任何合并进主干的分支都必须能完整构建出文档站并通过链接校验发布release.zig在发版时执行构建并把渲染产物推送到独立的 docs 发布仓库随后由 GitHub Pages 托管上线到 docs.tigerbeetle.com。这与仓库中 src/scripts/ci.zig 与 src/scripts/release.zig 的整体 CI/发布体系保持一致文档站构建作为其中的一个环节被调度。十四、本地构建与调试如果你想在本地构建并检查文档站流程如下仓库为只读状态以下仅涉及本地构建产物# 从仓库根目录构建文档站使用仓库内托管的 Zig 工具链 ./zig/zig build docs构建完成后静态站点产物输出在仓库根目录下的zig-out目录中README 明确写到 Outputs are static HTML files in the./zig-outdirectory。你可以直接用任意静态文件服务器预览python3 -m http.server --directory zig-out 8080若改动文档后构建失败file_checker会给出精确的报错类别TargetNotFound、AnchorNotFound、InsecureLink、OrphanedPage、FileSizeExceeded等及出错文件路径按错误类型修正链接、锚点或文件格式即可。十五、设计要点小结纵观整个生成器可以提炼出几个值得借鉴的设计决策单一来源输入目录树完全由各目录的README.md的链接清单推导配合孤儿页面检测保证站点结构与文档仓库严格一致构建阶段即校验链接检查、锚点检查、文件大小/格式检查全部发生在构建期坏链接在 CI 阶段就被拦截而不是等部署后由用户发现零依赖模板引擎自研$dollar_name替换引擎配合编译期字段校验避免引入重型模板框架的同时保证安全性多形态输出同一份 Markdown 同时产出多页站点、单页版便于离线阅读与全文检索与 JSON 搜索索引三种形态共享同一套 pandoc 转换结果静态化部署产物是纯静态 HTML JSON可无状态地托管在任何静态服务本仓库选用 GitHub Pages并支持 404 页与旧链接重定向。对希望在 TigerBeetle 仓库中贡献文档的开发者而言理解上述流水线意味着新增页面时只要遵循在父级 README 中以- 标题形式登记链接并保证文中链接与锚点真实有效其余导航、搜索索引、单页、校验都会自动完成。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考