Quarto book 编写

Quarto Book

如何用Quarto写一本电子书，而且能导出HTML，PDF，Word，EPUB等格式

1. 总览

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

• HTML
• PDF
• Word
• EPUB

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

Book 可以理解为 是一个整合多个html文档的工具，带有章节编号，支持交叉引用，支持全文搜索

2. Book项目流程

2.1 创建Book Project

在Quarto中，可以使用多种工具启动Book项目，quarto亲爸爸–RStudio以及轻量化的VSCode，后续Rsutudio母公司力推Positron，整合了R和VSCode，个人用起来不如VSCode轻量化

VS Code

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

然后选择Book Project

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

新的图书项目将在 VS Code 中创建并打开。点击“预览”按钮。

RStudio

要在 RStudio 中创建一个新的图书项目，请使用 新建项目 命令并选择 Quarto 图书

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

点击Render按钮预览本书

2.2 Book Workflow

当你创建一个book project的时候，系统会自动生成各种推荐的初始文件

• index.qmd : 这是你的book的入口文件，也是你开始编写book的地方
• _quarto.yml: 这是你的book的配置文件，你可以在这里配置你的book的各种属性，比如标题，作者，语言，输出格式等等
• cover.png: 这是你的book的封面图片，你可以在这里上传你的封面图片
• summary.qmd: 这是你的book的摘要，你可以在这里写一些关于你的book的介绍
• references.bib: 这是你的book的参考文献，你可以在这里添加你的参考文献
• references.qmd: 这是你的book的参考文献列表，你可以在这里生成你的参考文献列表
• intro.qmd: 这是你的book的介绍，你可以在这里写一些关于你的book的介绍

1. Config File

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

• 该项目的类型：Book
• book的设置：(书名，作者，日期，章节分类，参考文献，输出格式)

2. Render

在写完任意的qmd文档之后，都可以使用render进行预览，进行实时修改

Note

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

3. Publishing 生成完整书籍

当你完成全部预览和修改之后，使用命令进行Render，在终端输入quarto render,book的输出会被统一放在_book目录中，这个目录在_quarto.yaml中设置

3. Book 结构

Quarto的书籍结构可以很简单，只有章节列表；也可以包含多个部分和/或附录。Quarto 书籍的章节和部分会自动编号（以便交叉引用），但您也可以指定书籍的某些部分不进行编号。

最简单的书籍结构会在创建项目的时候生成，如下所示：

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

• index.qmd是必须的，该书的 HTML 版本将使用 index.qmd 作为主页，如果提供了封面图片，则会将封面图片放置在该页面上,本页应包含前言、致谢等内容.Index就是常规书的致谢，欢迎等页面

• chapter显示是书的章节

• references.qmd显示的是参考文献，后续介绍

3.1 Title 标题

由于渲染选项在 _quarto.yml 中提供，因此您通常会在章节顶部看到一个简单的一级标题

这个的意思就是在每一个qmd的顶部，可以写一个一级标题，同时这个一级标题也代表着book的目录

3.2 章号

默认情况下，所有章节都会编号。如果您希望某个章节不编号，只需在其主标题后添加 .unnumbered 类即可。例如，通常会省略 index.qmd 的章节编号：

# Preface {.unnumbered}

您可以混合使用带编号的章节和不带编号的章。但请注意，虽然您可以链接到不带编号的章节，但您无法在不带编号的章节内交叉引用图表等内容。因此，未编号的章节主要用于作为引言内容或书末的参考文献

3.3 节号

您可以通过 number-depth 选项设置编号深度。例如，要仅对章节下方的节进行编号，请使用以下代码：

number-depth: 1

请注意，number-depth 是一个格式选项，而不是书籍选项，因此它位于 _quarto.yml 的顶层, 而不是嵌套在 book ，你可以单独详细的设置

format:
  pdf:
    number-depth: 1

目录深度选项与编号深度无关（即，如果目录条目被编号深度屏蔽，则可以在目录中包含未编号的条目

3.4 索引的构建

在书籍出版和文档编写（特别是技术书籍、学术论文）的语境下，Index（索引） 指的是位于书末的“主题索引”或“关键词索引”

它不是目录（Table of Contents），而是一个按字母顺序（中文通常按拼音或笔画）排列的关键词列表，告诉读者某个特定概念、术语、人名或工具在书中的哪些页码出现过。

特性	目录 (Table of Contents)	索引 (Index)
位置	书的最前面	书的最后面
排序方式	按章节顺序 (1, 2, 3…)	按字母/拼音顺序 (A, B, C…)
组织逻辑	作者的叙述逻辑 (故事线)	读者的查询逻辑 (关键词)
粒度	粗粒度 (章、节)	细粒度 (具体术语、概念、人名)
主要用途	浏览全书结构，按顺序阅读	解决具体问题，随机查阅
生成难度	简单 (自动根据标题生成)	复杂 (需要人工标记关键词 + 工具排序)

在book中，你可以对于PDF的输出文档，使用宏包来创建索引，主要是添加到_quarto.yml中，在文章的头添加使用包说明，在文章的尾添加索引

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header: 
      text: |
        \usepackage{makeidx}
        \makeindex
    include-after-body: 
      text: |
        \printindex

然后在你文章的任意位置，你都可以将词汇设置成index

Markdown\index{Markdown} allows you to write using an easy-to-read, easy-to-write plain text format.

3.5 Parts & Appendices

Note

请注意，EPUB 和 Word (Docx) 格式目前不支持将书籍分成多个部分。将包含多个部分的书籍渲染成这些格式时，这些部分将被忽略。

你也可以把书使用part的方式，进行分隔章节

book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: dice.qmd
      chapters: 
        - basics.qmd
        - packages.qmd
    - part: cards.qmd
      chapters:
        - objects.qmd
        - notation.qmd
        - modifying.qmd
        - environments.qmd

Markdown 文件 dice.qmd 和 cards.qmd可以包含部分标题（作为一级标题）以及该部分的一些介绍性内容。你也可以直接写词汇作为分段不进行连接md文件

您可以通过在图书配置中添加附录键来包含附录。附录的排序基本上是A，B，C，D之类的

如果你想改成更简洁或其他风格（例如 “App. A: Additional Resources”），你可以通过修改 _quarto.yml 配置文件来实现

# _quarto.yml

crossref:
  appendix-title: "App."      # 自定义前缀文本
  appendix-delim: ": "        # 自定义前缀和标题之间的分隔符

3.6 页面导航

如果一本书的某个章节或子章节有多页，通常会方便地让用户能够在刚刚读完的页面底部导航到下一页（或上一页）。启用后，无论何时存在下一页或上一页（包括在上一节或下一节中），页面导航都会显示在页面底部。此选项默认对书籍启用，但对网站禁用。

book:
  page-navigation: true

在页面下方有类似[< Previous: Introduction] [Next: Methods >]的标签，用来导航上下页面，pdf不会有

3.7 页脚

使用page-footer选项可以为书中所有页面提供一个通用的页脚。最简单的页脚仅提供居中显示且字体较浅的文本：

book:
  page-footer: "Copyright 2021, Norah Jones" 

您可以使用background、foreground和border选项来进一步控制页脚的外观。默认情况下，页脚没有背景色，并且有顶部边框。要移除边框，您可以这样做：

4. 书籍交叉引用

创建网站和创建书籍的一个重要区别在于，除了网络输出之外，书籍还可以呈现为单个连续文档（例如 PDF 或 MS Word 文档）。书籍可能以电子方式阅读，也可能不以电子方式阅读（这意味着内部超链接可能可用，也可能不可用）。

为了创作出可以在所有这些媒介中阅读的书籍，在创建指向其他章节或章节内小节的链接时应格外小心（但请注意，如果您的书籍仅针对 HTML 输出，则可以随意使用常规超链接）

• HTML 依赖 URL 路径（如 ./chapter2.html#section1）
• PDF 依赖内部锚点或页码（LaTeX 编译后生成的内部跳转）

Quarto 的交叉引用功能可为图表、表格、公式、章节、列表、定理和证明自动生成编号和引用。在书籍中，交叉引用的工作方式相同，只是可以跨章节查找。

4.1 创建引用

要引用图表或其他可交叉引用的实体，请使用 @ 语法（类似于引用），并加上您要引用的实体的 ID/标签：

See @fig-penginus-by-island for a breakdown by island.

要使章节或小节可被引用，需要在其主标题后添加 #sec 前缀,例如 # Introduction {#sec-introduction}

Important

为了能够使得章节交叉引用，标签必须是使用sec-前缀

要引用某个章节，请使用 @标识符添加交叉引用，就像我们在上面的示例中所做的那样See @sec-introduction for additional discussion.这样就会显示成

See Section 4 for additional discussion.

4.2 Chapter Numbering

在书籍中，图表和其他交叉引用目标会自动包含章节编号。例如，以下 Markdown 代码位于您书籍的第 3 章中

As illustrated in @fig-geo-comparison, the western states have a much higher incidence of forest fires.

请注意，虽然书籍支持不带编号的章节，但您自然无法创建指向没有编号的章节内容的交叉引用。

5. Book自定义输出类型

本文介绍了如何自定义图书项目的输出，包括如何针对每种受支持的输出格式调整图书的样式和外观。

如果您想指定渲染选项（包括格式特定的选项），则需要在 _quarto.yml 项目文件中进行设置，而不是在各个 Markdown 文档中进行设置。这是因为在渲染一本书时，所有章节都会合并到一个文档中（使用同一套格式选项）。

highlight-style: pygments

format:
  html:
    theme: cosmo
    code-copy: true
  pdf: default
    
bibliography: references.bib
csl: citestyle.csl

请注意，在上述配置中，高亮样式选项适用于所有格式，而 HTML 选项仅适用于 HTML 输出。参考文献相关选项自然也适用于所有格式。

book中也能增加这种关键的信息，比如导航图片，推特链接头像，网站地址等等

5.1 Sidebar Tools

侧边导航栏，书籍会自动包含一个导航侧边栏，其中可以选择性地包含用于搜索书籍内容、分享书籍链接等的工具。以下是一个启用这些选项的 _quarto.yml 文件示例：

book:
  title: "Hands-On Programming with R"
  author: "Garrett Grolemund"
  search: true
  repo-url: https://github.com/jjallaire/hopr/
  repo-actions: [edit]
  downloads: [pdf, epub]
  sharing: [twitter, facebook]
  
comments:
  hypothesis: true

• serach box栏 是用来全书搜索的
• 侧边栏中书籍标题正下方的按钮提供了指向该书 GitHub 代码库的链接、该书 PDF 和 ePub 版本的下载链接，以及在 Twitter 和 Facebook 上分享该书的链接。
• 在目录的右侧下方，有一个“编辑此页面”的链接，点击该链接即可进入 GitHub 上当前章节的编辑界面。主要是作者赋予的权限
• Hypothesis 的评论栏位于页面最右侧。请注意，评论功能适用于所有 Quarto HTML 输出，因此它位于单独的 YAML 键中。

Note

sidebar 也是可以设置的，同样在book下面进行设置

5.2 Cover Images

您可以使用封面图片选项为 EPUB 和/或 HTML 格式的文件添加封面图片。例如：

book:
  cover-image: cover.png

您也可以按格式进行此操作（例如，如果您想为 EPUB 提供更高分辨率的图像，为 HTML 提供更低分辨率的图像以减少下载时间）。

format:
   html: 
     cover-image: cover.png
   epub:
     cover-image: cover-highres.png