1st Edition

bookdown Authoring Books and Technical Documents with R Markdown

By Yihui Xie Copyright 2017
    138 Pages
    by Chapman & Hall

    138 Pages
    by Chapman & Hall

    bookdown: Authoring Books and Technical Documents with R Markdown presents a much easier way to write books and technical publications than traditional tools such as LaTeX and Word. The bookdown package inherits the simplicity of syntax and flexibility for data analysis from R Markdown, and extends R Markdown for technical writing, so that you can make better use of document elements such as figures, tables, equations, theorems, citations, and references. Similar to LaTeX, you can number and cross-reference these elements with bookdown. Your document can even include live examples so readers can interact with them while reading the book. The book can be rendered to multiple output formats, including LaTeX/PDF, HTML, EPUB, and Word, thus making it easy to put your documents online. The style and theme of these output formats can be customized.

    We used books and R primarily for examples in this book, but bookdown is not only for books or R. Most features introduced in this book also apply to other types of publications: journal papers, reports, dissertations, course handouts, study notes, and even novels. You do not have to use R, either. Other choices of computing languages include Python, C, C++, SQL, Bash, Stan, JavaScript, and so on, although R is best supported. You can also leave out computing, for example, to write a fiction. This book itself is an example of publishing with bookdown and R Markdown, and its source is fully available on GitHub.

    List of Tables

    List of Figures


    About the Author



    Get started


    Two rendering approaches

    Some tips


    Markdown syntax

    Inline formatting

    Block-level elements

    Math expressions

    Markdown extensions by bookdown

    Number and reference equations

    Theorems and proofs

    Special headers
    Text references

    R code




    Custom blocks



    HTML widgets

    Web pages and Shiny apps

    Output Formats


    GitBook style

    Bootstrap style

    Tufte style





    A single document


    YAML options






    Build the book

    Preview a chapter

    Serve the book

    RStudio IDE



    RStudio Connect




    Software Tools

    R and R packages



    Software Usage 103


    R Markdown

    FAQ 109

    Bibliography 111

    Index 113


    Yihui Xie is a software engineer at RStudio. He is the author of several R packages, and interested in statistical computing, data visualization, and web technologies. He founded the largest online community for statistics "Capital of Statistics" in China in 2006. After publishing a few journal papers, a PhD thesis, and the book Dynamic Documents with R and knitr, the frustration with LaTeX eventually led to the creation of bookdown.

    If you have written about statistics and included examples that are implemented in a programming language, you have struggled with the challenge of weaving together these two distinct forms of communication. Donald Knuth laid out a model of "literate programming" (1992) that prioritizes the clarity of computer code by embedding snippets of code within explanatory text. A new tool for authoring large-scale dynamic documents in this paradigm is the bookdown package, described by a book of the same name, and it stands as the most comprehensive and extensible tool available for R users... R Markdown...had limitations as well. There was no method to cross-reference figures in one chapter from another chapter of the book. The figures were not numbered successively. These problems, and many others, were solved by the release of the bookdown package...Xie has revolutionized the publishing of statistical reports using the knitr and rmarkdown packages and this is surely the next step in that revolution. His idea of books being versions instead of editions is ground-breaking. I look forward to the continual improvements to this bookdown package and this book in the years to come."~The American Statistician

    There could be a lot of interesting and unexpected ways that bookdown could be used to generate content. For example, automated software tests for clinical data analysis programs can be scheduled to run overnight and used knitr to create PDFs to show to auditors. The issue is that hundreds of files could be created. Bookdown could generate a much more organized and cross-referenced package to show to regulators during audits. ~ Max Kuhn

    I definitely recommend publication, and as quickly as possible. People are waiting for this. The R/bookdown/knitr system is better than GitBook for scientific work with code and formulas, especially if combined with R Studio. ~ Jan de Leeuw, UCLA

    I would whole-heartedly recommend this book for publication. I think the ability to render long documents in a variety of formats, with text intermingled with code, will only grow in importance in future years. This book and associated package are clearly a major step towards being able to achieve this. The book was very well written, and notwithstanding the few suggestions I had for improvements, I think there is little modification that needs to be done before publication. I am sure it will prove interesting and useful to many readers. ~ Michael Grayling, U. of Cambridge

    Bookdown is hugely useful for long-form documents: books, course notes, theses/dissertations. And I expect it to be widely adopted for those purposes…The book is quite nicely written: clear and concise. ~ Karl Broman, U. of Wisconsin

    The audience would absolutely include R users who are comfortable with Word but not LaTeX (for example, in my department, most of the graduate students have used R Markdown, but only a couple know LaTeX)…One huge advantage of bookdown is that you can have a current version of a book online as you develop it. ~ Brooke Anderson, Colorado State U.

    Simply amazing! Six hours, basic R and R Markdown knowledge, and I created a book using bookdown. ~ Lars Schoebitz