|
bookdown
是著名R包作者谢益辉开发的,支持采用Rmarkdown
(R代码可以运行)或普通markdown
编写文档,然后编译成HTML
, WORD
, PDF
, Epub
等格式。样式清新,使用简单,值得拥有。(点击阅读原文,跳转博客,所有外链可点)
在Bookdown的官网,有很多免费的用bookdown
写的R书籍,如Hadley
Wickham等撰写的《R for Data Science》,Roger D. Peng撰写的《R Programming for Data
Science》,
陈总的《液体活检口袋书》,益辉的《R语言忍者秘笈》,《单细胞数据整体分析流程》https://hemberg-lab.github.io/scRNA.seq.course/index.html
(初学单细胞分析可以完全照着这个,在学习过程中改进,我们也做了部分翻译Hemberg-lab单细胞转录组数据分析(一))。
还有很多基于Bookdown的教程,一时也想不起来,欢迎大家补充。我们前面转录组和R培训的教案也是用bookdown写作的,后续再调整下格式,出一批电子书和纸质书,有意向和需求的欢迎联系。
下面分2步讲述,自己如何构建一个Bookdown书籍,第一部分是通过bookdown示例了解其基本功能和使用,第二部分是个人在使用过程中碰到的问题和解决方式。
Rstudio
或Pandoc
二选一, bookdown
必须安装。
Install Rstudio (version>1.0.0)
(安装和使用见Rstudio)
Install Pandoc (version>1.17.0.2)
或者参照here。如果系统新,可以直接使用系统自带的yum
或apt-get
;如果没有权限或系统比较老,Pandoc的安装可以使用conda,具体配置见Conda配置,配置好运行conda install -c conda-forge pandoc
即可安装。
In R install.packages("bookdown")
克隆或下载https://github.com/rstudio/bookdown-demo示例文件,编译成功后,依葫芦画葫芦修改.
运行下载的示例中的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')"
在前面的内容运转起来后,再看后面的内容。
Rmd
文件一个典型的bookdown
文档包含多个章节,每个章节在一个R Markdown
文件里面 (文件的语法可以是pandoc
支持的markdown
语法,但后缀必须为Rmd
)。
每一个章节都必须以# Chapter title
开头。后面可以跟一段概括性语句,概述本章的内容,方便理解,同时也防止二级标题出现在这一页。默认系统会按照文件名的顺序合并Rmd
文件。
另外章节的顺序也可在_bookdown.yml
文件中通过rmd_files:["file1.Rmd", "file2.Rmd", ..]
指定。
如果有index.Rmd
,index.Rmd
总是出现在第一个位置。通常index.Rmd里面也需要有一章节,如果不需要对这一章节编号的话,可以写作# Preface {-}
, 关键是{-}
。
在第一个出现的Rmd
文件中 (通常是index.Rmd
),可以定义Pandoc
相关的YAML metadata
, 比如标题、作者、日期等 (去掉#及其后的内容)。
``
插入图片最好使用knitr::include_graphics
,可以同时适配HTML和PDF输出。另外当目录下同时存在name1.png
和name1.pdf
文件时,会自动选择在HTML展示name1.png
文件,在PDF
输出中引入name1.pdf
格式的文件。
图的标签为fig-name
(不能有下划线),在引用时需使用如下格式\@ref(fig:fig-name)
,且fig.cap
也要设置内容。
多张图可以同时展示,图的名字以vector形式传给include_graphics
,需要设置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"))```~~~~~~~~~~~~~~~~
如果图或表的标题中有Markdown语法,输出为HTML时是可以正确解析的,但是输出为PDF时却不可以。这时可以使用Text Reference
。当图或表的标题太长时,也可以使用Text Reference
引用一段话作为图和表的标题。
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时不支持使用在线图片,可以加一个判断。
```{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 cover_file)```
外部表格的名字中必须包含tab:
, 然后是表格的实际名字,格式为(\#tab:table-name)
; 引用时使用Table \@ref(tab:table-name)
。表格名字中不能有下划线。
Check Table \@ref(tab:seq-sum) for detail.Table: (\#tab:seq-sum) Summary of sequencing reads 测序量总结 (对于双端测序, *\_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 ----------------------------------------------------------------------
插入表格推荐使用knitr::kable
,只要提供数据矩阵,用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=TRUE)```~
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
文件中内容如下,如果我们要引用这个文章,只要写 [@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.com/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},}
配置输入和输出文件参数。
book_filename: "输出文件的名字"output_dir: "输出目录的名字,默认_book"language: ui: chapter_name: ""
配置产生输出文件的命令行参数。
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: p config: toc: collapse: none before: | #设置toc开头和结尾的链接 <li><a href="http://www.ehbio.com"><img src="ehbio_logo.png" width="100%"></a></li> after: | <li><a href="mailto:ct@ehbio.com" target="blank">ct@ehbio.com</a></li> download: [pdf, epub, mobi] edit: https://github.com/rstudio/bookdown/edit/master/inst/examples/%s sharing: twitter: no github: no facebook: no
不同的文件分别用于html
和pdf
输出
"index.Rmd"
配置全局变量自适应HTML
和PDF
输出
``
保留生成的markdown文件
``
包含子文件 (subfile.txt)
``
cahce external file ref
``
如果没有安装Rstudio,可以在生成的book目录(有index.html
的目录)下运行python -m SimpleHTTPServer 11521
(11521为端口号,一般选较大值避免冲突), 然后就可以在浏览器输入网址http://server-ip:11521
来访问了。
https://bookdown.org/yihui/bookdown/get-started.html
https://github.com/rstudio/bookdown/tree/master/inst/examples
http://stackoverflow.com/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.rstudio.com/authoring_bibliographies_and_citations.html
Save markdown http://stackoverflow.com/questions/19989325/knit-rmd-file-to-md-and-save-the-md-file-one-level-up-with-a-different-name
PDF online pic http://www.pzhao.org/zh/post/bookdown-tips/
Archiver|手机版|科学网 ( 京ICP备07017567号-12 )
GMT+8, 2024-12-23 17:11
Powered by ScienceNet.cn
Copyright © 2007- 中国科学报社