JSON for Modern C 离线 Docset为 Dash、Velocity 与 Zeal 构建文档索引的完整流程【免费下载链接】jsonJSON for Modern C项目地址: https://gitcode.com/GitHub_Trending/js/jsondocs/docset 目录是 JSON for Modern Cnlohmann/json官方文档的离线化方案它把完整的 mkdocs 文档站点打包成 Kapeli docset 格式供 Dash、Velocity、Zeal 这类本地文档浏览器离线检索使用。本文基于该目录下的 README、Makefile、docSet.sql 与 Info.plist 逐文件拆解 docset 的组成结构、构建管线与索引设计帮助你从零构建一个可在本地快速跳转、搜索的 JSON for Modern C API 文档库。1. docset 是什么离线文档浏览器的标准容器docset 是 Dash 生态定义的一种文档包格式本质上是一个带固定目录约定的文件夹.docset浏览器打开后即可全文索引并按符号类、函数、宏、指南页跳转。JSON for Modern C 仓库将构建该文档包所需的全部素材集中在docs/docset/下按 README 说明生成命令为make nlohmann_json.docset生成后的nlohmann_json.docset文件夹可直接被文档浏览器打开较新版本同时收录在 Dash 用户贡献Dash-User-Contributions中供直接在线下载。需要说明一个仓库内的细节差异README 中给出的目标名是nlohmann_json.docset而从 Makefile 的当前源码结构看实际定义的主目标是JSON_for_Modern_C.docset其默认目标all进一步产出可分发的压缩包JSON_for_Modern_C.tgz见 Makefile。实际执行时以 Makefile 中的目标名为准即可。2. docs/docset 目录文件布局构建一个 docset 涉及四类角色文件docs/docset/目录正好一一对应文件作用Makefile构建管线生成索引、打包 docset、安装到 Zeal、一致性检查docSet.sql以 SQL 脚本形式声明的全文搜索索引约 240 条符号条目Info.plistdocset 元数据标识符、名称、平台族、JS 开关等docset.jsonDash 用户贡献仓库使用的包元数据名称、版本、别名、作者icon.png/icon2x.png16×16 与 32×32 的文档图标复制到 docset 根目录2.1 Info.plistdocset 的身份声明Info.plist 是一个标准 Apple Property List各键的作用为keyCFBundleIdentifier/key stringnlohmann_json/string keyCFBundleName/key stringJSON for Modern C/string keyDocSetPlatformFamily/key stringjson/string keyisDashDocset/key true/ keydashIndexFilePath/key stringindex.html/string keyDashDocSetFallbackURL/key stringhttps://nlohmann.github.io/json//string keyisJavaScriptEnabled/key true/CFBundleIdentifier与CFBundleName决定浏览器中显示的名称与唯一标识isDashDocset为true标识这是 Dash 兼容文档包dashIndexFilePath指向构建产物的站点首页即 mkdocs 生成的index.htmlDashDocSetFallbackURL是在线回退地址本地缺失页面时可跳转至官网文档isJavaScriptEnabled为true这是 mkdocs-material 主题依赖 JS 做导航与搜索能正常渲染的前提。2.2 docSet.sql用 SQL 声明搜索索引docset 的核心是 SQLite 索引。Makefile 中第一步就是sqlite3 docSet.dsidx docSet.sqldocSet.sql 头部先定义表结构DROP TABLE IF EXISTS searchIndex; CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT); CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);searchIndex表只有四列符号名name、符号类型type、页面路径path并对(name, type, path)建立唯一索引保证条目不重复。全文件共 244 行可分三层阅读API 层第 5 行至 165 行覆盖basic_json的全部公开成员parse、dump、at、flatten、各is_*查询、二进制格式转换to_cbor/from_msgpack等、json_pointer、json_sax、ordered_json、ordered_map、byte_container_with_subtype、adl_serializer以及operator、operator_json等自由函数与字面量操作符Features 指南层第 167 行至 202 行把功能文档页注册为Guide类型例如Binary Formats: CBOR、JSON Pointer、Element Access: Checked access: at、Integration: CMake等让搜索 JSON Pointer 能直接命中对应指南页宏层第 204 行至 244 行覆盖JSON_ASSERT、JSON_DIAGNOSTICS、JSON_NO_IO、NLOHMANN_DEFINE_TYPE_INTRUSIVE、NLOHMANN_JSON_NAMESPACE_BEGIN、版本宏NLOHMANN_JSON_VERSION_MAJOR等编译期配置宏。每条path都指向 mkdocs 构建后的具体页面例如INSERT INTO searchIndex(name, type, path) VALUES (basic_json::parse, Function, api/basic_json/parse/index.html);这与 docs/mkdocs/docs/api/basic_json/ 下的 Markdown 源文件一一对应——索引里的页面路径就是文档站点的 URL 路径这是后面构建脚本能精确改写页面标题的基础。type字段取值遵循 Dash 的符号类型约定Class、Function、Method、Constructor、Type、Operator、Enum、Literal、Macro、Guide浏览器据此在结果中分类显示。2.3 docset.json用户贡献包的元数据docset.json 面向 Dash 用户贡献仓库的自动构建{ name: JSON for Modern C, version: 3.12.0, archive: JSON_for_Modern_C.tgz, author: { name: Niels Lohmann, link: https://nlohmann.me }, aliases: [nlohmann/json] }其中archive字段正好对应 Makefile 的打包目标产出的JSON_for_Modern_C.tgzaliases让用户搜索 nlohmann/json 时也能命中该 docset。3. 构建管线Makefile 的完整流程docs/docset/Makefile 定义了从生成索引 → 组装 docset → 压缩打包 → 安装到 Zeal → 一致性检查 → 清理的完整链路。前置条件bash、make、sqlite3命令行工具、可用的sedMakefile 第 2 行优先探测 GNU 的gsed否则退回系统sed以兼容 GNU/BSD 行为差异以及能运行 Python 虚拟环境的机器用于构建 mkdocs 站点。3.1 主目标组装 JSON_for_Modern_C.docset第 13 至 42 行 的主目标按顺序执行以下步骤生成索引sqlite3 docSet.dsidx docSet.sql得到 SQLite 索引文件搭目录骨架创建JSON_for_Modern_C.docset/Contents/Resources/Documents/复制两个icon*.png与Info.plist构建文档站点这是最耗时的两步直接复用文档站自身的构建入口make install_venv -C ../mkdocs # python3 -mvenv venv pip install -r requirements.txt make build -C ../mkdocs # venv/bin/mkdocs build先跑 check_structure.py 结构检查依赖版本在 docs/mkdocs/requirements.txt 中锁定mkdocs1.6.1、mkdocs-material9.7.7、mkdocs-minify-plugin0.8.0等拷贝产物把../mkdocs/site/*整体复制进Contents/Resources/DocumentsCSS 补丁离线可读性关键向 mkdocs-minify 压缩后的主样式表追加两条规则header, footer, nav.md-tabs, nav.md-tabs--active, div.md-sidebar--primary, a.md-content__button { display: none; } div.md-sidebar div.md-sidebar--secondary, div.md-main__inner { top: 0; margin-top: 0 }从源码注释看目的是隐藏浏览器环境里无用的顶部导航、页脚与一级侧边栏并把主内容区上移消除留白——因为文档浏览器会接管窗口框架与搜索入口站点自身的导航反而是视觉噪音标题改写两级策略先用sed全局删除页面标题后缀- JSON for Modern C作为兜底然后遍历 docs/mkdocs/docs/ 下所有*.md页面对每页查询 SQLite 中path$$path/index.html对应的name若存在就用索引里的规范名替换 HTMLtitle。这样 Dash 里显示的页面标题就是 docSet.sql 中精心编写的符号名如 Element Access: Checked access: at而非 Markdown 文件默认标题收尾删除sitemap.*把docSet.dsidx复制到Contents/Resources/完成 docset 约定布局。3.2 打包目标JSON_for_Modern_C.tgz第 44 至 45 行 将 docset 目录压缩分发并显式排除 macOS 的.DS_Storetar --exclude.DS_Store -cvzf JSON_for_Modern_C.tgz JSON_for_Modern_C.docset这个 tgz 就是docset.json中archive字段引用的分发物。3.3 辅助目标Zeal 安装与索引一致性检查install_docset_zeal第 48 至 53 行把生成的 docset 安装到 Zeal 的本地数据目录路径遵循 XDG 约定docset_root${XDG_DATA_HOME:-$HOME/.local/share}/Zeal/Zeal/docsets rm -rf $$docset_root/JSON_for_Modern_C.docset mkdir -p $$docset_root cp -r JSON_for_Modern_C.docset $$docset_root/list_missing_pages / list_removed_paths第 55 至 83 行一对双向一致性检查非常体现维护思路。前者遍历 mkdocs 的.md页面列表报告文档页存在但 docSet.sql 索引里没有的遗漏后者遍历searchIndex表中的所有 path报告索引里存在但没有对应 Markdown 源页的失效条目。文档站页面频繁增删时这两个目标能防止搜索索引与实际站点脱节clean第 85 至 88 行删除docSet.dsidx与已生成的 docset、tgz 产物。4. 与文档站构建的衔接关系docset 不是独立内容源它是 docs/mkdocs/ 文档站构建产物的二次加工。衔接点在 docs/mkdocs/Makefile 中有明确注释build与install_venv两个目标注明 This target is used by the docset Makefile。也就是说站点结构由 docs/mkdocs/mkdocs.yml 决定mkdocs-material 主题、use_directory_urls风格目录、nav 中 Home / Features / API 的层级站点导航中的每一个页面目录都成为 docSet.sql 中path的来源构建前先执行check_structure.py结构校验再mkdocs build输出到site/版本信息上docset.json声明的version: 3.12.0与站点构建时注入的版本宏NLOHMANN_JSON_VERSION_*共同标识这一份离线文档对应的库版本。理解这条链路的实际意义是docset 的新鲜度完全跟随文档站——任何 API 页面变动重新执行一次 docset 构建即同步无需单独维护离线内容副本。5. 许可说明按 README 的 Licenses 一节docset 中使用的 JSON logoicon 素材的来源为公有领域public domain资源docset 包内其余文档内容则跟随 JSON for Modern C 项目本身的 MIT 许可见 LICENSE.MIT构建与分发时保持这一归属即可。6. 小结从源码到离线文档库的操作路径在docs/docset/下执行make默认目标all或直接执行make JSON_for_Modern_C.docset得到 docset 目录与 tgz 包在 Dash / Velocity / Zeal 中打开JSON_for_Modern_C.docsetZeal 用户可直接make install_docset_zeal文档站页面变更后用make list_missing_pages与make list_removed_paths核对 docSet.sql 索引与 mkdocs 页面的双向一致性分发物以JSON_for_Modern_C.tgz为准元数据见 docset.json。整套方案的可复制之处在于用一份 SQL 文件声明搜索索引、用一个 Info.plist 声明包身份、用 Makefile 把文档站构建产物 CSS 补丁 标题改写固化为可重复执行的管线——这套模式可以原样移植到任何基于 mkdocs 的 C 项目文档上。【免费下载链接】jsonJSON for Modern C项目地址: https://gitcode.com/GitHub_Trending/js/json创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考