Yihui Xie

bookdown: Authoring Books and

Technical Documents with R
Markdown
 To Shao Yong (邵雍),
for sharing a secret joy with simple words;

月到天⼼处，风来⽔面时。
⼀般清意味，料得少⼈知。

and

To Hongzhi Zhengjue (宏智禅师),

for sharing the peace of an ending life with simple words.

梦幻空华，六⼗七年；
白鸟淹没，秋⽔连天。
Contents

List of Tables vii

List of Figures ix

Preface xi

About the Author xix

1 Introduction 1
1.1 Motivation . . . . . . . . . . . . . . . . . . . . . 2
1.2 Get started . . . . . . . . . . . . . . . . . . . . . 3
1.3 Usage . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Two rendering approaches . . . . . . . . . . . . . 8
1.5 Some tips . . . . . . . . . . . . . . . . . . . . . . 9

2 Components 11
2.1 Markdown syntax . . . . . . . . . . . . . . . . . 11
2.1.1 Inline formatting . . . . . . . . . . . . . . 11
2.1.2 Block-level elements . . . . . . . . . . . . 12
2.1.3 Math expressions . . . . . . . . . . . . . . 14
2.2 Markdown extensions by bookdown . . . . . . . . 15
2.2.1 Number and reference equations . . . . . . 15
2.2.2 Theorems and proofs . . . . . . . . . . . . 18
2.2.3 Special headers . . . . . . . . . . . . . . . 25
2.2.4 Text references . . . . . . . . . . . . . . . 26
2.3 R code . . . . . . . . . . . . . . . . . . . . . . . 27
2.4 Figures . . . . . . . . . . . . . . . . . . . . . . . 28
2.5 Tables . . . . . . . . . . . . . . . . . . . . . . . 33
2.6 Cross-references . . . . . . . . . . . . . . . . . . 38
2.7 Custom blocks . . . . . . . . . . . . . . . . . . . 39

iii
iv Contents

2.8 Citations . . . . . . . . . . . . . . . . . . . . . . 39
2.9 Index . . . . . . . . . . . . . . . . . . . . . . . . 43
2.10 HTML widgets . . . . . . . . . . . . . . . . . . . 44
2.11 Web pages and Shiny apps . . . . . . . . . . . . . 47

3 Output Formats 49
3.1 HTML . . . . . . . . . . . . . . . . . . . . . . . 50
3.1.1 GitBook style . . . . . . . . . . . . . . . . 50
3.1.2 Three-column Bootstrap style . . . . . . . . 59
3.1.3 The default Bootstrap style . . . . . . . . . 68
3.1.4 Tufte style . . . . . . . . . . . . . . . . . . 72
3.2 LaTeX/PDF . . . . . . . . . . . . . . . . . . . . . 73
3.3 E-Books . . . . . . . . . . . . . . . . . . . . . . 75
3.3.1 EPUB . . . . . . . . . . . . . . . . . . . . 75
3.3.2 MOBI . . . . . . . . . . . . . . . . . . . . 76
3.4 A single document . . . . . . . . . . . . . . . . . 76

4 Customization 79
4.1 YAML options . . . . . . . . . . . . . . . . . . . 79
4.2 Theming . . . . . . . . . . . . . . . . . . . . . . 82
4.3 Templates . . . . . . . . . . . . . . . . . . . . . 84
4.4 Configuration . . . . . . . . . . . . . . . . . . . 86
4.5 Internationalization . . . . . . . . . . . . . . . . 87

5 Editing 91
5.1 Build the book . . . . . . . . . . . . . . . . . . . 91
5.2 Preview a chapter . . . . . . . . . . . . . . . . . . 93
5.3 Serve the book . . . . . . . . . . . . . . . . . . . 93
5.4 RStudio IDE . . . . . . . . . . . . . . . . . . . . 95
5.5 Collaboration . . . . . . . . . . . . . . . . . . . . 98

6 Publishing 101
6.1 RStudio Connect . . . . . . . . . . . . . . . . . . 101
6.2 Netlify Drop . . . . . . . . . . . . . . . . . . . . 102
6.2.1 The build-and-deploy pipeline sequence . . . 102
6.2.2 Before you begin . . . . . . . . . . . . . . 103
6.2.3 Build your book . . . . . . . . . . . . . . . 103
6.2.4 Deploy your site . . . . . . . . . . . . . . . 103
Contents v

6.2.5 Optional: Update your site . . . . . . . . . . . 104

6.2.6 Optional: change the default subdomain . . . . . 104
6.2.7 Drawbacks and alternatives . . . . . . . . . 105
6.3 GitHub . . . . . . . . . . . . . . . . . . . . . . . 105
6.4 Features for HTML publishing . . . . . . . . . . . 110
6.4.1 HTML 404 pages . . . . . . . . . . . . . . 110
6.4.2 Metadata for sharing . . . . . . . . . . . . 112
6.5 Publishers . . . . . . . . . . . . . . . . . . . . . 112

Appendix 117

A Software Tools 117

A.1 R and R packages . . . . . . . . . . . . . . . . . . 117
A.2 Pandoc . . . . . . . . . . . . . . . . . . . . . . . 118
A.3 LaTeX . . . . . . . . . . . . . . . . . . . . . . . 119

B Software Usage 121

B.1 knitr . . . . . . . . . . . . . . . . . . . . . . . . 121
B.2 R Markdown . . . . . . . . . . . . . . . . . . . . 123

C FAQ 127

Bibliography 129

Index 131