创建一本书

概述

Quarto 书籍是将多个文档（章节）组合成一个手稿。书籍可以以多种格式创建：

HTML
PDF
MS Word
EPUB
AsciiDoc

HTML 书籍实际上只是 Quarto 网站的一种特殊类型，因此支持与网站相同的所有功能，包括全文搜索。最重要的区别是 HTML 书籍使用章节编号，因此支持不同章节之间的交叉引用。

以下是一些使用 Quarto 创建的书籍示例：

书籍	源代码
R for Data Science	代码
Python for Data Analysis	代码
Visualization Curriculum	代码

Quarto 书籍可以发布到多种目的地，包括 GitHub Pages、Netlify、RStudio Connect 或任何其他静态托管服务或内联网服务器。有关更多详细信息，请参阅发布网站的文档。

快速开始

根据您选择的工具，按照快速开始指南创建并运行一个简单的书籍。在了解基础知识后，继续阅读以了解更高级的书籍功能。

要在 VS Code 中创建一个新的书籍项目，从命令面板执行 Quarto: Create Project 命令：

然后，选择 Book Project：

系统会提示您选择一个父目录来创建项目。然后，系统会要求您为书籍项目命名目录：

新的书籍项目将在 VS Code 中创建并打开。点击 Preview 按钮（）预览书籍：

预览将显示在源文件的右侧。当您重新渲染 index.qmd 或渲染其他文件如 intro.qmd 时，预览会自动更新。

要在 RStudio 中创建一个新的书籍项目，使用 New Project 命令并选择 Quarto Book：

然后，提供一个目录名称和其他相关的书籍选项：

点击 Render 按钮预览书籍：

预览将显示在源文件的右侧。当您重新渲染 index.qmd 或渲染其他文件如 intro.qmd 时，预览会自动更新。

要从终端创建一个新的书籍项目，使用 quarto create project 命令，按照提示选择类型并为项目提供名称（将用作目录名称）：

Terminal

quarto create project book mybook

这将在 mybook 子目录中创建一个简单书籍的脚手架。使用 quarto preview 命令渲染并预览书籍：

Terminal

quarto preview mybook

书籍预览将在新的网络浏览器中打开。当您编辑并保存 index.qmd（或其他文件如 intro.qmd）时，预览会自动更新。

工作流程

上面我们演示了如何使用 index.qmd、intro.qmd、summary.qmd 文件创建和编辑一个简单的书籍。这里我们将更深入地介绍书籍工作流程的其他方面。

配置文件

Quarto 项目文件（_quarto.yml）包含在书籍项目目录中。此文件包含书籍的初始配置。例如：

project:
  type: book

book:
  title: "mybook"
  author: "Jane Doe"
  date: "8/18/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub:
    cover-image: cover.png

请参阅项目基础文章，了解更多关于项目工作的信息，包括如何为您的书籍添加自定义的预渲染和后渲染脚本。

书籍预览

如果您使用的是VS Code或RStudio，预览按钮（VS Code）或渲染按钮（RStudio）会自动在嵌入窗口中渲染并运行quarto preview。如果需要，您也可以从终端执行相同的操作：

Terminal

# 在当前目录预览书籍
quarto preview

请注意，当您预览书籍时（无论是使用VS Code/RStudio集成工具还是从终端），对配置文件（例如_quarto.yml）以及书籍资源（例如主题或CSS文件）的更改将导致预览自动刷新。

您可以使用命令行选项或_quarto.yml配置文件自定义预览服务器的行为（端口、是否打开浏览器等）。有关更多详细信息，请参阅quarto preview help或项目文件参考。

Important

在预览书籍时，章节将被渲染和更新。但是，如果您对全局选项（例如_quarto.yml或包含的文件）进行更改，您需要完全重新渲染您的书籍以反映所有更改。因此，即使您已经使用预览服务器预览了某些页面的更改，也应该始终在部署之前完全quarto render您的站点。

对于AsciiDoc书籍，我们建议使用HTML格式预览您的书籍，更多信息请阅读AsciiDoc书籍。

发布

当您准备好发布书籍时，使用render命令渲染所有输出格式：

Terminal

quarto render

如果您不向quarto render传递任何参数，所有格式都将被渲染。您还可以通过--to参数渲染单个格式：

Terminal

quarto render           # 渲染所有格式
quarto render --to pdf  # 仅渲染PDF格式

您的书籍输出将写入书籍项目的_book子目录：

Terminal

mybook/
  _book/
    index.html # 以及其他书籍文件
    mybook.pdf
    mybook.epub

有关如何将书籍发布到GitHub Pages、Netlify和其他服务的详细信息，请参阅发布网站的文档。请注意，在该文档中，output-dir可能被称为_site：对于发布书籍，您应该使用_book而不是_site。

AsciiDoc书籍

对于AsciiDoc书籍，我们建议在您编写书籍时，使用Quarto内置的HTML格式预览您的内容，这允许使用Quarto的预览功能进行迭代工作流程。一旦您准备好生成AsciiDoc，您可以使用AsciiDoctor工具将您的书籍编译为PDF或HTML输出，以预览内容的最终渲染形式。

使用Asciidoctor-pdf预览PDF

使用AsciiDoc工具链创建PDF预览是验证您的书籍的AsciiDoc输出是否能正确渲染的有用方法。为此，请按照以下说明操作：

首先，按照此处的说明安装Asciidoctor PDF：https://docs.asciidoctor.org/pdf-converter/latest/install/
在项目根目录的终端中，使用以下命令将您的AsciiDoc书籍编译为PDF：
```
$  asciidoctor-pdf _book/book-asciidoc/<title>.adoc
```
PDF将放置在_book/book-asciidoc/<title>.pdf。

使用Asciidoctor预览HTML

使用AsciiDoc工具链创建HTML预览是验证您的书籍的AsciiDoc输出是否能正确渲染的有用方法。为此，请按照以下说明操作：

首先，按照此处的说明安装Asciidoctor：https://docs.asciidoctor.org/asciidoctor/latest/install/
在项目根目录的终端中，使用以下命令将您的AsciiDoc书籍编译为PDF：
```
$  asciidoctor _book/book-asciidoc/<title>.adoc
```
一个包含整个书籍内容的单个HTML文件将放置在_book/book-asciidoc/<title>.html。HTML文件将包含对_book/book-asciidoc/文件夹中的文件和图像的引用，因此如果未同时移动这些文件夹，HTML将无法正确显示这些内容。

了解更多

一旦您掌握了基本的书籍模板并运行起来，请查看以下文章，了解各种增强书籍的方法：

书籍结构深入探讨了构建书籍的不同方式（编号和未编号的章节/部分，创建多个部分，添加附录等）
书籍交叉引用解释了如何在书籍中创建对章节、图表、表格、方程等的交叉引用。
书籍输出涵盖了在各种输出格式中自定义书籍样式和外观的方法，以及如何为读者提供导航和其他工具。
书籍选项提供了所有可用书籍选项的全面参考。
代码执行提供了优化包含大量文档或昂贵计算的书籍渲染的技巧。
发布网站列举了将书籍发布为网站的各种选项，包括 GitHub Pages、Netlify 和 RStudio Connect。