mdbook写作和发布流程

本文旨在为技术作者，特别是物理引擎、图形学、科学计算等领域的开发者，提供一套完整、高效且自动化的技术文档解决方案。之前，我尝试过多种方法，都会出现各种各样问题，耗费大量时间解决工具格式兼容问题。最后，我总结这套整合 mdBook、KaTeX 插件和 GitHub Pages，构建一个从内容撰写到网站部署的无缝工作流。

工作流程简述

使用Mdbook创建电子书项目，然后通过markdown的格式进行内存创作，本地编译电子书进行预览和修改。这里，使用两个Github仓库A和B，A负责存电子书项目代码，B负责发布。最后同步仓库A，然后通过仓库B的Github Page进行发布。

使用软件包

• visual studio code：markdown的书写工具。
• rust安装包：因为mdbook基于rust开发，提供运行环境。
• mdbook安装包：通过mdbook，编译markdown文件变成html。
• mdbook-KaTeX插件：用于书写latex格式的公式。

操作实践

配置mdbook环境

1. 安装rustup包。可以从这里 下载。安装成功后，可以运行cargo命令。

2. 通过Rust包管理器cargo安装mdbook包。

cargo install mdbook

3. 创建mdbook项目。

mdbook init my-physics-book

4. 配置book.toml文件和SUMMARY.md目录文件。添加需要的markdown文件。关于配置的细节见后面章节。

5. 使用命令在本地预览电子书。

mdbook serve --open

配置Github项目

1. 注册Github账号。
2. 创建两个仓库，A为private,保存书的源代码。B为Public,负责发布。
3. 将本地电子书项目同步到仓库A上。配置.gitignore文件。

# 在.gitignore中，忽略mdbook build output
/book/

发布电子书

1. 安装ghp-import工具。

python -m pip install ghp-import

2. 修改Github仓库B的Settings/Pages/Build and deplayment选项，记得将Branch下面改为gh-pages/root。

3. 本地编译电子书,编译后电子书，会在/book下面。

mdbook build

4. 把本地的/book内容强制提交到当前仓库B的 gh-pages 分支，并立即推送到远端，同时禁用 Jekyll 处理。”

ghp-import book -r git@github.com:账号/B.git -b gh-pages -p

最后，记得同步仓库A，做好备份。

mdbook配置

• book.toml配置 在book.toml中，添加下面内容，开启katex配置，这样才能用$$ $$(Latex格式)写公式。

[preprocessor.katex]
after = ["links"]
renderers = ["html"]

关于Visual Studio Code配置

推荐安装下面插件：

• Markdown all in One
• Markdown preview enhanced

在编辑的.md文件上，使用ctrl+shift+V打开预览，进行所见即所得的编写。

mdbook对Markdown扩展

这里我罗列一些常用的扩展。

划线

An example of ~~strikethrough text~~.

An example of strikethrough text.

注释

脚注会在正文中生成一个小的编号链接，点击后 引导读者进入条目底部的脚注文本。这里写两个注释。

这是一个注释的例子[^note1]。

[^note1]: 这里是脚注的内容。在文章底部。

This is an example of a footnote[^note2].

[^note2]: This text is the contents of the footnote, which will be rendered
    towards the bottom.

注释的渲染结果如下：

这是一个注释的例子¹。

This is an example of a footnote².

任务列表

任务清单可以作为已完成项目的清单。 示例：

- [x] Complete task
- [ ] Incomplete task

渲染结果为：

• Complete task
• Incomplete task

定义列表

这个功能可以用来制作专业术表。

 2D引擎
  ：Box2D

常见物理引擎
  : Bullet3
  : 2D的Box2D
  ：PhysX

渲染结果如下：

2D引擎 ：Box2D

常见物理引擎

Bullet3

2D的Box2D ：PhysX

重要信息提示

可以通过下面格式生成不同类型的提示信息。

> [!NOTE]
> 一般信息

> [!TIP]
> 一个有用的建议或最佳实践。

> [!IMPORTANT]
> 一个有用的建议或最佳实践。

> [!WARNING]
> 关键信息突出潜在风险。

> [!CAUTION]
> 关于需要谨慎的潜在问题的信息。

渲染后的结果如下：

Note

一般信息

Tip

一个有用的建议或最佳实践。

Important

一个有用的建议或最佳实践。

Warning

关键信息突出潜在风险。

Caution

关于需要谨慎的潜在问题的信息。

参考文献

[1] https://rust-lang.github.io/mdBook/index.html

1. 这里是脚注的内容。在文章底部。 ↩

2. This text is the contents of the footnote, which will be rendered towards the bottom. ↩