Introduction to e-books with {bookdown}

---

Publishing an e-book

Now that we’ve seen how to create a simple HTML report using R Markdown and display it online, let’s build upon those skills and see how to publish an electronic book (“e-book”) so that it can be shared with and viewed by others. To do so, we’ll make use of the {bookdown} package, which is what Mark uses for his lab guide. You can see many other examples of different books written with {bookdown} here.

Task: If you haven’t done so already, install the {bookdown} package. Load it when done.

## install bookdown if necessary
## install.packages("bookdown")

## load bookdown
library("bookdown")

Create a new repo

Task: Navigate to GitHub and create a new public repo called book-demo. Add a README.md file and an R .gitignore file as well (you can skip a license file). CLick the green Create repository button when you’re ready.

Task: Click on the Settings button in the upper right.

Task: Click on the Pages button on the left side.

Task: Click on the None button under the Branch heading and swith it to main.

Task: Click on the / (root) button under the Branch heading and swith it to docs/.

Task: When you’re ready, click on the Save button.

Success: Your repo is now set to use GitHub Pages for displaying HTML files.

Create an RStudio project

Task: Create a new project in RStudio from the book-demo repo you just created.

Task: Create another project in RStudio but this time select the option for New Directory.

Task: From the Project Type window, select “Book project using bookdown”.

Task: Set the directory name and location to anything you’d like (eg, tmp). This will be a temporary folder/directory to hold a few files.

Task: Select bs4_book from the dropdown menu for HTML book format.

Task: Check the box for “Open in a new session” and click the Create Project button.

Task: Navigate to the temporary project/folder/directory you create above and move all of the files except the .Rproj file to the folder/directory where your book-demo project lives.

Success: You now have a template for creating and publishing an HTML e-book!

Task: Click on the Addins button at the top of your RStudio window and select “Preview Book” under “BOOKDOWN”.

Tip: You can also type bookdown:::serve_book() at the command prompt to preview your book.

Success: You can now see a preview of your book in the Viewer pane!

Editing your book

There are a few ways that you can modify the layout and content of your book. Modifying the medium (e.g., PDF, HTML) and layout of your book will require you to edit some YAML files (.yml). To add new or edit existing content, you’ll edit some Markdown files (.Rmd).

Book layout

There are two YAML files that control the medium and format of your book:

1. _output.yml
   
2. _bookdown.yml

Medium

Task: Edit _output.yml to remove the non-HTML formats and replace USERNAME with your username. Save your changes when done.

bookdown::bs4_book:
  css: style.css
  theme:
    primary: "#096B72"
  repo: https://github.com/USERNAME/book-demo

Tip: You can also change the hex color code in the primary: field to something more to your liking (see options here).

Recall that earlier we set up our GitHub repo to use the docs/ folder for serving our GitHub Pages site. We need to add a complimentary instruction to _bookdown.yml to do so.

Task: Edit _bookdown.yml to change book_filename to "book-demo" and add new line at the bottom with output_dir: "docs". Save your changes when done.

book_filename: "demo-book"
new_session: true
before_chapter_script: _common.R
delete_merged_file: true
language:
  ui:
    chapter_name: "Chapter "
output_dir: "docs"

Task: Edit your .gitignore file by commenting out the line under # pkgdown site so that Git will start tracking the docs/ folder and everything in it .

# pkgdown site
# docs/

Task: Re-build your book to the new docs/ folder by clicking the Build Book button on the Build tab in RStudio.

Task: Go ahead and commit all of your changed files and push them to GitHub.

Format

To change the actual content of your book, you can edit (or delete) the existing Markdown files and add new ones as well. The content on the landing page of your book is controlled by the index.Rmd file, which will be converted to the base of your book as an HTML file when the book is built.

Task: Open the index.Rmd file and inspect its contents.

Task: Edit the YAML section of index.Rmd to change your book’s title and author (and date if you’d like). Also un-comment the url: and change it to read url: https://USERNAME.github.io/book-demo where USERNAME is your username.

--- 
title: "My first book"
author: "Mark Scheuerell"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
url: https://mdscheuerell.github.io/book-demo
# cover-image: path to the social sharing image like images/cover.jpg
description: |
  This is a minimal example of using the bookdown package to write a book.
  The HTML output format for this example is bookdown::bs4_book,
  set in the _output.yml file.
biblio-style: apalike
csl: chicago-fullnote-bibliography.csl
---

Tip: If you have an image you’d like to use for the table of contents, you can un-comment the cover-image: line and include the path/name of your file.

Tip: If your book will have citations and references like we’ve seen previously, you can change the output style with the biblio-style and csl fields.

Book content

At this point we can actually inspect our book skeleton to see many of the different ways to control the layout and content of your book.

Task: Go ahead and make any changes you’d like to the landing page and save them when done. Re-build your book to see any changes.

Chapter ordering

By default, {bookdown} will order your chapters by the order of filenames (e.g., 01-intro.Rmd will appear before 02-cross-refs.Rmd (filenames that start with an underscore _ are skipped). If you’d like to set the order of chapters according to your own scheme, you can add an rmd_files field to the _bookdown.yml file. For example, here I move chapter 4 to come after chapter 6:

book_filename: "book-demo"
new_session: true
before_chapter_script: _common.R
delete_merged_file: true
language:
  ui:
    chapter_name: "Chapter "
output_dir: "docs"
rmd_files: [
  "index.Rmd",
  "01-intro.Rmd",
  "02-cross-refs.Rmd",
  "03-parts.Rmd",
  "05-blocks.Rmd",
  "06-share.Rmd",
  "04-citations.Rmd",
  "07-references.Rmd",
]

Tip: You can find lots of other {bookdown} options here.

Task: Commit your changes and push them to GitHub.

Viewing your document

Now that we’ve pushed our basic book report to GitHub, we should be able to view it online.

Task: Navigate back your book-demo repo on GitHub and you’ll see the docs/ folder containing the various HTML and other associated files.

Tip: Recall that GitHub cannot render HTML files in a normal repo, but you can view your book by navigating to https://USERNAME.github.io/book-demo/ where USERNAME is your GitHub username.

Success: You now have an online book that you can update by making changes in your RStudio project and pushing them to GitHub.

Tip: You can add a link to your newly rendered document by edited the main page of your repo.

Task: Click on the small gear icon in the upper right, which will bring up a window to edit some aspects of your repo.

Task: In the Website field, type or copy/paste the link to your rendered site, which should be https://USERNAME.github.io/book-demo/ where USERNAME is your GitHub username. Click on the green Save changes button when you’re done.

Success: Your repo has now been updated to include a direct link to your properly rendered HTML report.