1.3 使用方法

有典型的 bookdown 书籍包括多个章节，并且每一章放在一个 R Markdown 文件中，文件的拓展名为 .Rmd。每一个 R Markdown 文件必须直接以本章标题作为开头，并使用一级标题，例如 # Chapter Title。全部 R Markdown 文件必须使用 UTF-8 编码，特别是当他们包含某些多字节字符时，例如中文、日文和韩文。以下是一个例子（the bullets are the filenames, followed by the file content):

index.Rmd

# 前言 {-}

在本书中，我们将会介绍一种有趣的方法。

01-intro.Rmd

# 简介

本章是我们提出的用来解决一个 **重要问题** 的方法的概述。

02-literature.Rmd

# 文献

下面是对现有方法的回顾。

03-method.Rmd

# 方法

我们在本章介绍了我们提出的方法。

04-application.Rmd

# 应用

本章中展示了一些_重要的_应用。

## 示例 1

## 示例 2

05-summary.Rmd

# 结语

我们完成了一本好书。

默认情况下，bookdown 按文件名的顺序合并所有 Rmd 文件，例如，01-intro.Rmd 将出现在 02-literature.Rmd 之前。以下划线 _ 开头的文件名将被跳过。如果存在名为 index.Rmd 的 Rmd 文件，则在合并所有 Rmd 文件时，它将始终被视为首个文件。使用这种特殊处理的原因是，从 index.Rmd 生成的 HTML 文件 index.HTML 通常是你查看网站时的默认主页，例如，当你打开 http://yihui.org/ 时，你实际上正在浏览 http://yihui.org/index.html。

你能够通过在书籍目录中包含一个名为 _bookdown.yml 的配置文件来覆盖程序的上述行为。它是一个 YAML 文件 (https://en.wikipedia.org/wiki/YAML)，R Markdown 用户应该对这种格式很熟悉，因为它也被用来在 R Markdown 文档开头编写元数据（你能够在第 B.2 节了解有关 YAML 的更多信息）。你可以使用一个名为 rmd_files 的字段来定义你自己的书籍文件列表与 Rmd 文件顺序。例如：

rmd_files: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]

使用上述方法时，bookdown 将会使用你在这个 YAML 字段（如果文件 index.Rmd 存在，它将会被添加进文件列表，并且以下划线命名的文件名将会被忽略）中定义的文件列表。如果你希望同时输出 HTML 和 LaTeX/PDF 文档，并且对于 HTML 和 LaTeX 输出使用不同的 Rmd 文件，你可以分别为这两种输出格式指定不同的文件列表，例如，

rmd_files:
  html: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]
  latex: ["abstract.Rmd", "intro.Rmd"]

尽管我们一直在谈论 R Markdown 文件，但章节文件实际上不必是 R Markdown 文件。它们可以是普通的 Markdown 文件 (.md)，并且完全不需要包含 R 代码块。你当然可以使用 bookdown 来创作小说和诗歌。但是，默认情况下，只有 .Rmd 文件（而不是 .md 文件）会被视为章节文件，从而被包含在自动收集的文件中。

目前，你可能会使用的主要的输出格式包括 bookdown::pdf_book、bookdown::gitbook、bookdown::html_book 和 bookdown::epub_book。软件包中有一个类似于 rmarkdown::render() 的函数 bookdown::render_book()，但它是为了使用输出格式函数将多个 Rmd 文档呈现在一本书中。你可以直接从命令行调用这个函数，或者点击 RStudio IDE 中的相关按钮。下面是一些命令行示例：

bookdown::render_book('foo.Rmd', 'bookdown::gitbook')
bookdown::render_book('foo.Rmd', 'bookdown::pdf_book')
bookdown::render_book('foo.Rmd', bookdown::gitbook(lib_dir = 'libs'))
bookdown::render_book('foo.Rmd', bookdown::pdf_book(keep_tex = TRUE))

为了在 RStudio IDE 中使用 render_book 和输出格式函数，可以定义一个名为 site 的 YAML 字段，其值为 bookdown::bookdown_site，¹并且输出格式函数可以在 output 字段中使用，例如：

---
site: "bookdown::bookdown_site"
output:
  bookdown::gitbook:
    lib_dir: "book_assets"
  bookdown::pdf_book:
    keep_tex: yes
---

然后你可以点击 RStudio 中 Build 选项卡下的 Build Book 按钮来将 Rmd 文件编译为一本书，或者点击工具栏中的 Knit 按钮来预览当前章节。

更多在 _bookdown.yml 中的 bookdown 设置将会在第 4.4 节中介绍。除了这些配置，你还能够在书籍的第一个 Rmd 文件中的 YAML 元数据里指定一些 Pandoc 相关的配置，例如标题、作者以及书籍付梓日期等。例如：

--- 
title: "Authoring A Book with R Markdown"
author: "Yihui Xie"
date: "`r Sys.Date()`"
site: "bookdown::bookdown_site"
output:
  bookdown::gitbook: default
documentclass: book
bibliography: ["book.bib", "packages.bib"]
biblio-style: apalike
link-citations: yes
---

这个函数会调用 bookdown::render_book()。↩︎