【mdBook】3 创建书籍

安装 mdbook CLI 工具后，您可以使用它来创建和渲染书籍。

初始化书籍

mdbook init 命令将创建一个包含空书籍的新目录，供您开始使用。指定您想要创建的目录名称：

mdbook init my-first-book

在生成书籍之前，它会询问几个问题。回答完问题后，您可以进入新书籍的目录：

cd my-first-book

有多种渲染书籍的方法，但最简单的方法之一是使用 serve 命令，该命令将构建您的书籍并启动本地 Web 服务器：

mdbook serve --open

--open 选项将在您的默认网页浏览器中打开新书籍。即使您在编辑书籍内容时，也可以让服务器保持运行，mdbook 将自动重新构建输出并自动刷新您的网页浏览器。

查看 CLI 指南以获取有关其他 mdbook 命令和 CLI 选项的更多信息。

书籍结构

书籍由多个文件构建而成，这些文件定义了书籍的设置和布局。

book.toml

在书籍的根目录中，有一个 book.toml 文件，其中包含描述如何构建书籍的设置。该文件使用 TOML 标记语言编写。默认设置通常足以让您开始使用。当您有兴趣探索 mdBook 提供的更多功能和选项时，请查看配置章节以获取更多详细信息。

一个非常基础的 book.toml 可以简单如下：

[book]
title = "我的第一本书"

SUMMARY.md

书籍的下一个主要部分是位于 src/SUMMARY.md 的摘要文件。此文件包含书籍中所有章节的列表。在可以查看章节之前，必须将其添加到此列表中。

这是一个包含几个章节的基本摘要文件：

# 摘要[介绍](README.md)- [我的第一章](my-first-chapter.md)
- [嵌套示例](nested/README.md)- [子章节](nested/sub-chapter.md)

尝试在编辑器中打开 src/SUMMARY.md 并添加一些章节。如果任何章节文件不存在，mdbook 将自动为您创建它们。

有关摘要文件的其他格式选项的更多详细信息，请查看摘要章节。

源文件

书籍的内容全部包含在 src 目录中。每个章节都是一个独立的 Markdown 文件。通常，每个章节以包含章节标题的一级标题开始。

# 我的第一章在此填写您的内容。

文件的具体布局由您决定。文件的组织将对应于生成的 HTML 文件，因此请记住文件布局是每个章节 URL 的一部分。

当 mdbook serve 命令运行时，您可以打开任何章节文件并开始编辑它们。每次保存文件时，mdbook 将重新构建书籍并刷新您的网页浏览器。

查看 Markdown 章节以获取有关格式化章节内容的更多信息。

src 目录中的所有其他文件将包含在输出中。因此，如果您有图像或其他静态文件，只需将它们包含在 src 目录中的某处即可。

发布书籍

完成书籍编写后，您可能希望将其托管在某处供他人查看。第一步是构建书籍的输出。这可以通过在 book.toml 文件所在的目录中运行 mdbook build 命令来完成：

mdbook build

这将生成一个名为 book 的目录，其中包含书籍的 HTML 内容。然后，您可以将此目录放在任何 Web 服务器上进行托管。

有关发布和部署的更多信息，请查看持续集成章节以获取更多内容。