Announcing bookdown v0.23

[This article was first published on RStudio Blog, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

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.

Latest release
Last bookdown release 0.23 cran badge

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

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

Home page for a bs4_book() showing the layout with a table of contents on the left, main chapter content in the center, and an 'on this page' sidebar on the right.

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.

Screenshot showing the fields and dropdown selection menu in the RStudio New Project Wizard.

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

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.

To leave a comment for the author, please follow the link and comment on their blog: RStudio Blog.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)