开发工具文档【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址https://gitcode.com/gh_mirrors/md/mdBook点击查看免费下载mdBook 将一本书的全部构建参数集中存放在根目录的book.toml文件中本文以官方文档 General configuration 为骨架结合仓库源码逐项拆解[book]、[rust]、[build]三个核心配置表你会掌握每个键的含义、默认值、生效范围与典型用法并了解这些配置在 mdBook 源码中的实际解析与调用位置从而能够独立完成一本多语言、可定制构建流程的书籍配置。配置文件入口book.toml 从哪来、如何加载mdBook 在运行mdbook build、mdbook serve等命令时会从书籍根目录读取book.toml。配置加载的核心实现在 crates/mdbook-core/src/config.rsConfig::from_str直接调用toml::from_str解析 TOML 内容config.rsConfig::from_disk负责把磁盘上的配置文件读成字符串再交给from_strconfig.rsConfig结构体由book、build、rust、output、preprocessor五个顶层表组成config.rs其中output与preprocessor以松散 TOML 表形式保存分别交给各渲染器与预处理器自行消费。每个配置结构体都标注了#[serde(default, rename_all kebab-case, deny_unknown_fields)]如 config.rs这意味着所有键均采用 kebab-case 命名如build-dir、text-direction未在配置文件中出现的键会自动回落到结构体的Default实现不会报错而未知键则会因deny_unknown_fields直接导致解析失败避免拼写错误被静默吞掉。下面的完整示例覆盖了本文讲解的全部配置节来自文档 general.md[book] title Example book authors [John Doe] description The example book covers examples. [rust] edition 2018 [build] build-dir my-example-book create-missing false [preprocessor.index] [preprocessor.links] [output.html] additional-css [custom.css] [output.html.search] limit-results 15一个必须牢记的全局规则是配置文件中出现的任何相对路径始终以存放book.toml的书籍根目录为基准而不是以当前终端的工作目录为基准文档 general.md 明确强调。这一点对src、build-dir、extra-watch-dirs等路径型键都适用。书籍元信息[book] 配置表[book]表存放书籍的通用元数据对应源码中的 BookConfig 结构体。各键说明如下title书名类型为可选字符串OptionString默认Noneauthors作者列表VecString默认空数组在 HTML 渲染时会被写入meta nameauthor等元信息description书籍描述写入每个页面 HTMLhead中的 meta 信息默认Nonesrc源码目录默认值是src——即书籍根目录下名为src的文件夹config.rs。可通过此键改到任意目录如src my-src表示源码位于root/my-srclanguage书籍主语言默认Some(en)config.rs会用于生成html langen之类的语言属性text-direction文字方向可选值为ltr从左到右与rtl从右到左对应枚举 TextDirection。未指定时由language自动推导。示例配置来自文档 general.md[book] title Example book authors [John Doe, Jane Doe] description The example book covers examples. src my-src # 源码将位于 root/my-src 而不是 root/src language en text-direction ltrlanguage 与 text-direction 的推导规则从源码可以确认两者并非独立生效而是存在优先级关系。BookConfig::realized_text_directionconfig.rs的逻辑是显式设置了text-direction就用它否则调用TextDirection::from_lang_code根据语言代码推导config.rs。推导时内置了一张 RTL 语言清单包含ar/ara、he/heb、fa/per/fas、ur/urd、yi/yid、ku/kur等常见从右到左书写系统的语言代码清单之外的语言一律视为 LTR。仓库中的测试用例也印证了这套规则例如语言设为ar/he时推导结果为RightToLeften/ja为LeftToRight而一旦显式设置text-direction无论语言为何都以显式值为准config.rs 的test_text_direction测试。因此编写阿拉伯语、希伯来语或波斯语书籍时即使不写text-direction只要正确设置languagemdBook 也会自动为页面输出 RTL 方向若个别书籍需要阿拉伯语内容但整体 LTR 排版这类特殊场景则可用text-direction显式覆盖。Rust 语言选项[rust] 配置表[rust]表控制与 Rust 代码块、测试和 playground 相关的行为对应源码中的 RustConfig目前只有一个公开键edition代码块默认使用的 Rust edition可选值为2015、2018、2021、2024对应枚举 RustEdition。默认值是2015RustEdition的Default派生自结构体且文档明确说明默认为 2015。[rust] edition 2015 # 代码块的默认 edition单个代码块可以通过注解覆盖全局默认值例如只让某一块按 2015 版编译文档 general.mdrust,edition2015 // 这段代码仅在 2015 edition 下有效。 let try true; 对应的注解依次是edition2015、edition2018、edition2021、edition2024。仓库配置解析测试也验证了edition键与RustEdition枚举的映射关系edition 2018解析为RustEdition::E20182021对应E2021config.rs。此外rust.edition也可以借助Config::set在运行时动态覆盖测试set(rust.edition, 2024)后解析结果为RustEdition::E2024config.rs。构建选项[build] 配置表[build]表控制书籍的构建流程对应源码中的 BuildConfig共有四个键[build] build-dir book # 输出目录 create-missing true # 是否自动创建缺失页面 use-default-preprocessors true # 是否使用默认预处理器 extra-watch-dirs [] # 额外监听目录触发自动重建build-dir输出目录渲染结果输出到书籍根目录下的book/目录默认值bookconfig.rs。构建生成的index.html路径即为build_dir_for(html)与index.html拼接的结果src/cmd/build.rs。该配置可以被命令行参数--dest-dir短选项-d覆盖。从 command_prelude.rs 可以看到--dest-dir的帮助信息明确说明省略时使用build.build-dir再缺省则回落到./book而set_dest_dir函数command_prelude.rs在提供该参数时会用当前工作目录 参数路径直接覆写book.config.build.build_dir。注意此处的路径基准是当前工作目录与book.toml内相对路径以书籍根目录为基准的规则不同。create-missing缺失章节自动创建SUMMARY.md中列出的 Markdown 文件如果不存在默认true会在构建时自动创建空文件设为false后构建遇到缺失文件会直接报错退出文档 general.md。源码层面该行为发生在书籍加载阶段load_book在解析完SUMMARY.md后检查cfg.create_missing为true时调用create_missing(src_dir, summary)补齐缺失章节crates/mdbook-driver/src/load.rs。仓库测试集里也有对应的集成用例 tests/testsuite/build/create_missing/book.toml 与 tests/testsuite/build.rs验证了该开关的实际行为。use-default-preprocessors默认预处理器开关mdBook 自带links与index两个默认预处理器此键控制它们是否运行默认trueconfig.rs。判定规则在 crates/mdbook-driver/src/mdbook.rs不配置任何预处理器时默认的links与index照常运行use-default-preprocessors false会禁用这两个默认预处理器但只要你显式声明了某个预处理器表例如[preprocessor.links]无论该开关是 true 还是 false这个预处理器都会运行文档 general.md。换言之显式声明具有最高优先级。这意味着你可以在保留默认预处理器的同时追加自定义预处理器也可以关闭默认行为、完全用自己声明的预处理器替代。extra-watch-dirs扩展监听目录一个字符串列表VecPathBuf默认空在mdbook watch与mdbook serve命令下生效这些目录中的文件变化会触发重建。当书籍依赖src目录之外的内容例如外部数据文件、模板、脚本生成的中间产物时非常有用文档 general.md。相关命令的实现位于 src/cmd/watch.rs 与 src/cmd/serve.rs。完整配置实战示例综合以上内容一份面向实际项目的book.toml可以这样组织[book] title My Team Handbook authors [Alice, Bob] description Team internal documentation built with mdBook. language zh-CN # 设置语言属性 langzh-CN [rust] edition 2021 # 全书记代码块默认使用 2021 edition [build] build-dir dist # 自定义输出目录也可用 -d/--dest-dir 覆盖 create-missing true # SUMMARY.md 中缺失的章节自动创建 extra-watch-dirs [data] # data/ 下的改动也会触发 watch/serve 重建 [preprocessor.links] # 显式声明 links 预处理器即使关闭默认也会运行 [output.html] additional-css [custom.css]配置的进一步扩展本文只覆盖了通用配置三表mdBook 的配置体系还包括预处理器配置[preprocessor.xxx]各键的详细说明见 format/configuration/preprocessors.md渲染器配置[output.html]等渲染器专属键见 format/configuration/renderers.md环境变量覆盖所有配置都可以通过MDBOOK_前缀的环境变量覆盖例如MDBOOK_BOOK__TITLE对应book.title底层实现在 config.rs 的update_from_env详细规则见 format/configuration/environment-variables.md。掌握了book.toml的通用配置骨架后再配合预处理器与渲染器配置即可完整定制一本 mdBook 的构建产物。赞分享开发工具文档【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址https://gitcode.com/gh_mirrors/md/mdBook点击查看免费下载相关推荐mdBook 配置完全指南深入解析 book.toml 的 General / Preprocessor / Renderer / 环境变量四大配置体系mdBook 配置完全指南深入解析 book.toml 的 General / Preprocessor / Renderer / 环境变量四大配置体系 本指开发工具文档GetQzonehistory 完整指南批量备份 QQ 空间历史说说GetQzonehistory 完整指南批量备份 QQ 空间历史说说 上个月帮家里老人整理旧手机翻到一个 2011 年的 QQ 空间几条早年的说说已经显示网页爬虫数据分析Jupyter Book 使用与配置指南Jupyter Book 使用与配置指南 项目目录结构及介绍 Jupyter Book 的目录结构如下 . ├── binder │ └── environm上一篇Jan 桌面应用发版前质量清单Release Checklist全解析从迁移数据校验到回归验收的工程实践下一篇终极指南如何用Excalidraw免费虚拟白板快速创建专业图表创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考