New reference site

Joining its R Markdown siblings like blogdown, distill, and rmarkdown, bookdown has also gained a reference site, built with pkgdown. There, you’ll find:

1. 📖 A reference section,

2. 🖼️ An example gallery, plus

3. 📣 The latest news.

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

Figure 1: Screenshot of a bs4_book home page.

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 bs4_book(): https://pkgs.rstudio.com/bookdown/reference/bs4_book.html

New project template

To make it easier for users to start new bookdown book projects, we added two functions to create new bookdown projects:

• create_gitbook(), and
• create_bs4_book().

If you use RStudio, you can also access these two templates interactively from the New Project Wizard using File > New Project > New Directory.

Figure 2: Screenshot of the RStudio Project Wizard for creating a new bookdown project.

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:

1. How to use parts, chapters, sections, and subsections to organize your content.
2. How to use cross-references, including to captioned figures and tables.
3. How to add footnotes and citations.
4. How to use custom blocks for equations, theorems and proofs, and callouts.
5. 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:

before_chapter_script: _common.R

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

Improved search

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 fuse in _output.yml:

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

• The render_book() function has a new default behavior, and will now search for an index.Rmd file 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("index.Rmd").

• The render_book() function can also now be used to render your book in a subdirectory of your project:

  render_book("book_in_a_folder")

• 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

Acknowledgements

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.