Authoring Books and Technical Documents with R Markdown

Output formats and utilities for authoring books and technical documents with R Markdown.


Build Status CRAN downloads

bookdown logo

A open-source (GPL-3) R package to facilitate writing books and long-form articles/reports with R Markdown. Features include:

  • Generate printer-ready books and ebooks from R Markdown documents
  • A markup language easier to learn than LaTeX, and to write elements such as section headers, lists, quotes, figures, tables, and citations
  • Multiple choices of output formats: PDF, LaTeX, HTML, EPUB, and Word.
  • Possibility of including dynamic graphics and interactive applications (HTML widgets and Shiny apps)
  • Support for languages other than R, including C/C++, Python, and SQL, etc.
  • LaTeX equations, theorems, and proofs work for all output formats
  • Can be published to GitHub, bookdown.org, and any web servers
  • Integrated with the RStudio IDE
  • One-click publishing to https://bookdown.org

Full documentation at https://bookdown.org/yihui/bookdown, and see "Get Started" at https://bookdown.org to know how to get started with writing a book. You are welcome to send us feedback using Github issues or ask questions on StackOverflow with the bookdown tag.

News

CHANGES IN bookdown VERSION 0.6

NEW FEATURES

  • Added an argument config_file to render_book() so that one can specify a custom config file; the default config file is still _bookdown.yml (thanks, @stephlocke, #465).

  • Added a global option bookdown.preview.cutoff (defaults to 30) for the preview mode render_book(preview = TRUE): when the number of lines of a chapter is smaller or equal to this number, the full chapter is included in the preview; otherwise, only the section titles are extracted from the chapter for preview.

BUG FIXES

  • Various compatibility issues with Pandoc 2.0 (thanks, @maxheld83 #479, @jerrythomas #481, @Hantabaru #483, @dataopt #504, and #478).

  • split_by = 'section' does not work completely correctly for the HTML output formats like gitbook (thanks, @dataopt, @502).

CHANGES IN bookdown VERSION 0.5

NEW FEATURES

  • Added support for two more environments: Exercises and Solutions (thanks, @dshuman1, #423).

  • If the Rmd file merged from all chapters exists and you are sure it can be safely deleted, you can set an option delete_merged_file to true in _bookdown.yml (thanks, @dmenne, #442).

BUG FIXES

  • The book cannot be properly rendered when the option book_filename in _bookdown.yml contains a dot (thanks, @pinusm, #410).

  • Proof and Remark blocks do not work well for EPUB output (thanks, @mamaciasq, #443).

  • When split_by = 'section' for the gitbook output format, navigation buttons are missing on the page before the appendix (thanks, @dataopt, #409).

MINOR CHANGES

  • The label prefix for Example blocks was changed from ex: to exm:.

CHANGES IN bookdown VERSION 0.4

NEW FEATURES

  • Added special syntax for unnumbered part headers: # (PART\*). Numbered parts should be written after # (PART) as before (thanks, @brooksambrose, http://stackoverflow.com/q/43688902/559676).

  • The gitbook output format also supports abstract in YAML now (thanks, @maxheld83, #311).

  • For the gitbook output format, the downloads option in config supports rmd now (e.g. download: ["pdf", "epub", "rmd"]) if the edit link has been specified and is a link to Github (thanks, @coatless, #330).

  • You can set the global R option bookdown.post.latex via options() to be a function to post-process the LaTeX output of the pdf_book format; see ?bookdown::pdf_book for details (thanks, @nicksolomon, #373).

BUG FIXES

  • The HTML output file is not moved to the output directory when split_by = 'none' in bookdown::gitbook or bookdown::html_book (http://stackoverflow.com/q/40976073/559676).

  • The YAML option includes: before_body works correctly for gitbook output now (thanks, @benmarwick, #267).

  • Theorem environments are not defined for LaTeX output unless a theorem block is present (thanks, @JeffreyRacine, #291).

  • For remark and proof blocks, the chunk option name did not work correctly for non-LaTeX output (thanks, @ugroempi, #347).

  • Some text references do not work for HTML and Word output (thanks, @ugroempi, #363).

  • The option chapter_name in _bookdown.yml does not work when it is specified as a function (thanks, @tzerk, 0c05c3828be).

  • External assets such as fonts/css files should never be wiped when rendering a book to HTML (thanks, @nicholaelaw, #398).

MINOR CHANGES

  • The daemon argument was removed from serve_book(), but you can still pass it to servr::httw() via the ... argument.

  • Added a small space (padding) to the right of section numbers in gitbook output, so that the section numbers are better separated from the titles (thanks, @aronatkins, #367).

CHANGES IN bookdown VERSION 0.3

NEW FEATURES

  • Added a Github button in the group of sharing buttons on the toolbar. By default, this button is not displayed. You have to set github: yes under sharing in the gitbook configurations (https://bookdown.org/yihui/bookdown/html.html) and specify your Github repo using the top-level option github-repo in the YAML metadata of index.Rmd, e.g. github-repo: rstudio/bookdown.

  • The appendix heading will be preserved in bookdown::html_document2 output, e.g. if you have # (APPENDIX) Appendix {-} in your document, you will see the heading Appendix in the output. Previously it was removed.

  • Parts in HTML output are also be numbered using roman numerals like LaTeX/PDF output.

BUG FIXES

  • Wrong part titles were inserted to the table of contents of PDF output (thanks, @florisvdh, #243).

  • Cross-references for appendices in html_document2 output did not work (thanks, @florisvdh, #245).

  • Part titles were not correctly processed when they were longer than 20 characters in PDF output (thanks, @florisvdh, #246).

CHANGES IN bookdown VERSION 0.2

NEW FEATURES

  • Added arguemnts toc_unnumberred, toc_appendix, toc_bib, and quote_footer to pdf_book().

  • Added support for cross-referencing equations in multi-page HTML output and EPUB; see https://bookdown.org/yihui/bookdown/ for the syntax (thanks, @deleeuw, #85).

  • Rmd files can live in subdirectories if you use the Merge-and-Knit approach (the default), and they will be found if the configuration option rmd_subdir is true in _bookdown.yml (thanks, @leobuchignani, #205).

MAJOR CHANGES

  • The force_knit argument of render_book() was removed (to avoid confusion when switching output formats).

MINOR CHANGES

  • The merged R Markdown file will not be deleted if rendering failed so you can debug with this file (http://stackoverflow.com/q/38883222/559676).

  • The configurations edit: text and chapter_name have been moved from the top-level options to the sub-options of language: ui in _bookdown.yml. See https://bookdown.org/yihui/bookdown/internationalization.html

BUG FIXES

  • Figures are not correctly numbered in Word output using the bookdown::word_document2() format (thanks, @byzheng, #158).

  • For the "Knit and Merge" approach (new_session: yes in _bookdown.yml), certain parts like figures may not show up when switching from one output format to another (e.g. from HTML to LaTeX).

  • The rmd_files option in _bookdown.yml does not work when it is a list of html and latex options (thanks, @ismayc, #177).

  • Math expressions does not appear in the table of contents when the output format is gitbook (thanks, @philomonk, #204).

  • Footnotes of multiple paragraphs are not displayed on the current page (thanks, @axitdn, #234).

  • The output format pdf_document2() also works with articles now when an R Markdown document contains bookdown-specific headers, such as parts or appendix headers (http://stackoverflow.com/q/40529798/559676).

CHANGES IN bookdown VERSION 0.1

NEW FEATURES

  • Initial CRAN release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("bookdown")

0.7 by Yihui Xie, 2 months ago


https://github.com/rstudio/bookdown


Report a bug at https://github.com/rstudio/bookdown/issues


Browse source code at https://github.com/cran/bookdown


Authors: Yihui Xie [aut, cre] (<https://orcid.org/0000-0003-0645-5666>), JJ Allaire [ctb], Albert Kim [ctb], Alessandro Samuel-Rosa [ctb], Andrzej Oles [ctb], Bastiaan Quast [ctb], Ben Marwick [ctb], Chester Ismay [ctb], Christophe Dervieux [ctb], Clifton Franklund [ctb], Daniel Emaasit [ctb], David Shuman [ctb], Dean Attali [ctb], Drew Tyre [ctb], Frans van Dunne [ctb], Hadley Wickham [ctb], Jeff Allen [ctb], Jennifer Bryan [ctb], Jonathan McPhers [ctb], Junwen Huang [ctb], Kevin Cheung [ctb], Kevin Ushey [ctb], Kim Seonghyun [ctb], Kirill Muller [ctb], Luciano Selzer [ctb], Matthew Lincoln [ctb], Maximilian Held [ctb], Michael Sachs [ctb], Michal Bojanowski [ctb], Peter Hickey [ctb], Sahir Bhatnagar [ctb], Steve Simpson [ctb], Vincent Fulco [ctb], Yixuan Qiu [ctb], Zhuoer Dong [ctb], RStudio Inc [cph], Bartek Szopka [ctb] (The jQuery Highlight plugin), jQuery Foundation [cph] (jQuery library), jQuery contributors [ctb, cph] (jQuery library; authors listed in inst/resources/AUTHORS), MathQuill contributors [ctb] (The MathQuill library; authors listed in inst/resources/AUTHORS), FriendCode Inc [cph, ctb] (The gitbook style, with modifications)


Documentation:   PDF Manual  


GPL-3 license


Imports htmltools, knitr, rmarkdown, xfun, tinytex, yaml

Suggests htmlwidgets, rstudioapi, miniUI, rsconnect, servr, shiny, testit, tufte, webshot

System requirements: Pandoc (>= 1.17.2)


Imported by blogdown, bookdownplus, komadown, pubh, rmdformats.

Suggested by SimCorMultRes, SimCorrMix, SimRepeat, febr, flippant, prepplot, shadow.


See at CRAN