Chapter 4 bookdown

Bookdown is an extra package for R Markdown that is particularly useful for long documents.

  • In HTML format, produces a full website of interlinked pages, one page per chapter
  • Other HTML features: contents bar, search, colour schemes, font size adjustment, etc
  • Adds LaTeX-like theorem/definition/proof environments
“Plain” R Markdown R Markdown with Bookdown
Good for short documents, single HTML page Good for long documents, multi-page website
PDF or accessible HTML PDF or accessible HTML
LaTeX equations LaTeX equations
No theorem environments Theorem environments

We can reference chunks (tables and figures), sections, and equations in bookdown output formats

  • bookdown extends Pandoc
  • Examples of bookdown formats are bookdown::pdf_document2 or bookdown::html_document2.
  • Refer to
    • Figure \@ref(fig:chunk-name)
    • Table \@ref(tab:chunk-name)
    • Section \@ref(my-section)

Examples of chunks:

```{r chunk-name}
plot(cars)
``` 
See Figure \@ref{fig:chunk-name}.


# Section {#my-section}

Refer to Section \@ref{my-section}

Create a bookdown project:

File → New Project → New Directory → Book project using bookdown → Create Project

Bookdown cookbook: https://rstudio4edu.github.io/rstudio4edu-book/book-dress.html

Deployment and Hosting bookdown on GitHub Pages

Ref: Authoring Books with R Markdown, https://bookdown.org/yihui/bookdown/github.html

  1. Initialize your local git repository and link to the remote GitHub repo.

    See instructions HERE.

  2. Go to your _bookdown.yml file and add output_dir: "docs" on a line by itself

  3. Serve/preview your book locally

    Now the website output files should be in /docs.

    Create a .nojekyll in /docs that tells GitHub that your website is not to be built via Jekyll.

    touch .nojekyll

  4. Push your changes to GitHub remote

  5. Configure publishing source for GH pages as main branch /docs folder

    Go to your GH remote repo, click Settings → click Pages in the left column → under GitHub Pages, change the “Source” to be “main branch /docs folder”.

    GH pages Source