书籍结构

概述

Quarto 书籍的结构可以简单到只是一系列章节，或者可以包含多个部分和/或附录。Quarto 书籍的章节和部分会自动编号（用于交叉引用），但您也可以指定书籍的某些部分应保持未编号状态。

quarto create project book 生成的简单书籍配置展示了基本内容：

book:
  title: "我的书籍"
  author: "简·多伊"
  date: "2021/5/9"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

• index.qmd 文件是必需的（因为 Quarto 书籍还会生成 HTML 格式的网站）。此页面应包含前言、致谢等内容。书籍的 HTML 版本将使用 index.qmd 作为首页，如果提供了 cover-image，则会将其放置在该页面上。
• chapters 的其余部分包含一个或多个书籍章节。
• references.qmd 文件将包含生成的参考文献（详见下文的 参考文献）。

标题

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

# 引言

请注意，以下内容仍然完全有效：

---
title: "引言"
---

在没有第一级标题或 YAML 前文中设置标题的情况下，页面中的第一个标题将被用作标题。

章节编号

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

index.qmd

# 前言 {.unnumbered}

您可以混合使用编号和未编号的章节。但请注意，虽然您可以链接到未编号的章节，但无法在其中进行交叉引用图表等。未编号的章节因此主要适用于前言内容或书籍末尾的参考资料。

部分编号

您可以通过 number-depth 选项设置编号深度。例如，仅对紧接在章节级别下的部分进行编号，请使用以下内容：

number-depth: 1

请注意，toc-depth 与 number-depth 是独立的（即，如果它们被 number-depth 屏蔽了编号，您可以在目录中包含未编号的条目）。

参考文献

您应在书籍中希望生成参考文献的位置包含一个带有 #refs id 的 div。例如，quarto create project book 生成的 references.qmd 文件包含以下内容：

# 参考文献 {.unnumbered}

::: {#refs}
:::

请注意，您可以将章节标题更改为任何您喜欢的内容，移除 .unnumbered 以使其像其他章节一样编号，并根据需要在参考文献前后添加其他内容。

创建索引

对于 PDF 输出，您可以使用 LaTeX 的 makeidx 包和 \index 命令创建索引。

要为书籍的 PDF 输出添加索引，请在 _quarto.yml 中的 pdf 格式配置中添加这些 include-in-header 和 include-after-body 条目：

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

然后，在您希望添加索引条目的任何地方添加 \index{entry} 命令。例如：

Markdown\index{Markdown} 允许您使用易于阅读、易于书写的纯文本格式进行写作。

或者，您也可以使用 imakeidx 包。此包提供了额外的功能来格式化索引。例如：

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    include-in-header: 
      text: |
        \usepackage{imakeidx}
        \makeindex[intoc=true, columns=3, columnseprule=true, options=-s latex/indexstyles.ist]
    include-after-body: 
      text: |
        \printindex

在上面的示例中，intoc=true 将在目录中包含索引条目，columns=3 将索引格式化为三列，columnseprule=true 将在索引列之间显示一条线。最后，options=-s latex/indexstyles.ist 将从位于 latex/indexstyles.ist 的索引样式文件中使用额外的格式化选项。imakeidx 包中还有许多其他功能。请参阅其文档以获取更多详细信息。

请注意，\index 命令会自动忽略非 PDF 输出。

部分与附录

请注意

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

你可以使用 part 在书籍的 chapters 中将书籍分成部分。例如：

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 包含部分标题（作为一级标题）以及部分的一些介绍性内容。如果你只需要一个部分标题，那么你可以使用以下语法：

- part: "Dice"
  chapters: 
    - basics.qmd
    - packages.qmd

你可以通过在 book 配置中添加 appendices 键来包含附录。例如：

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

部分和附录在 HTML 输出中显示如下：

在 LaTeX 输出中，使用 \part 命令表示部分。在 EPUB 和 MS Word 输出中，部分完全被忽略。

附录使用大写字母编号，并在其标题中插入前缀以表明它们是附录（例如 “Appendix A — Additional Resources”）。你可以使用以下选项自定义前缀和分隔符：

crossref:
  appendix-title: "App."
  appendix-delim: ":"

这将导致上述示例输出为：“App. A: Additional Resources”。

页面导航

如果你有一个包含多个页面的小节或子小节的book，通常很方便为用户提供在阅读完当前页面后导航到下一页（或上一页）的功能。你可以通过以下方式启用此功能：

book:
  page-navigation: true

启用后，每当存在下一页或上一页（包括下一节或上一节）时，页面导航将显示在页面底部。此选项默认对书籍启用，但对网站不启用。

你还可以通过在YAML头部指定page-navigation来在页面级别启用或禁用页面导航，例如：

basics.qmd

---
page-navigation: false
---

或者，要控制目录中所有页面的页面导航，请在_metadata.yml中指定page-navigation：

_metadata.yml

page-navigation: false