bookdown初始文件生成

在RStudio中通过project管理一个bookdown项目，因此需要我们初始化生成bookdown文件，具体步骤如下：

1. 打开RStudio
2. File
3. New propject
4. New Directory
5. Book project using bookdown
6. 命名文件夹
7. Create Project

新创建的 bookdown项目会包含一些必要的文件和演示文件。接下来我们将具体介绍每个文件的设置。

主要文件简介

index.Rmd文件

一本bookdown书， 一般都有一个index.Rmd文件， 这是最后生成的网站的主页的原始文件， 可以在这个文件中写一些书的说明， 并在开头的YAML元数据部分进行有关设置， 如标题、作者、日期等。一个示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

--- 
title: "PLAU Project Online Viewing and Collaboration"
author: "苏总华"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
output: bookdown::gitbook
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: 
# url: your book url like https://bookdown.org/yihui/bookdown
# cover-image: path to the social sharing image like images/cover.jpg
description: |
  This is an online version of the PLAU project analysis.
link-citations: yes
github-repo: smileszh/PLAU
---

# Introdution {-}

  Past analysis results can be viewed online!

• title: “标题”
• author: “作者”

• date: \”r Sys.Date()” # 自动生成文档创建时间

• site: bookdown::bookdown_site #使得RStudio软件能辨认这是一个bookdown图书项目， 从而为其提供一键编译快捷方式

• output: bookdown::gitbook # 默认输出格式
• documentclass: book # PDF模版格式
• bibliography: [book.bib, packages.bib] # 指定文献数据库格式
• description: 描述
• github-repo: smileszh/PLAU # repo地址

_bookdown.yml文件

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

new_session: true
book_filename: "PLAU project"
delete_merged_file: true
output_dir: "docs"
language:
  ui:
    chapter_name: ""
  label:
    thm: '定理'
    def: '定义'
    exm: '例'
    proof: '证明: '
    solution: '解: '
    fig: '图'
    tab: '表'

其中new_session: true设置很重要， 这使得每一个Rmd文件中的R程序都在一个单独的R会话中独立地运行， 避免了不同Rmd文件之间同名变量和同名标签的互相干扰。 book_filename是最终生成的LaTeX PDF图书或者ePub电子书的主文件名。 language下可以定制一些与章节名、定理名等有关的名称。output_dir: "docs"可以设置渲染后都输出文件夹，默认是_book，但是如果要托管在GitHub page上，一定要设置这个参数，方便GitHub在线查看。

_output.yml文件

_output.yml文件， 用于输出格式的设置。 这部分内容也可以包含在index.Rmd的元数据中output条目下面。 例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

bookdown::gitbook:
  toc_depth: 2
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">A online version of PLAU project</a></li>
      after: |
        <li><a href="https://github.com/smileszh" target="blank">编辑: 苏总华</a></li>
    # edit: https://github.com/USERNAME/REPO/edit/BRANCH/%s
    download: ["pdf", "epub"]
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

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

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

1
2
3
4
5
6
7
8
9
10
11

\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

章节结构

除了index.Rmd文件， 项目中每个.Rmd文件都作为一章。 每个.Rmd文件第一行， 应该是以一个井号和空格开头的一级标题， 后面再加空格然后有大括号内以井号开头的章标签， 如

1

# 随机数 {#rng}

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

1
2
3

# 随机数 {#rng}

## 均匀随机数发生器 {#rng-unif}

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

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

1
2
3

# (PART) 随机数和随机模拟 {-}

# 随机数 {#rng}

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

1
2
3

# (APPENDIX) 附录 {-}

# 一些定理的证明 {#formula}

书的编译

在index.Rmd或者_bookdown.yml中设置site: bookdown::bookdown_site后， RStudio就能识别这个项目是一个bookdown项目， 这时RStudio会有一个Build窗格，其中有“Build book”快捷图标， 从下拉菜单中选择一个输出格式（包括gitbook、pdf_book、epub_book）， 就可以编译整本书。 对gitbook格式， 即HTML网页格式， 编译完成后会弹出一个预览窗口， 其中的“Open in Browser”按钮可以将内容在操作系统默认的网络浏览器中打开。

另一种办法是在命令窗口用如下命令编译，以输出gitbook为例：

1
2

bookdown::render_book("index.Rmd", 
  output_format="bookdown::gitbook")

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

每次编译都花费很长时间， 所以可以仅编译gitbook格式的一章， 修改满意后再编译整本书。 仅编译一章也需要所有的.Rmd文件都是已经编译过一遍的， 新增的Rmd文件会使得编译单章出错， 每次新增了Rmd文件都应该重新编译整本书， 但是内容修改后不必要重新编译整本书， 可以仅编译单章。

编译单章现在没有快捷图标， 只能在RStudio控制台（命令行）运行如下命令：

1
2

bookdown::preview_chapter("chap-name.Rmd", 
  output_format="bookdown::gitbook")

其中chap-name.Rmd是要编译的单章的文件名。 编译完成后在结果目录（默认是_book）中找到相应的HTML文件打开查看， 再次编译后仅需在浏览器中重新载入文件。

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