尧图网站建设 
开发工具文档【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址https://gitcode.com/gh_mirrors/md/mdBook点击查看免费下载导读本文以 mdBook 用户指南的 Creating a book 一章为主线系统讲解从初始化项目、理解book.toml与SUMMARY.md的目录结构到本地实时预览、最终构建静态站点的完整流程。读完本文你将掌握mdbook init/mdbook serve/mdbook build三个核心命令的用法、参数细节及其底层实现原理能够独立创建并发布一本基于 Markdown 的电子书。前置条件本文所有操作都建立在已安装mdbookCLI 工具的基础之上。安装方式参见用户指南的 Installation 章节。安装完成后在终端执行mdbook --version确认命令可用后即可开始创建书籍。初始化一本书mdbook initmdbook init命令会创建一个包含空书骨架的新目录。直接传入想要创建的目录名mdbook init my-first-book命令执行前会向你提出几个交互式问题例如书籍标题、是否创建.gitignore。回答完毕后切换到新书目录cd my-first-bookinit 生成的目录结构在 init 命令参考 中说明了init首次运行时会生成如下骨架book-test/ ├── book └── src ├── chapter_1.md └── SUMMARY.mdsrc目录书籍的 Markdown 源文件所在位置也是你主要编辑的区域book目录渲染输出目录其中的 HTML 产物可以直接上传到任意静态服务器SUMMARY.md整本书的“骨架”定义了章节列表与层级详见 SUMMARY.md 章节。从源码实现看mdbook init命令在 src/cmd/init.rs 中构造了一个BookBuilder其build()方法见 crates/mdbook-driver/src/init.rs依次完成创建root、src、book目录结构 → 生成SUMMARY.md与chapter_1.md占位文件 → 按需生成.gitignore→ 序列化book.toml→ 重新加载并校验生成的书籍。若SUMMARY.md已存在则不会覆盖而是保留原有结构见 create_stub_files。从已有 SUMMARY.md 生成章节init的一个实用技巧是“先搭骨架再生成文件”当src/SUMMARY.md已经存在时init会先解析它然后根据其中列出的路径自动补全缺失的章节文件。这样你可以先在纸上规划整本书的结构再让 mdBook 一键生成# 先手工写好 src/SUMMARY.md再执行 mdbook init path/to/bookinit 的常用参数init支持以下参数定义见 src/cmd/init.rs参数说明示例[dir]书籍根目录省略时默认为当前目录mdbook init path/to/book--theme将默认主题复制到src下的theme目录便于自定义mdbook init --theme--title title直接指定书名跳过交互式询问mdbook init --titlemy amazing book--ignore ignore生成 VCS 忽略文件取值none或gitmdbook init --ignoregit--force跳过所有确认提示mdbook init --force几个值得注意的细节--theme默认主题会被选择性复制到theme目录——若某文件已存在则不会被覆盖删除对应文件即可回退到默认主题。主题复制由Theme::copy_theme实现见 crates/mdbook-driver/src/init.rs更深入的主题定制参见 Theme 章节。--ignoregit生成的.gitignore内容即构建输出目录名默认book其内容拼接逻辑见 build_gitignore。省略该参数时mdBook 会交互式询问。书名与作者init会尝试通过git config --get user.name读取本地 git 用户名并写入book.toml的authors字段见 src/cmd/init.rs书名则通过交互式输入或--title提供。一本书的解剖三个核心组成部分一本 mdBook 书籍由几个关键文件共同定义其设置与布局。book.toml书籍的配置中心书籍根目录下的book.toml使用 TOML。最简单的book.toml只需要一个[book]表[book] title My First Book在此基础上可以逐步扩展出常用配置完整参数说明见 General configuration[book] title My First Book authors [Jane Doe] description The example book covers examples. language en [build] build-dir book # 输出目录默认 book可用 --dest-dir 覆盖 create-missing true # 是否自动创建 SUMMARY.md 中缺失的章节文件 use-default-preprocessors true # 是否启用默认预处理器links 与 index extra-watch-dirs [] # serve/watch 时额外监听的目录 [output.html] additional-css [custom.css]注意配置中所有相对路径均以book.toml所在的书根目录为基准。SUMMARY.md整本书的目录骨架书籍的第二大核心文件是位于src/SUMMARY.md的章节清单。任何章节在被访问之前都必须先登记到这份清单中。一个基本的示例# Summary [Introduction](https://link.gitcode.com/i/857a9665d4ed1ab968c3643109477b94) - My First Chapter - [Nested example](https://link.gitcode.com/i/857a9665d4ed1ab968c3643109477b94) - [Sub-chapter](https://link.gitcode.com/i/db6aef2ef676b95dfc0aec7ea08e18d5)在编辑器中打开src/SUMMARY.md添加几个章节试试如果其中引用的章节文件尚不存在mdbook会自动帮你创建它们这与create-missing配置相关见 crates/mdbook-driver/src/mdbook.rs 中MDBook::load的加载链路。SUMMARY.md的解析格式相当严格其支持的结构元素包括详见 SUMMARY.md 章节前缀章节Prefix Chapters不编号、置于主体章节之前适合前言、引言但不可嵌套且必须在编号章节之前[A Prefix Chapter](https://link.gitcode.com/i/6d244f913536d34d6825d0a18b672d43) - First ChapterPart Title部分标题一级标题用于将后续编号章节逻辑分组渲染为不可点击的文字# My Part Title - [First Chapter](https://link.gitcode.com/i/6d244f913536d34d6825d0a18b672d43)编号章节Numbered Chapters书籍主体内容支持-或*列表嵌套形成层级两种符号不可混用。后缀章节Suffix Chapters位于编号章节之后、不编号的章节。草稿章节Draft Chapters不填写路径的章节如- [Draft Chapter]()在 HTML 渲染的目录中显示为禁用链接用于标记尚未动笔的章节。分隔符Separators由至少三个连字符组成的---行可在目录中插入分隔线。源文件目录src章节内容书籍正文全部存放于src目录每个章节是一个独立的 Markdown 文件。通常每个章节以一级标题开头# My First Chapter Fill out your content here.文件的具体布局由你自由决定但要注意文件的组织方式会直接映射为生成的 HTML 文件路径因此文件布局就是每个章节的 URL 结构。例如nested/sub-chapter.md会对应输出nested/sub-chapter.html。src目录中的其他非 Markdown 文件图片、字体、静态资源等都会被原样复制到输出中。因此只需把图片等静态文件放进src目录的任意位置即可在书中引用。正文的 Markdown 语法支持详见 Markdown 章节。实时预览mdbook serve渲染书籍的方式有多种最简便的方式之一是serve命令——它会在构建书籍的同时启动一个本地 Web 服务器mdbook serve --open--open或-o选项会自动用默认浏览器打开新书页面。即使你持续编辑书籍内容也可以让服务器保持运行——每次保存文件mdbook都会自动重新构建输出并自动刷新浏览器页面。serve 的底层原理从源码看serve命令src/cmd/serve.rs默认监听localhost:3000支持通过-n/--hostname与-p/--port修改监听地址mdbook serve path/to/book -p 8000 -n 127.0.0.1浏览器自动刷新通过 WebSocket 实现mdBook 在服务中注册了__livereload端点见 LIVE_RELOAD_ENDPOINT当文件监控线程检测到变化时会向广播通道发送 “reload” 消息所有已连接的 WebSocket 客户端随即触发页面刷新见 rebuild_on_change 回调 与 websocket_connection。另外serve会把site-url临时覆盖为/以便本地正确提供 404 页面并在book.toml中写入live-reload-endpoint配置。其他实用选项--dest-dir/-d修改输出目录相对路径以当前目录为基准省略时回退到build.build-dir配置默认./book。.gitignore排除规则serve不会为.gitignore中列出的文件触发自动构建仅使用书根目录下的.gitignore全局与父目录的.gitignore均不生效可用于忽略编辑器产生的临时文件。注意serve命令用于测试书籍的 HTML 输出效果并非面向生产环境的完整 HTTP 服务器。相关命令watch与testmdbook watch仅监控并重建书籍不启动 HTTP 服务器适合配合外部静态服务器使用详见 watch 命令。mdbook test对书中的 Rust 代码块运行rustdoc --test可在 CI 中校验示例代码详见 test 命令。发布一本书mdbook build书写完成后你可能想把书托管到某个地方供他人阅读。第一步是构建书籍输出——在book.toml所在目录执行mdbook build这会生成名为book的目录其中包含书籍的完整 HTML 内容。之后你可以把这个目录放到任意 Web 服务器上进行托管。build 的行为细节build会先解析SUMMARY.md理解书籍结构并抓取对应文件同样地SUMMARY.md中提及但尚不存在的文件也会被自动创建前提是build.create-missing为true默认开启若设为false缺失文件会导致构建报错退出。渲染输出会保持与源文件相同的目录结构方便大型书籍在输出中保持条理见 build 命令参考。源目录中除.md扩展名以外的所有文件都会被复制到输出目录。build同样支持目录参数、--open与--dest-dir选项mdbook build path/to/book mdbook build --open mdbook build -d out构建产物的目录规划从 mdbook.rs 的build_dir_for可以看出输出目录的规划规则当只有一个渲染器默认 HTML 渲染器时产物直接放在build.build-dir即book/下当配置了多个渲染器如额外的mdbook-epub等后端时每个渲染器会在构建目录下拥有自己的子目录如book/epub/、book/html/等。托管与持续集成将book目录部署到静态托管平台如各类静态站点服务即可完成发布。对于自动化发布场景mdBook 官方用户指南提供了完整的 Continuous Integration 章节展示了如何在 CI 流水线中安装 mdBook、执行构建并将产物部署到托管服务适合在 GitHub Actions 等平台实现“提交即发布”。小结至此你已完成从零创建一本书的完整闭环mdbook init my-first-book—— 生成book.toml、src/SUMMARY.md与章节占位文件编辑book.toml与src/SUMMARY.md—— 配置元数据、构建选项规划章节层级支持前缀/编号/后缀章节、Part Title、草稿章节与分隔符在src/下编写 Markdown 章节—— 文件布局即最终 URL 结构静态资源直接放入src即可mdbook serve --open—— 本地实时预览保存即自动重建与刷新mdbook build—— 生成book/静态站点部署到任意 Web 服务器或接入 CI 流水线。需要进一步探索时可继续阅读 CLI 指南 了解watch、test、clean、completions等命令或查阅 Configuration 与 For developers 深入自定义预处理与渲染后端。赞分享开发工具文档【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址https://gitcode.com/gh_mirrors/md/mdBook点击查看免费下载相关推荐Hugo 快速上手指南从零创建、配置并发布你的第一个网站Hugo 快速上手指南从零创建、配置并发布你的第一个网站 导读 本篇技术指南以 Hugo 官方 Quick Start 教程对应仓库文档 docs/cont开发工具前端CLIGatsby 快速上手指南用 npm init gatsby 交互式脚手架创建并运行你的第一个站点Gatsby 快速上手指南用 npm init gatsby 交互式脚手架创建并运行你的第一个站点 本篇技术指南围绕 Gatsby 官方快速入门文档 doc前端静态站点Web框架Ray Serve LLM 快速上手用 OpenAiIngress 部署并查询你的第一个 LLM 服务Ray Serve LLM 快速上手用 OpenAiIngress 部署并查询你的第一个 LLM 服务 Ray Serve LLM 是 Ray 内置的 LLM人工智能分布式训练强化学习任务调度模型推理服务后端上一篇3步搞定表单数据可视化Formily终极报表生成方案下一篇toastr颜色对比度检查确保符合WCAG标准创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 mdBook 快速上手：用 `init`、`serve` 与 `build` 创建并发布你的第一本书
开发工具文档【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址https://gitcode.com/gh_mirrors/md/mdBook点击查看免费下载导读本文以 mdBook 用户指南的 Creating a book 一章为主线系统讲解从初始化项目、理解book.toml与SUMMARY.md的目录结构到本地实时预览、最终构建静态站点的完整流程。读完本文你将掌握mdbook init/mdbook serve/mdbook build三个核心命令的用法、参数细节及其底层实现原理能够独立创建并发布一本基于 Markdown 的电子书。前置条件本文所有操作都建立在已安装mdbookCLI 工具的基础之上。安装方式参见用户指南的 Installation 章节。安装完成后在终端执行mdbook --version确认命令可用后即可开始创建书籍。初始化一本书mdbook initmdbook init命令会创建一个包含空书骨架的新目录。直接传入想要创建的目录名mdbook init my-first-book命令执行前会向你提出几个交互式问题例如书籍标题、是否创建.gitignore。回答完毕后切换到新书目录cd my-first-bookinit 生成的目录结构在 init 命令参考 中说明了init首次运行时会生成如下骨架book-test/ ├── book └── src ├── chapter_1.md └── SUMMARY.mdsrc目录书籍的 Markdown 源文件所在位置也是你主要编辑的区域book目录渲染输出目录其中的 HTML 产物可以直接上传到任意静态服务器SUMMARY.md整本书的“骨架”定义了章节列表与层级详见 SUMMARY.md 章节。从源码实现看mdbook init命令在 src/cmd/init.rs 中构造了一个BookBuilder其build()方法见 crates/mdbook-driver/src/init.rs依次完成创建root、src、book目录结构 → 生成SUMMARY.md与chapter_1.md占位文件 → 按需生成.gitignore→ 序列化book.toml→ 重新加载并校验生成的书籍。若SUMMARY.md已存在则不会覆盖而是保留原有结构见 create_stub_files。从已有 SUMMARY.md 生成章节init的一个实用技巧是“先搭骨架再生成文件”当src/SUMMARY.md已经存在时init会先解析它然后根据其中列出的路径自动补全缺失的章节文件。这样你可以先在纸上规划整本书的结构再让 mdBook 一键生成# 先手工写好 src/SUMMARY.md再执行 mdbook init path/to/bookinit 的常用参数init支持以下参数定义见 src/cmd/init.rs参数说明示例[dir]书籍根目录省略时默认为当前目录mdbook init path/to/book--theme将默认主题复制到src下的theme目录便于自定义mdbook init --theme--title title直接指定书名跳过交互式询问mdbook init --titlemy amazing book--ignore ignore生成 VCS 忽略文件取值none或gitmdbook init --ignoregit--force跳过所有确认提示mdbook init --force几个值得注意的细节--theme默认主题会被选择性复制到theme目录——若某文件已存在则不会被覆盖删除对应文件即可回退到默认主题。主题复制由Theme::copy_theme实现见 crates/mdbook-driver/src/init.rs更深入的主题定制参见 Theme 章节。--ignoregit生成的.gitignore内容即构建输出目录名默认book其内容拼接逻辑见 build_gitignore。省略该参数时mdBook 会交互式询问。书名与作者init会尝试通过git config --get user.name读取本地 git 用户名并写入book.toml的authors字段见 src/cmd/init.rs书名则通过交互式输入或--title提供。一本书的解剖三个核心组成部分一本 mdBook 书籍由几个关键文件共同定义其设置与布局。book.toml书籍的配置中心书籍根目录下的book.toml使用 TOML。最简单的book.toml只需要一个[book]表[book] title My First Book在此基础上可以逐步扩展出常用配置完整参数说明见 General configuration[book] title My First Book authors [Jane Doe] description The example book covers examples. language en [build] build-dir book # 输出目录默认 book可用 --dest-dir 覆盖 create-missing true # 是否自动创建 SUMMARY.md 中缺失的章节文件 use-default-preprocessors true # 是否启用默认预处理器links 与 index extra-watch-dirs [] # serve/watch 时额外监听的目录 [output.html] additional-css [custom.css]注意配置中所有相对路径均以book.toml所在的书根目录为基准。SUMMARY.md整本书的目录骨架书籍的第二大核心文件是位于src/SUMMARY.md的章节清单。任何章节在被访问之前都必须先登记到这份清单中。一个基本的示例# Summary [Introduction](https://link.gitcode.com/i/857a9665d4ed1ab968c3643109477b94) - My First Chapter - [Nested example](https://link.gitcode.com/i/857a9665d4ed1ab968c3643109477b94) - [Sub-chapter](https://link.gitcode.com/i/db6aef2ef676b95dfc0aec7ea08e18d5)在编辑器中打开src/SUMMARY.md添加几个章节试试如果其中引用的章节文件尚不存在mdbook会自动帮你创建它们这与create-missing配置相关见 crates/mdbook-driver/src/mdbook.rs 中MDBook::load的加载链路。SUMMARY.md的解析格式相当严格其支持的结构元素包括详见 SUMMARY.md 章节前缀章节Prefix Chapters不编号、置于主体章节之前适合前言、引言但不可嵌套且必须在编号章节之前[A Prefix Chapter](https://link.gitcode.com/i/6d244f913536d34d6825d0a18b672d43) - First ChapterPart Title部分标题一级标题用于将后续编号章节逻辑分组渲染为不可点击的文字# My Part Title - [First Chapter](https://link.gitcode.com/i/6d244f913536d34d6825d0a18b672d43)编号章节Numbered Chapters书籍主体内容支持-或*列表嵌套形成层级两种符号不可混用。后缀章节Suffix Chapters位于编号章节之后、不编号的章节。草稿章节Draft Chapters不填写路径的章节如- [Draft Chapter]()在 HTML 渲染的目录中显示为禁用链接用于标记尚未动笔的章节。分隔符Separators由至少三个连字符组成的---行可在目录中插入分隔线。源文件目录src章节内容书籍正文全部存放于src目录每个章节是一个独立的 Markdown 文件。通常每个章节以一级标题开头# My First Chapter Fill out your content here.文件的具体布局由你自由决定但要注意文件的组织方式会直接映射为生成的 HTML 文件路径因此文件布局就是每个章节的 URL 结构。例如nested/sub-chapter.md会对应输出nested/sub-chapter.html。src目录中的其他非 Markdown 文件图片、字体、静态资源等都会被原样复制到输出中。因此只需把图片等静态文件放进src目录的任意位置即可在书中引用。正文的 Markdown 语法支持详见 Markdown 章节。实时预览mdbook serve渲染书籍的方式有多种最简便的方式之一是serve命令——它会在构建书籍的同时启动一个本地 Web 服务器mdbook serve --open--open或-o选项会自动用默认浏览器打开新书页面。即使你持续编辑书籍内容也可以让服务器保持运行——每次保存文件mdbook都会自动重新构建输出并自动刷新浏览器页面。serve 的底层原理从源码看serve命令src/cmd/serve.rs默认监听localhost:3000支持通过-n/--hostname与-p/--port修改监听地址mdbook serve path/to/book -p 8000 -n 127.0.0.1浏览器自动刷新通过 WebSocket 实现mdBook 在服务中注册了__livereload端点见 LIVE_RELOAD_ENDPOINT当文件监控线程检测到变化时会向广播通道发送 “reload” 消息所有已连接的 WebSocket 客户端随即触发页面刷新见 rebuild_on_change 回调 与 websocket_connection。另外serve会把site-url临时覆盖为/以便本地正确提供 404 页面并在book.toml中写入live-reload-endpoint配置。其他实用选项--dest-dir/-d修改输出目录相对路径以当前目录为基准省略时回退到build.build-dir配置默认./book。.gitignore排除规则serve不会为.gitignore中列出的文件触发自动构建仅使用书根目录下的.gitignore全局与父目录的.gitignore均不生效可用于忽略编辑器产生的临时文件。注意serve命令用于测试书籍的 HTML 输出效果并非面向生产环境的完整 HTTP 服务器。相关命令watch与testmdbook watch仅监控并重建书籍不启动 HTTP 服务器适合配合外部静态服务器使用详见 watch 命令。mdbook test对书中的 Rust 代码块运行rustdoc --test可在 CI 中校验示例代码详见 test 命令。发布一本书mdbook build书写完成后你可能想把书托管到某个地方供他人阅读。第一步是构建书籍输出——在book.toml所在目录执行mdbook build这会生成名为book的目录其中包含书籍的完整 HTML 内容。之后你可以把这个目录放到任意 Web 服务器上进行托管。build 的行为细节build会先解析SUMMARY.md理解书籍结构并抓取对应文件同样地SUMMARY.md中提及但尚不存在的文件也会被自动创建前提是build.create-missing为true默认开启若设为false缺失文件会导致构建报错退出。渲染输出会保持与源文件相同的目录结构方便大型书籍在输出中保持条理见 build 命令参考。源目录中除.md扩展名以外的所有文件都会被复制到输出目录。build同样支持目录参数、--open与--dest-dir选项mdbook build path/to/book mdbook build --open mdbook build -d out构建产物的目录规划从 mdbook.rs 的build_dir_for可以看出输出目录的规划规则当只有一个渲染器默认 HTML 渲染器时产物直接放在build.build-dir即book/下当配置了多个渲染器如额外的mdbook-epub等后端时每个渲染器会在构建目录下拥有自己的子目录如book/epub/、book/html/等。托管与持续集成将book目录部署到静态托管平台如各类静态站点服务即可完成发布。对于自动化发布场景mdBook 官方用户指南提供了完整的 Continuous Integration 章节展示了如何在 CI 流水线中安装 mdBook、执行构建并将产物部署到托管服务适合在 GitHub Actions 等平台实现“提交即发布”。小结至此你已完成从零创建一本书的完整闭环mdbook init my-first-book—— 生成book.toml、src/SUMMARY.md与章节占位文件编辑book.toml与src/SUMMARY.md—— 配置元数据、构建选项规划章节层级支持前缀/编号/后缀章节、Part Title、草稿章节与分隔符在src/下编写 Markdown 章节—— 文件布局即最终 URL 结构静态资源直接放入src即可mdbook serve --open—— 本地实时预览保存即自动重建与刷新mdbook build—— 生成book/静态站点部署到任意 Web 服务器或接入 CI 流水线。需要进一步探索时可继续阅读 CLI 指南 了解watch、test、clean、completions等命令或查阅 Configuration 与 For developers 深入自定义预处理与渲染后端。赞分享开发工具文档【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址https://gitcode.com/gh_mirrors/md/mdBook点击查看免费下载相关推荐Hugo 快速上手指南从零创建、配置并发布你的第一个网站Hugo 快速上手指南从零创建、配置并发布你的第一个网站 导读 本篇技术指南以 Hugo 官方 Quick Start 教程对应仓库文档 docs/cont开发工具前端CLIGatsby 快速上手指南用 npm init gatsby 交互式脚手架创建并运行你的第一个站点Gatsby 快速上手指南用 npm init gatsby 交互式脚手架创建并运行你的第一个站点 本篇技术指南围绕 Gatsby 官方快速入门文档 doc前端静态站点Web框架Ray Serve LLM 快速上手用 OpenAiIngress 部署并查询你的第一个 LLM 服务Ray Serve LLM 快速上手用 OpenAiIngress 部署并查询你的第一个 LLM 服务 Ray Serve LLM 是 Ray 内置的 LLM人工智能分布式训练强化学习任务调度模型推理服务后端上一篇3步搞定表单数据可视化Formily终极报表生成方案下一篇toastr颜色对比度检查确保符合WCAG标准创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考