其中在三个减号组成的两行之间的内容叫做YAML元数据， 是一本书的设置， 上例中有书的标题、作者名、日期（用R程序自动生成）、描述。 其中的 site 选项很重要， 一定要有这个选项， site: bookdown::bookdown_site 使得RStudio软件能辨认这是一个bookdown图书项目， 从而为其提供一键编译快捷方式。 元数据中 output 项指定默认的输出格式。 documentclass 项为借助LaTeX编译PDF格式指定LaTeX的模板， 现在还不能支持ctexbook模板所以使用了book模板。 bibliography 项指定一个或者几个.bib格式的文献数据库。

一个bookdown图书项目除了 index.Rmd 文件之外， 一般还应该有一个 _bookdown.yml 文件存放与整本书有关的YAML元数据。

其中 new_session: true 设置很重要， 这使得每一个Rmd文件中的R程序都在一个单独的R会话中独立地运行， 避免了不同Rmd文件之间同名变量和同名标签的互相干扰。 book_filename 是最终生成的LaTeX PDF图书或者ePub电子书的主文件名。 language 下可以定制一些与章节名、定理名等有关的名称。

另外一个需要的设置文件是 _output.yml 文件， 用于输出格式的设置。 这部分内容也可以包含在 index.Rmd 的元数据中 output 条目下面。

其中的 style.css 是自定义的CSS显示格式， 可以去掉这一行，使用默认的CSS格式。 这个例子文件分为三部分， gitbook、pdf_book和epub_book三种输出格式分别设置了一些输出选项。 在gitbook部分， 设置了目录上方显示的书的主页的链接（ before 项）和目录下方显示的作者信息。 在 in_header 部分插入了一部分个性化的HTML代码， 这部分代码是使用本地的数学公式显示支持以免外网不通时数学公式不能显示， 插入的内容将出现在每个生成的HTML文件的head部分。

在 pdf_book 部分，设置了通过LaTeX编译整本书为PDF的一些选项。 指定了 latex_engine 为 xelatex ， 这对中文支持很重要。 in_header 选项要求在LaTeX文件导言部分插入一个 preamble.tex 文件，

\usepackage{ctex}
\usepackage{amsthm,mathrsfs}
\usepackage{booktabs}
\usepackage{longtable}
\makeatletter
\def\thm@space@setup{%
  \thm@preskip=8pt plus 2pt minus 4pt
  \thm@postskip=\thm@preskip
\makeatother

其中很重要的是使用ctex包来支持中文。 在index.Rmd的元数据中也可以指定一些LaTeX选项， 比如指定页边距等（这些设置有些是非标准的，一般不需要）：

在bookdown项目中与 index.Rmd 同级的所有.Rmd文件都自动作为书的一章， 除非文件名以下划线开头。 这样做的好处是作者可以任意地增删章节， 编译整本书时章节编号会自动调整。 章节的顺序将按照文件名的字典序排列， 所有的包含一章内容的.Rmd文件， 最好命名为类似 0201-rng.Rmd 这样的名字， 文件名前面人为地加上排序用的序号， 使得章节按照自己的次序排列。 也可以设置不自动将每个.Rmd文件都作为一章， 而是在 _output.yml 中设置一项 rmd_files ， 列出所有需要作为一章的文件，并以列出次序编译，如

这时，应该添加一个 _site.yml 文件，内容如：

这些章标签去掉井号后会作为生成的HTML文件的名字， 所以一定要有章标签， 而且章节标签在全书中都不要重复以免冲突。 文件内可以用两个井号和一个空格开始的行表示节标题， 最后也应该有大括号内以井号开头的节标签，如

使用bookdown写书， 一般每章不要太长， 否则编译预览很慢， 读者浏览网页格式也慢。

内容相近的章节可以作为一个“部分”。 在一个部分的第一个章节文件的章标题前面增加一行， 以 # (PART) 开头， 以 {-} 结尾， 中间是部分的名称，如

书的最后可以有附录， 附录的章节将显示为 A.1 , B.1 这样的格式。 在附录章节的第一个文件开头加如下的第一行标题行：

编译结果默认保存在 _book 子目录中， 可以在 _bookdown.yml 中设置 output_dir 项改为其它子目录。 编译整本书为pdf_book格式时，如果成功编译， 也会弹出一个PDF预览窗口。 可以在 _book 子目录中找到这个PDF文件。

其中 chap-name.Rmd 是要编译的单章的文件名。 编译完成后在结果目录（默认是 _book ）中找到相应的HTML文件打开查看， 再次编译后仅需在浏览器中重新载入文件。 建议使用Google chrome浏览器， 用MS IE或者Edge浏览器对gitbook的Javascrpt支持不够好， 使得目录的层级管理、自动滚动、单章编译后的目录更新不正常， 而chrome则没有问题。

编译单章也不能解决所有的问题， 有些问题还是需要编译整本书， 而章节很多时整本书编译又太慢。 可以在项目中增加一个临时的部分内容子目录， 如 testing 子目录， 在子目录中存放相同的设置文件 index.Rmd 、 _bookdown.yml 、 _output.yml ， 以及图形文件、文献数据库文件， 并将要检查的若干章节复制到 testing 子目录中， 在 testing 中新建一个bookdown项目， 然后编译其中的整本书。 这在调试部分章节的HTML和PDF输出时很有效。 解决问题后只要将修改过的章节复制回原始的书的目录中。

有时仅仅想验证某个长数学公式或者表格， 用上述的编译单章或者单独一个小规模测试项目的办法也不经济。 这时，单独开一个备用的普通RStudio项目， 不能是bookdown项目， 在其中的Rmd文件中验证数学公式和表格的编排， 这样最为方便。

有时需要根据编译输出目标采用不同的设置， 输出为html时可以使用HTML插件(widgets)， 而输出到PDF则不可以。 knitr::opts_knit$get("rmarkdown.pandoc.to") 感知当前编译过程的目标， 对HTML类，输出为 "html" ， 对PDF，输出为 "latex" 。