gitbook

cargo install gitbook

lib.rs:

mdBook

mdBook 是一个将Markdown文档集合渲染为更适用于最终用户的格式（如HTML或EPUB）的工具。它提供了一个命令行界面，但如果需要更多控制，也可以使用这个crate。

这是API文档，如果您想了解关于命令行工具、格式、结构等信息，还可以查看用户指南。它也是使用mdBook渲染的，以展示其功能和默认主题。

使用crate（而不是CLI）的一些原因：

• 将mdBook集成到现有项目中
• 扩展mdBook的功能
• 在构建书籍之前进行一些处理或测试
• 通过公共API访问以帮助创建新的渲染器
• ...

注意：虽然我们努力确保mdbook的命令行界面和行为向后兼容，但该工具的内部实现仍在发展和迭代。如果您希望防止意外的破坏，建议将基于mdbook crate构建的工具锁定到特定版本。

示例

如果从头开始创建新书籍，您可以通过MDBook::init()方法获取BookBuilder。

use mdbook::MDBook;
use mdbook::config::Config;

let root_dir = "/path/to/book/root";

// create a default config and change a couple things
let mut cfg = Config::default();
cfg.book.title = Some("My Book".to_string());
cfg.book.authors.push("Michael-F-Bryan".to_string());

MDBook::init(root_dir)
    .create_gitignore(true)
    .with_config(cfg)
    .build()
    .expect("Book generation failed");

您也可以加载现有的书籍并构建它。

use mdbook::MDBook;

let root_dir = "/path/to/book/root";

let mut md = MDBook::load(root_dir)
    .expect("Unable to load the book");
md.build().expect("Building failed");

实现新的后端

mdbook 有一个相当灵活的机制来为您的书籍创建额外的后端。一般思路是在书籍的 book.toml 中添加一个额外的表，该表指定了由mdbook调用的可执行文件。在构建过程中，这个可执行文件将被调用，并将书籍的内存表示（RenderContext）通过stdin传递给子进程。

《RenderContext》提供了后端访问book.toml内容的方式，并告知所有生成的工件应放置在哪个目录。欲深入了解，请参阅用户指南中《开发者指南》部分的相关章节。

为了简化后端的创建，可以直接导入mdbook包，使反序列化RenderContext变得容易，并让您访问各种与Config交互的方法。