mdBook

mdBook 是一个从 Markdown 文件创建现代在线书籍的工具。

它看起来像什么？

mdBook 的 用户指南 使用 Markdown 编写，并使用 mdBook 生成您可以阅读的类似在线书籍的网站。该文档使用 GitHub 上的最新版本，并展示了可用的功能。

安装

安装 mdBook 有多种方法。

1. 二进制文件

   二进制文件可供下载 此处。请确保将二进制文件的路径添加到您的 PATH。

2. 从 Crates.io

   这需要至少 Rust 1.39 和 Cargo。一旦安装了 Rust，请在终端中输入以下内容

   cargo install mdbook
   

   这将为您下载和编译 mdBook，剩下的只是将 Cargo 的二进制目录添加到您的 PATH。

   自动部署的说明

   如果您使用脚本通过 Travis 或其他 CI 服务器进行自动部署，我们建议您在通过脚本安装时指定 mdBook 的 semver 版本范围！

   这将限制服务器安装最新的非中断版本mdBook，并防止您的书籍因为发布新版本而无法构建。

   您还可以禁用默认功能以加快编译时间。

   示例

   cargo install mdbook --no-default-features --features output --vers "^0.1.0"
   

3. 从Git

   发布到crates.io的版本将略低于GitHub上托管的版本。如果您需要最新版本，可以自己构建mdBook的git版本。Cargo使这变得非常简单！

   cargo install --git https://github.com/rust-lang/mdBook.git mdbook
   

   再次提醒，请确保将Cargo bin目录添加到您的PATH中。

4. 对于贡献

   如果您想为mdBook做贡献，您必须在您的本地机器上克隆仓库

   git clone https://github.com/rust-lang/mdBook.git
   

   cd到mdBook/并运行

   cargo build
   

   生成的二进制文件可以在mdBook/target/debug/目录下找到，名称为mdBook或mdBook.exe。

用法

mdBook主要用作命令行工具，尽管它将所有功能都作为Rust crate暴露出来，以便集成到其他项目中。

以下是一些您可能会运行的命令。有关更详细的说明，请参阅用户指南。

• mdbook init<目录>

  init命令将创建一个目录，其中包含启动所需的最小模板。如果省略<directory>参数，则使用当前目录。

  book-test/
  ├── book
  └── src
      ├── chapter_1.md
      └── SUMMARY.md
  

  book和src都是目录。 src包含用于将输出渲染到book目录的Markdown文件。

  有关更多信息和一些技巧，请参阅CLI文档。

• mdbook build

  您将运行此命令来渲染书籍，它读取SUMMARY.md文件以了解书籍的结构，以源目录中的Markdown文件作为输入，并输出您可以上传到服务器的静态HTML页面。

• mdbook watch

  当您运行此命令时，mdbook将监视您的Markdown文件，并在每次更改时重新构建书籍。这样可以避免每次都需要返回终端并多次输入mdbook build。

• mdbook serve

  与mdbook watch做同样的事情，但还将在https://127.0.0.1:3000（端口号可更改）上提供服务，并在发生更改时重新加载浏览器。

• mdbook clean

  删除包含生成的书籍的目录。

第三方插件

用户可以通过第三方插件配置书籍的加载和渲染方式。这些插件是在构建过程中调用的程序，大致分为两类，预处理器和渲染器。

预处理器用于在将书籍发送到渲染器之前对其进行转换。一个示例是将所有{{#include some_file.ext}}的出现替换为该文件的正文。一些现有的预处理器包括

• index - 默认启用的内置预处理器，它将所有 README.md 章节转换为 index.md，以便在发布到浏览器时，可以通过 URL foo/ 访问 foo/README.md
• links - 默认启用的内置预处理器，用于扩展章节中的 {{# playground}} 和 {{# include}} 辅助函数。
• katex - 将 LaTex 方程式渲染为 HTML 的预处理器。

渲染器被赋予最终的书籍，以便它们可以对它进行一些操作。这通常用于，正如其名所示，以特定格式渲染文档，然而并没有阻止渲染器对书籍进行静态分析以验证链接或运行测试。一些现有的渲染器包括：

• html - 内置的渲染器，将生成书籍的 HTML 版本
• markdown - 默认禁用的内置渲染器，在运行预处理器后输出结果 Markdown。对于调试预处理器非常有用。
• linkcheck - 后端将检查所有链接是否有效
• epub - 一个实验性的 EPUB 生成器

开发者注意：如果您开发了您自己的插件并希望在此处提及它，请随时发送 PR。

通过安装适当的程序并在书籍的 book.toml 文件中提及它，可以启用预处理器或渲染器。

$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]

[output.html]

[output.linkcheck]  # enable the "mdbook-linkcheck" renderer

$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend

有关插件系统的更多信息，请参阅 用户指南。

作为一个库

除了命令行界面之外，这个crate也可以作为一个库使用。这意味着您可以将它集成到现有的项目中，例如一个Web应用。由于命令行界面只是库功能的包装，因此当您将此crate作为库使用时，您可以完全访问命令行界面的所有功能，以及一个易于使用的API等等！

有关更多信息，请参阅 用户指南 和 API 文档。

贡献

非常欢迎和鼓励贡献！请不要犹豫参与问题讨论，提出新功能并寻求帮助。

如果您刚开始使用 Rust，有一些问题被标记为 E-Easy，我们将很高兴地指导您，以便您能够成功通过修复错误或添加新功能的过程！让我们知道您是否需要任何帮助。

有关贡献的更多信息，请查看我们的 贡献指南，它可以帮助您完成构建和贡献过程！

还有最新的API文档的 渲染版本 可用，供在 master 上进行黑客攻击的人使用。

许可

本仓库中所有代码均采用 Mozilla公共许可证v2.0 发布，更多信息请查看 LICENSE 文件。