Happy summer from the R Markdown family! We are proud to share that bookdown (https://pkgs.rstudio.com/bookdown/) version 0.23 is on CRAN. bookdown is a package that helps you write books and long-form articles/reports, knitting together content from single or multiple R Markdown files as input.
You can install bookdown from CRAN with:
install.packages("bookdown") # or if the v0.23 binary package for your platform is not ready yet, try # install.packages("bookdown", type = "source")
In this post, we’ll share some highlights from the latest release, but you might want to look at the release notes for the full details.
New reference site
New HTML book format based on Bootstrap 4
This release includes a new HTML book output format called
bs4_book(), contributed by Hadley Wickham and Maëlle Salmon. Based on Bootstrap 4,
bs4_book() includes carefully crafted features to provide a clean reading experience whether you are on a phone, tablet, or desktop. On a full-size screen, the layout includes three columns of content so readers can quickly see all chapters on the left, the current chapter in the middle, and sections within the the current chapter on the right. As an example, you can read a book using this format here: https://mastering-shiny.org
Learn more about the unique features of this output format in the book “bookdown: Authoring Books and Technical Documents with R Markdown”: https://bookdown.org/yihui/bookdown/html.html#bs4-book
Our package reference site also has a documentation page for
New project template
To make it easier for users to start new bookdown book projects, we added two functions to create new bookdown projects:
If you use RStudio, you can also access these two templates interactively from the New Project Wizard using File > New Project > New Directory.
To help you build a new bookdown project faster, we also added some helpful pointers inside the template book itself to get you writing your book more quickly. You can think of the boilerplate content as a cheat sheet for the most useful features of bookdown so that you can easily access them if you are offline, or if you simply don’t have the docs right in front of you as you work. For example, you’ll find:
- How to use parts, chapters, sections, and subsections to organize your content.
- How to use cross-references, including to captioned figures and tables.
- How to add footnotes and citations.
- How to use custom blocks for equations, theorems and proofs, and callouts.
- How to prepare your book to be shared.
We also included a
_common.R script in the template project. By using
before_chapter_script in your
bookdown.yml file, this script is run at the beginning of each chapter:
Importantly, this works with
new_session: true since bookdown v0.18 (see news).
We hope these templates make it easier to start a book with bookdown. As always, with any template, you can also just cut out the template contents and start customizing and writing straight away too - the overall file structure and YAML configurations will still provide a useful skeleton for your next book.
Create and customize 404 pages
For all HTML book formats, bookdown now creates a default
404.html page in your output directory using simple content (a header, and a body of 2 paragraphs). Learn more about 404 pages and how to create a custom page in our online docs: https://bookdown.org/yihui/bookdown/features-for-html-publishing.html#html-404
For all HTML books, we now support an alternative search engine called
fuse.js, which provides a better user experience and more nuanced search capabilities than
lunr.js. To enable
fuse.js for gitbook, set the search engine to be
output: bookdown::gitbook: config: search: engine: fuse # lunr is the default options: null # can override, see: https://fusejs.io/api/options.html
This is the only search engine supported by
bs4_book() and, depending on user feedback, we may set
fuse to be the default search engine in
gitbook() as well. We will appreciate your testing and feedback!
In other news
render_book()function has a new default behavior, and will now search for an
index.Rmdfile in the current working directory. Previously, this function required users to specify the name of this file. Now,
render_book()is equivalent to
render_book()function can also now be used to render your book in a subdirectory of your project:
We updated the jQuery library to v3.x, which is now imported from the R package jquerylib.
Last but not least, we are continually working to update our documentation. For example, we have new instructions to help you deploy a bookdown book using Netlify Drop: https://bookdown.org/yihui/bookdown/netlify-drop.html
A big thanks to the 32 contributors who helped with this release by discussing problems, proposing features, and contributing code:
@aimundo, @apreshill, @AstrickHarren, @avraam-1997, @briandk, @cderv, @CrumpLab, @danawanzer, @DavidLukeThiessen, @dchiu911, @debruine, @edzer, @GuillaumeBiessy, @hhmacedo, @hnguyen19, @johnbaums, @jtbayly, @judgelord, @LDSamson, @maelle, @malcolmbarrett, @N0rbert, @pschloss, @rgaiacs, @robjhyndman, @salim-b, @shirdekel, @ShixiangWang, @Shuliyey, @strimmerlab, @thisisnic, and @thosgood.