|
bookdown是著名R包作者謝益輝開發(fā)的，支持采用Rmarkdown (R代碼可以運(yùn)行)或普通markdown編寫文檔，然后編譯成HTML, WORD, PDF, Epub等格式。樣式清新，使用簡單，值得擁有。(點(diǎn)擊閱讀原文，跳轉(zhuǎn)博客，所有外鏈可點(diǎn))
在Bookdown的官網(wǎng)，有很多免費(fèi)的用bookdown寫的R書籍，如Hadley Wickham等撰寫的《R for Data Science》，Roger D. Peng撰寫的《R Programming for Data Science》, 陳總的《液體活檢口袋書》，益輝的《R語言忍者秘笈》，《單細(xì)胞數(shù)據(jù)整體分析流程》https://hemberg-lab./scRNA.seq.course/index.html (初學(xué)單細(xì)胞分析可以完全照著這個(gè)，在學(xué)習(xí)過程中改進(jìn))。 還有很多基于Bookdown的教程，一時(shí)也想不起來，歡迎大家補(bǔ)充。我們前面轉(zhuǎn)錄組和R培訓(xùn)的教案也是用bookdown寫作的，后續(xù)再調(diào)整下格式，出一批電子書和紙質(zhì)書，有意向和需求的歡迎聯(lián)系。 下面分2步講述，自己如何構(gòu)建一個(gè)Bookdown書籍，第一部分是通過bookdown示例了解其基本功能和使用，第二部分是個(gè)人在使用過程中碰到的問題和解決方式。 基本使用安裝必須軟件Rstudio或Pandoc二選一, bookdown必須安裝。
Install Rstudio (version>1.0.0) (安裝和使用見Rstudio) Install Pandoc (version>1.17.0.2)或者參照here。如果系統(tǒng)新，可以直接使用系統(tǒng)自帶的yum或apt-get；如果沒有權(quán)限或系統(tǒng)比較老，Pandoc的安裝可以使用conda，具體配置見Conda配置，配置好運(yùn)行conda install -c conda-forge pandoc即可安裝。 In R install.packages('bookdown')
Demo示例克隆或下載https://github.com/rstudio/bookdown-demo示例文件，編譯成功后，依葫蘆畫葫蘆修改. 編譯成書運(yùn)行下載的示例中的bash _build.sh，_book目錄下就是成書. The content of _build.sh is: #!/bin/shRscript -e 'bookdown::render_book('index.Rmd', 'bookdown::gitbook')'# 生成pdf需要安裝好latex，如果不需要可以注釋掉Rscript -e 'bookdown::render_book('index.Rmd', 'bookdown::pdf_book')'
在前面的內(nèi)容運(yùn)轉(zhuǎn)起來后，再看后面的內(nèi)容。 Customize our bookdown準(zhǔn)備Rmd文件基本規(guī)則一個(gè)典型的bookdown文檔包含多個(gè)章節(jié)，每個(gè)章節(jié)在一個(gè)R Markdown文件里面 (文件的語法可以是pandoc支持的markdown語法，但后綴必須為Rmd)。 每一個(gè)章節(jié)都必須以# Chapter title開頭。后面可以跟一段概括性語句，概述本章的內(nèi)容，方便理解，同時(shí)也防止二級(jí)標(biāo)題出現(xiàn)在這一頁。默認(rèn)系統(tǒng)會(huì)按照文件名的順序合并Rmd文件。 另外章節(jié)的順序也可在_bookdown.yml文件中通過rmd_files:['file1.Rmd', 'file2.Rmd', ..]指定。 如果有index.Rmd，index.Rmd總是出現(xiàn)在第一個(gè)位置。通常index.Rmd里面也需要有一章節(jié)，如果不需要對這一章節(jié)編號(hào)的話，可以寫作# Preface {-}, 關(guān)鍵是{-}。 在第一個(gè)出現(xiàn)的Rmd文件中 (通常是index.Rmd)，可以定義Pandoc相關(guān)的YAML metadata, 比如標(biāo)題、作者、日期等 (去掉#及其后的內(nèi)容)。 ```title: 'My book'author: #可以寫多行信息，都會(huì)被當(dāng)做Author處理- 'CT'- 'CY'- 'chentong_biology@163.com'date: '`r Sys.Date()`'documentclass: article #可以為book或article# 如果需要引用參考文獻(xiàn)，則添加下面三行內(nèi)容bibliography: [database.bib] #指定存儲(chǔ)參考文獻(xiàn)的bib文件，endote或zotero都可以導(dǎo)出這種引文格式biblio-style: apalike #設(shè)定參考文獻(xiàn)顯示類型link-citations: yes``````{r setup, include=FALSE}knitr::opts_chunk$set(echo = FALSE, fig.align='center', out.width='95%', fig.pos='H')knitr::opts_chunk$set(cache = FALSE, autodep=TRUE)set.seed(0304)```~~~~~~
插入并引用圖片(外部圖片)插入圖片最好使用knitr::include_graphics，可以同時(shí)適配HTML和PDF輸出。另外當(dāng)目錄下同時(shí)存在name1.png和name1.pdf文件時(shí)，會(huì)自動(dòng)選擇在HTML展示name1.png文件，在PDF輸出中引入name1.pdf格式的文件。 圖的標(biāo)簽為fig-name(不能有下劃線)，在引用時(shí)需使用如下格式\@ref(fig:fig-name)，且fig.cap也要設(shè)置內(nèi)容。 多張圖可以同時(shí)展示，圖的名字以vector形式傳給include_graphics，需要設(shè)置out.width=1/number-pics 和 fig.show='hold'。 Insert a single pic and refer as Figure \@ref(fig:fig-name). `echo=FALSE` will hide the code block and display the output of `r` command only. These options can be set globally as indicated below.```{r fig-name, fig.cap='Markdown supported string as caption', fig.align='center', echo=FALSE}knitr::include_graphics('images/1.png')```Suppose we have 3 pictures in `images` folder with names as `Fig1_a`, `Fig1_b`, `Fig1_c`, we can refer to them using Figure \@ref(fig:fig1).```{r fig1, fig.cap='3 sub-plots.', fig.align='center', out.width=33%, fig.show='hold'}fig1 = list.files('images', pattern='Fig1_.*', full.names=T)knitr::include_graphics(fig1)```Another way of including two pics.```{r fig-name2, out.width='49%', fig.show='hold', fig.cap='Markdown supported string as caption', fig.align='center', echo=FALSE}knitr::include_graphics(c('images/1.png', 'images/2.png'))```~~~~~~~~~~~~~~~~
如果圖或表的標(biāo)題中有Markdown語法，輸出為HTML時(shí)是可以正確解析的，但是輸出為PDF時(shí)卻不可以。這時(shí)可以使用Text Reference。當(dāng)圖或表的標(biāo)題太長時(shí)，也可以使用Text Reference引用一段話作為圖和表的標(biāo)題。 Here is normal text.(ref:pic-label) This line can be referred in **fig.cap** and markdown syntax is supported for both `HTML` and `PDF` output.```{r pic-label, fig.cap='(ref:pic-label)'}knitr::include_graphics('images/1.png')```~
輸出PDF時(shí)不支持使用在線圖片，可以加一個(gè)判斷。 ```{r fig-name, fig.cap='Markdown supported string as caption', fig.align='center', echo=FALSE}if (!file.exists(cover_file <- 'cover.jpg')){="" download.file(url,="" cover_file,="" mode='wb' )}knitr::include_graphics(if="" (identical(knitr:::pandoc_to(),="" 'html'))="" url="" else="">
插入并引用表格(外部表格)外部表格的名字中必須包含tab:, 然后是表格的實(shí)際名字，格式為(\#tab:table-name); 引用時(shí)使用Table \@ref(tab:table-name)。 表格名字中不能有下劃線。 Check Table \@ref(tab:seq-sum) for detail.Table: (\#tab:seq-sum) Summary of sequencing reads 測序量總結(jié) (對于雙端測序, *\_1* 表示左端reads, *\_2* 表示右端reads) ----------------------------------------------------------------------Sample Total reads Total bases Sequence length (nt) GC content (%) Encoding -------- ------------- --------------- ---------------------- ---------------- -----------------------T8_1 37,106,941 5,566,036,721 138-150 47 Sanger / Illumina 1.9 T8_2 37,106,941 5,566,034,285 138-150 47 Sanger / Illumina 1.9 ----------------------------------------------------------------------
插入并引用表格(內(nèi)部表格)插入表格推薦使用knitr::kable，只要提供數(shù)據(jù)矩陣，用r讀取就可以了。 Check Table \@ref(tab:table-id) for detail.```{r table-id, include=FALSE}a <- as.data.frame(matrix(rnorm(20),="" nrow="4))knitr::kable(a," caption='Test table' ,="" booktabs="">
插入腳注text^[footnote] is used to get the footnote.
where `type` may be `article`, `book`, `manual`, and so on.^[The type name is case-insensitive, so it does not matter if it is `manual`, `Manual`, or `MANUAL`.]
插入引文假如我們的bib文件中內(nèi)容如下，如果我們要引用這個(gè)文章，只要寫 [@chen_m6a_2015]就可以了。 @article{chen_m6a_2015, title = {m6A {RNA} {Methylation} {Is} {Regulated} by {MicroRNAs} and {Promotes} {Reprogramming} to {Pluripotency}}, volume = {16}, issn = {1934-5909, 1875-9777}, url = {http://www./cell-stem-cell/abstract/S1934-5909(15)00017-X}, doi = {10.1016/j.stem.2015.01.016}, language = {English}, number = {3}, urldate = {2016-12-08}, journal = {Cell Stem Cell}, author = {Chen, Tong and Hao, Ya-Juan and Zhang, Ying and Li, Miao-Miao and Wang, Meng and Han, Weifang and Wu, Yongsheng and Lv, Ying and Hao, Jie and Wang, Libin and Li, Ang and Yang, Ying and Jin, Kang-Xuan and Zhao, Xu and Li, Yuhuan and Ping, Xiao-Li and Lai, Wei-Yi and Wu, Li-Gang and Jiang, Guibin and Wang, Hai-Lin and Sang, Lisi and Wang, Xiu-Jie and Yang, Yun-Gui and Zhou, Qi}, month = mar, year = {2015}, pmid = {25683224}, pages = {289--301},}
準(zhǔn)備YML配置文件_bookdown.yml配置輸入和輸出文件參數(shù)。 book_filename: '輸出文件的名字' output_dir: '輸出目錄的名字，默認(rèn)_book'language: ui: chapter_name: ''
_output.yml配置產(chǎn)生輸出文件的命令行參數(shù)。 bookdown::pdf_book: template: ehbio.tex #使用自己定制的pandoc latex模板 includes: # or only customize part latex module in_header: preamble.tex before_body: latex/before_body.tex after_body: latex/after_body.tex latex_engine: xelatex citation_package: natbib keep_tex: yes pandoc_args: --chapters toc_depth: 3 toc_unnumbered: no toc_appendix: yes quote_footer: ['\\VA{', '}{}']bookdown::epub_book: stylesheet: css/style.cssbookdown::gitbook: css: style.css split_by: section config: toc: collapse: none before: | #設(shè)置toc開頭和結(jié)尾的鏈接 其它定制不同的文件分別用于html和pdf輸出 # in _bookdown.yml rmd_files: html: ['index.Rmd', 'file2.Rmd'] latex: ['index_pdf.Rmd', 'file3.Rmd']# Different render way#!/bin/shRscript -e 'bookdown::render_book('index.Rmd', 'bookdown::gitbook')'Rscript -e 'bookdown::render_book('index_pdf.Rmd', 'bookdown::pdf_book')'
配置全局變量自適應(yīng)HTML和PDF輸出 ```{r setup, include=FALSE}library(knitr)output <- opts_knit$get('rmarkdown.pandoc.to')html="FALSElatex" =="" falseopts_chunk$set(echo="FALSE," fig.align='center' ,="" fig.show='hold' )if="" (output="='html')" {="" ="" html="TRUE}if" (output="='latex')" {="" ="" opts_chunk$set(out.width='95%' ,="" out.height='0.7\\textheight' ,="" out.extra='keepaspectratio' ,="" fig.pos='H' )="" ="" latex="TRUE}#knitr::opts_chunk$set(cache" =="" false,="" autodep="TRUE)set.seed(0304)```Below" text="" will="" only="" appear="" in="" html="" output.```{asis,="" echo="html}#" ehbio="" gene="" technology="" {-}```below="" command="" will="" only="" be="" executed="" and="" displayed="" in="" html="" output.```{r="" cover,="" eval="html," out.width='99%'>
保留生成的markdown文件 # add below lines to last Rmd file```{r, include=FALSE}file.rename(from='bookdown_file_name.md', to='bookdown_file_name.saved.md')```~~~~~~~~~~~
包含子文件 (subfile.txt) ```{r child='subfile.txt'}```~~~~~~
cahce external file ref ```{r mtime-func}mtime <- function(files){="" lapply(sys.glob(files),="" function(x)="" file.info(x)$mtime)}``````{r="" mtime-usage,="" cache="T," cache.extra="mtime(c('file1'," 'file2',="" file3))}file3=""><- paste0(dir,="" '/',="" name)data1=""><- read.table('file1')data2=""><->
預(yù)覽生成的WEB文件如果沒有安裝Rstudio，可以在生成的book目錄(有index.html的目錄)下運(yùn)行python -m SimpleHTTPServer 11521 (11521為端口號(hào)，一般選較大值避免沖突), 然后就可以在瀏覽器輸入網(wǎng)址http://server-ip:11521來訪問了。 Referenceshttps:///yihui/bookdown/get-started.html https://github.com/rstudio/bookdown/tree/master/inst/examples http:///questions/25236850/how-to-set-different-global-options-in-knitr-and-rstudio-for-word-and-html Multiple output with different configs https://github.com/yihui/knitr/issues/1145 Multiple output with different configs https://github.com/yihui/knitr/issues/114://github.com/rstudio/rmarkdown/issues/614 Citation style http://rmarkdown./authoring_bibliographies_and_citations.html Save markdown http:///questions/19989325/knit-rmd-file-to-md-and-save-the-md-file-one-level-up-with-a-different-name PDF online pic http://www./zh/post/bookdown-tips/
|
