本教程來自華東師范大學(xué)湯銀才教授，本人已授權(quán)。為了獲得更好的閱讀體驗(yàn)，可在文末直達(dá)原文網(wǎng)站。

第 2 章 bookdown速覽

這是第 2 章的內(nèi)容，概要性地講解基于bookdown拓展包進(jìn)行圖書排版的整體思路與實(shí)現(xiàn)方式.

2.1 關(guān)于bookdown

bookdown擴(kuò)展包 (https://github.com/rstudio/bookdown) 是繼knitr和rmarkdown擴(kuò)展包之后， 另一個(gè)增強(qiáng)markdown格式的擴(kuò)展， 使得Rmd格式可以支持公式、定理、圖表、文獻(xiàn)自動(dòng)編號和引用等適用于編寫書籍的功能。在bookdown的管理下一本書的內(nèi)容可以按章節(jié)分解成多個(gè)Rmd文件， 其中可以包含可執(zhí)行的R代碼， R代碼生成的統(tǒng)計(jì)匯總結(jié)果、表格、圖形可以自動(dòng)插入到生成的內(nèi)容中， 表格和圖形可以是浮動(dòng)排版的。書的輸出格式包括支持gitbook格式的網(wǎng)頁圖書， 也可以經(jīng) LATEX 編譯器轉(zhuǎn)換的PDF圖書，還可以生成ePub等格式的電子書。建議使用RStudio集成環(huán)境來編輯、管理和生成這樣的圖書，可通過其內(nèi)建的一鍵式編譯整本書的插件(build)實(shí)現(xiàn)。

2.2 快速排版的思路

由rmarkdown完成整個(gè)書稿的寫作;

由_output.yml完成不同形式呈現(xiàn)的書稿的設(shè)計(jì)，其中bookdown::gitbook負(fù)責(zé)html形式的gitbook, bookdown::pdf_book 負(fù)責(zé)pdf形式的電子書（由 TEXTEX 支持)；bookdown::epub_book負(fù)責(zé)epub電子書. 部分針對書稿簡單設(shè)置可放在index.Rmd文件的yml頭部(具體放在前面兩組三個(gè)短線---之間);

書稿按章節(jié)進(jìn)行拆分，借助js支持的html快速生成書稿的初稿，最后再進(jìn)行整合，根據(jù)需要通過Build插件完成gitbook, pdf_book, epub的構(gòu)建;

借助mathjax處理數(shù)學(xué)公式的渲染;

盡快可通過聯(lián)網(wǎng)由cdn上的mathjax.js進(jìn)行渲染，但速度隨因公式的增加，渲染變得很慢，甚至出錯(cuò)。mathjax的本地化是提速的主要解決方案.

重點(diǎn)做好章節(jié)、數(shù)學(xué)公式、表格、圖形、定理、文獻(xiàn)等浮動(dòng)對象的處理，在編寫過程中及時(shí)做好標(biāo)簽設(shè)定與引用，見2.6節(jié)的匯總表格及后續(xù)各章的介紹與示例.

2.3 書的基本設(shè)置

一本用bookdown管理的書， 一般放置在某個(gè)子目錄下，并作為一個(gè)RStudio項(xiàng)目(project)用RStudio管理。該目錄中的所有的文本文件都要使用UTF-8編碼。

2.3.1 index.Rmd文件

一本bookdown書， 一般都需要有一個(gè)index.Rmd文件， 這是最后生成的網(wǎng)站的主頁的原始文件. 這個(gè)文件的開始是YAML元數(shù)據(jù)部分, 進(jìn)行全書的有關(guān)設(shè)置，包括標(biāo)題、作者、日期及影響全書的一些選項(xiàng)等，放在三個(gè)減號組成的兩行之間。然后寫一些這本書的說明，如書的前言部分。index.Rmd中YAML元數(shù)據(jù)部分的一個(gè)例子如下：

title:?"bookdown書稿模板" author:?"湯銀才" date:?"2021-07-25" documentclass:?book bibliography:?[myrefs.bib] biblio-style:?apa link-citations:?yes site:?bookdown::bookdown_site description:?"bookdown寫書體驗(yàn)非常好."

注意:

site選項(xiàng)很重要， 一定要有， site: bookdown::bookdown_site使得RStudio能辨認(rèn)這是一個(gè)bookdown圖書項(xiàng)目， 從而為其生成一鍵編譯的build快捷方式；

在bookdown項(xiàng)目中與index.Rmd同級的所有.Rmd文件都自動(dòng)作為書的一章，其好處是作者可以任意地增刪章節(jié)，編譯整本書時(shí)將按照文件名的字典序依次進(jìn)行。實(shí)際上， 也可以在_output.yml文件中設(shè)置一項(xiàng)rmd_files， 列出所有需要作為一章的文件，并以列出次序編譯；

在index.Rmd的元數(shù)據(jù)中也可以指定一些 LATEX 的選項(xiàng), 例如

fontsize:?12pt indent:?true linestretch:?2.0 link-citations:?yes colorlinks:?yes lot:?true lof:?true geometry: -?a4paper -?tmargin=2.5cm -?bmargin=2.5cm -?lmargin=3.5cm -?rmargin=2.5cm

2.3.2 _bookdown.yml文件

一個(gè)bookdown圖書項(xiàng)目除了index.Rmd文件之外，還有一些設(shè)置文件從index.Rmd文件的元數(shù)據(jù)部分抽離出來。一個(gè)是_bookdown.yml文件, 它存放與整本書的處理有關(guān)的YAML元數(shù)據(jù)。例如

book_filename:?"bookdown-template" new_session:?yes language:label:fig:?"圖?"tab:?"表?"thm:?'定理'def:?'定義'exm:?'例'proof:?'證明:?'ui:chapter_name:?["第?",?"?章"]

其中new_session: true設(shè)置很重要，這使得每一個(gè)Rmd文件中的R程序都在一個(gè)單獨(dú)的R會(huì)話中獨(dú)立地運(yùn)行，避免了不同Rmd文件之間同名變量和同名標(biāo)簽的互相干擾。book_filename是最終生成的PDF圖書或者ePub電子書的主文件名。language下可以定制一些與章節(jié)名、定理名等有關(guān)的名稱。

2.3.3 _output.yml文件

另一個(gè)設(shè)置文件是_output.yml， 用于圖書輸出格式的設(shè)置, 本小冊子的_output.yml文件內(nèi)容如下

bookdown::gitbook:css:?css/style.csssplit_by:?chapterincludes:in_header:?_header.htmlconfig:toc:collapse:?subpscroll_highlight:?yesbefore:?|<li><a?href="./">bookdown排版模板</a></li>after:?|<li><a?href="https://bookdown.org"?target="blank">本書由?bookdown?強(qiáng)力驅(qū)動(dòng)</a></li>download:?[pdf,?epub]edit:?https://github.com/yihui/bookdown-chinese/edit/master/%ssharing:github:?yesfacebook:?nopandoc_args:?[?"--csl",?"apa-6th-edition-no-ampersand.csl"?] bookdown::pdf_book:includes:in_header:?latex/preamble.texbefore_body:?latex/before_body.texafter_body:?latex/after_body.texkeep_tex:?yesdev:?"cairo_pdf"latex_engine:?xelatexcitation_package:?biblatextemplate:?latex/template.textoc_depth:?3toc_unnumbered:?notoc_appendix:?yesquote_footer:?["\\begin{flushright}",?"\\end{flushright}"]pandoc_args:?[?"--top-level-division=chapter"?] bookdown::epub_book:stylesheet:?css/style.csspandoc_args:?[?"--csl",?"apa-6th-edition-no-ampersand.csl"?]

它分別對gitbook、pdf_book和epub_book三種輸出格式設(shè)置了一些輸出選項(xiàng)。其中一些選項(xiàng)是通過文件形式給出設(shè)置的，我們再補(bǔ)充說明一下。

style.css是自定義的 CSS 顯示格式，在gitbook和epub_book中使用;

_header.html是插入了一部分個(gè)性化的HTML代碼，其內(nèi)容將出現(xiàn)在每個(gè)生成的HTML文件的head部分。我們在此文件中給出了使用本地的Mathjax實(shí)現(xiàn)數(shù)學(xué)公式離線顯示的設(shè)置，內(nèi)容為

<script?type="text/x-mathjax-config"> MathJax.Hub.Config({jax:?["input/TeX","output/SVG"],extensions:?["tex2jax.js","MathMenu.js","MathZoom.js"],TeX:?{Macros:?{bm:?["{\\boldsymbol?#1}",1],},extensions:?["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"]} });</script> <script?type="text/javascript"src="http://127.0.0.1/MathJax/MathJax.js"> </script>

其中http://127.0.0.1/MathJax/是本地服務(wù)器上Mathjax的位置。

3.apa-6th-edition-no-ampersand.csl 是gitbook和epub_book處理文獻(xiàn)使用的風(fēng)格文件;

4.preamble.tex是處理(編譯)bookdown文件經(jīng)pandoc轉(zhuǎn)化生成的tex文件時(shí)導(dǎo)言區(qū)需要額外的宏包和設(shè)置;

5. before_body.tex 是tex書稿類正文前面的設(shè)置，最基本的是

?\frontmatter

6.?after_body.tex 是tex書稿類正文之后的設(shè)置，最基本的是

\backmatter 7.?`template.tex`?是針對`bookdown`編譯經(jīng)`pandoc`轉(zhuǎn)化生成的`tex`文件時(shí)的模板，由它生成供`latex_engine`指定的編譯方式(`xelatex`)編譯的`tex`文件.?`index.Rmd`及`_output.yml`中的設(shè)置會(huì)嵌入到這個(gè)模板中，生成完整的單文檔`tex`源文件.

其他選項(xiàng)說明：

split_by: chapter: 按章分割書稿；

collapse: subp: 目錄中隱藏子節(jié)(僅顯示二級標(biāo)題)；

scroll_highlight: yes: 目錄滾動(dòng)時(shí)高亮顯示，便于定位；

keep_tex: yes: 保留中間生成的tex源文件，便于查錯(cuò)；

dev: "cairo_pdf": 使用cairo_pdf()生成 LATEX?編譯需要的圖片文件;

latex_engine: xelatex: TeX文件的排版引擎為 XeLATEX, 針對UTF-8編碼;

citation_package: biblatex: 文獻(xiàn)引用庫指定為biblatex, 另一個(gè)為natbib;

toc_depth: 3: 目錄提取至三級標(biāo)題;

toc_unnumbered: no: 指定目錄編號;

toc_appendix: yes: 附錄添加到目錄中.

2.4 章節(jié)結(jié)構(gòu)

如前所述, 除了index.Rmd文件， 項(xiàng)目中每個(gè).Rmd文件都作為一章，其第一行是以一個(gè)#號和空格開頭的一級標(biāo)題。

每一章可以有若干節(jié)與子節(jié)，分別用markdown的二級標(biāo)題(二個(gè)#開始)和三級標(biāo)題(三個(gè)#開始)編寫。bookdown的章、節(jié)、子節(jié)標(biāo)題單獨(dú)成一行，其后可以添加標(biāo)簽, 章節(jié)的標(biāo)簽是標(biāo)題后加空格，然后是大括號內(nèi)以#號開頭的標(biāo)簽， 如

#?引言?{#intro}##?關(guān)于bookdown?{#bookdown}

bookdown中有二個(gè)特殊的標(biāo)題：

1. 部分

內(nèi)容相近的章節(jié)可以作為一個(gè)“部分”。為此，在一個(gè)部分的第一個(gè)章節(jié)文件的章標(biāo)題前面增加一行， 以# (PART) 開頭， 以{-}結(jié)尾，例如

???#?(PART)?bookdown中的浮動(dòng)對象?{-}

2. 附錄

一本書的最后可以有附錄， 附錄的章節(jié)將顯示為A.1, B.1這樣的格式。為此， 在附錄章節(jié)的第一個(gè)文件開頭加如下的第一行標(biāo)題行：

???#?(APPENDIX)?附錄?{-}#?biblatex介紹?{#biber}

2.5 書的編譯

在index.Rmd或者_(dá)bookdown.yml中設(shè)置site: bookdown::bookdown_site后， RStudio就能識別這個(gè)項(xiàng)目是一個(gè)bookdown項(xiàng)目， 這時(shí)RStudio會(huì)有一個(gè)Build按鈕，其中有Build book快捷圖標(biāo)， 從下拉菜單中選擇一個(gè)輸出格式（包括gitbook、pdf_book、epub_book）， 就可以編譯整本書(見下圖)。

R Bookdown編譯界面.

經(jīng)build編譯生成的圖書默認(rèn)保存在_book子目錄中。

對gitbook格式(即HTML網(wǎng)頁格式)， 編譯完成后會(huì)彈出一個(gè)預(yù)覽窗口， 點(diǎn)擊“Show in new window”按鈕可以將內(nèi)容在操作系統(tǒng)默認(rèn)的網(wǎng)絡(luò)瀏覽器中打開。我們也可以用其他瀏覽器(建議使用 Google chrome 瀏覽器)打開_book子目錄中的index.html文件來查看gitbook格式的圖書。

對于pdf_book格式，如果成功編譯(#fn4 "4")， 也會(huì)彈出一個(gè)PDF預(yù)覽窗口。可以在_book子目錄中找到這個(gè)PDF文件。

對于epub_book格式，如果成功編譯，會(huì)在操作系統(tǒng)默認(rèn)的ePub軟件(如蘋果電腦的book)中打開,并在_book子目錄中找到這個(gè)ePub文件。

2.6 浮動(dòng)對象標(biāo)簽與引用匯總

浮動(dòng)對象標(biāo)簽設(shè)置引用格式

標(biāo)題	(# label)	\@ref(label)
公式	(\#eq:label)	\@ref(eq:label)
圖形	label="label"	\@ref(fig:label)
表格	label="label"	\@ref(tab:label)
定理	label="label"	\@ref(prefix:label)
文本	(ref:label)	(ref:label)
文獻(xiàn)	biblabel	@biblabel

注：

定理泛指定理類，包括定理(thm)、引理(lem)、推論(cor)、命題(prp)、設(shè)想(cnj)、定義(def)、例子(exm)、習(xí)題(exr)等, 其中括號中是引用時(shí)的前綴(prefix);

文本標(biāo)簽在單獨(dú)一行中設(shè)定，可用在表格與圖形的caption中引用，即在 fig.caption, tab.caption選項(xiàng)的設(shè)置中引用；

定理類環(huán)境標(biāo)簽前綴的漢化可在_bookdown.yml中通過language進(jìn)行，例如

language:label:fig:?"圖?"tab:?"表?"thm:?'定理'def:?'定義'exm:?'例'

往期精品(點(diǎn)擊圖片直達(dá)文字對應(yīng)教程)

機(jī)器學(xué)習(xí)

后臺(tái)回復(fù)“生信寶典福利第一波”或點(diǎn)擊閱讀原文獲取教程合集

總結(jié)

以上是生活随笔為你收集整理的R沟通｜Bookdown中文书稿写作手册（中）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。