MG Bookdown Guide

Matthew R. Gemmell

2025-06-11

Chapter 1 MG Bookdown Guide

This is a quick and dirty guide on how I use bookdown. It is primarily for my use but if someone else finds it I hope it will also proof useful. Additionally, this was made with R Bookdown.

Another useful resource is: https://rstudio4edu.github.io/rstudio4edu-book/intro-bookdown.html

1.1 Intro

R bookdown uses Rmarkdown. First learn some Rmarkdown then learn bookdown. Some useful links are below.

• R bookdown website: https://bookdown.org/
• R bookdown book: https://bookdown.org/yihui/bookdown/
• Cheatsheets to find r markdown cheatsheet: https://rstudio.com/resources/cheatsheets/
• Minimal bookdown template: https://github.com/rstudio/bookdown-demo

I generally write and do everything in RStudio.

F7 to spell check in rstudio

1.2 Create bookdown html

Set working directory to directory with all the r markdowns.

Change name to the file name that starts with 01 or the index file if you have it.

bookdown::render_book("01-XX.Rmd", "bookdown::gitbook")

HTMLS found in "_book" directory Need to run render_book command to update any changes

Easiest way I find is to have 1 page per chapter File names need to start with a number to show order 01-, 02-, 03- etc

1.3 Libraries

To use all the contents of this guide you will need to have a few R packages installed. FOr convenience all the install commands are below:

install.packages("bookdown")
install.packages("webexercises")
install.packages("tippy")
#Reticulate to allow use of python in knitr
install.packages("reticulate")
#Icons, below code also included in that section in this guide
install.packages("remotes")
remotes::install_github("mitchelloharawild/icons")
#Download icon sets
icons::download_fontawesome()
icons::download_ionicons()
icons::download_bioicons()

1.4 Add image

To add an image you can use the following HTML code:

<center>
![](figures/NEOF.png){style="width:200px"}
</center>

HTML code with more options:

<center>
![](figures/NEOF.png){style="width:200px; border-radius:15px; border:5px solid #333333; background:null"}
</center>

• : set st the image to be aligned to the centre of the page.
• width: Sets the width, the maximum width of the page of my bookdowns is 1000px.
  • Use 200px for 20%, 300px for 30% etc
  • Useful to do this way so images don't become tiny on a mobile phone.
  • If the width of the page is smaller than the set width it will interactively set the image to 100%
• border-radius: Adds curved corners, good for images with cornered background. 15px is a good default but may need to be increased/decreased depending on your image.
• border: Adds a border around the image. Good for images with background.
• background-color: Set to null for none, can set to white for a white background

Optionally you can do it with R markdown code:

```{r, fig.align = 'center',out.width= '20%', echo=FALSE }
knitr::include_graphics(path = "figures/R_community.png", auto_pdf = TRUE)
``` 

1.5 Section part

To create a section part you can add the following to the top of a page.

# (PART\*) Name {-}

1.6 Appendix

You can create an appendix from one or multiple pages.

Ensure the first page of your appendix has the following at the top:

# (APPENDIX) Appendix {-}

1.7 YAML files

You will need to edit some YAML files

• _bookdown.yml : Good to change the "book_filename:"
• _output.yml : Good to change the "before:" text to what you want.
  • I turn off a lot of things so readers do not have a lot of buttons I don't want them to have
    • I set "split_by:" set to "rmd" so there is a html page for each rmd file.

More info:

• https://bookdown.org/yihui/bookdown/output-formats.html
• https://bookdown.org/yihui/bookdown/yaml-options.html
• https://bookdown.org/yihui/rmarkdown/bookdown-output.html

1.8 Web exercises

The R package webexercises is useful to include MCQs and other functions in your bookdown.

You will need to initialise this which is below the MCQ and expand example. For more functions please see the following page.

1.8.1 MCQ example

Example code chunk:

```{r, echo = FALSE}
opts_p <- c("__A1__", "__A2__", answer="__A3__")
```
1. Question? `r longmcq(opts_p)`

1. Question?
   A1 A2 A3

1.8.2 template

```{r, echo = FALSE}
opts_p <- c("__ __", "__ __", "__ __")
```
`r longmcq(opts_p)`

1.8.3 Expandable help box example

`r hide("Title")`
Contents
`r unhide()`

Contents

1.8.4 Initalising

You first need to add web exerices to your bookdown (only needs doing once).

Run below in your bookdown dir

library("webexercises")
add_to_bookdown(bookdown_dir = ".",
                include_dir = "www",
                script_dir = "scripts",
                output_format = "gitbook")

If like me you don't use an index.rmd file and instead use your "01-XX.Rmd" as the first page you will need to delete the resulting "index.rmd" file. Then you need to add in the below to your "01-XX.RMD" file just below the block with the title, author etc.

```{r cite-packages, include = FALSE}
# automatically create a bib database for R packages
# add any packages you want to cite here
knitr::write_bib(c(
  .packages(), 'bookdown', 'webexercises'
), 'packages.bib')
```

To make the MCQs have nice boxes around the text change the webex-radiogroup label to the below. This is found in ./www/webex.css

.webex-radiogroup label {
  /*Text colour*/
  color: : #aaaaaa;
  margin-left: 2em;
  margin-bottom: 0.25em;
  text-indent: -1em;
  padding-left: 0.5em;
  font-weight: 400;
  display: block;
  /*Set border of text to solid and dark grey*/
  border: 2px solid #808080;
  border-radius: 0.25em;
}

1.9 Tippy tooltips

You can add tooltips into R markdown with the Tippy R package which uses Tippy.js.

A tooltip is text that appears when you hover your mouse over an item such as text, an example is below.

Text

The below code creates the above:

<u id='word'>Text</u> 

```{r, echo=FALSE}
#Tippy tooltips
tippy::tippy_this(elementId = "word", 
                  tooltip = "This is the tooltip text",
                  arrow = TRUE, placement = "bottom")
```

Our normally displayed text is specified in <u id='ID'>TEXT</u>. This has various functions.

• <u></u>: Underlines TEXT within it.
• id=: Specifies an ID of the TEXT section within <u></u>. Important for the next part.

The function tippy:tippy_this() will add a tooltip to a specified item. The options of the function are:

• elementId: Element to add the tooltip to via its ID.
• tooltip: Text to include in the tooltip.
• arrow: Specifies if the tooltip will have an arrow pointing to the text the tooltip refers to.
• placement: Placement of the tooltip relative to the text the tooltip refers to.

Other options are available for tippy:tippy_this() based on Tippy.js props. For an example see how arrow= is used above compared to the Tippy.js arrow prop.

1.9.1 CSS

I would suggest adding the following to your style.css file to increase the text and box size of the tooltip.

.tippy-tooltip {
  font-size: 16px;
  padding: 3px 5px;
}

1.9.2 Multilpe instances

You can have multiple tooltips in one paragraph . You can even use the same tooltip multiple
times but only needing one tippy_this() call for each ID.

However, you must have each tippy_this() call needed for each .Rmd page on each relevant page. I suggest having one code block with all required tippy_this() calls for the required page at the bottom of that page.

Markdown code for the above text is:

You can have 
<u id='multiple'>multiple</u> 
tooltips in one 
<u id='paragraph'>paragraph</u> 
. You can even use the same tooltip 
<u id='multiple'>multiple</u>  
times but only needing one `tippy_this()` call for each ID.

However, you must have each `tippy_this()` call needed for each __.Rmd__ page on each relevant page.
I suggest having one code block with all required `tippy_this()` 
calls for the required page at the bottom of that page.

```{r, echo=FALSE}
#Tippy tooltips
tippy::tippy_this(elementId = "multiple", 
                  tooltip = "More than one",
                  arrow = TRUE, placement = "bottom")
tippy::tippy_this(elementId = "paragraph", 
                  tooltip = "a distinct section of a piece of writing",
                  arrow = TRUE, placement = "bottom")
```

1.10 Icons

You can use Icons in your bookdown: https://github.com/mitchelloharawild/icons

Note: You will only be able to use free icons.

1.10.1 Fontawesome

The below code can be used to add . Colour chosen to work on Day, Sepia, and Night font.

```{r, echo=FALSE}
icons::icon_style(icons::fontawesome("rocket", style="solid"), fill = "#648fff")
```

To add to text do like so:

A compass (
```{r, echo=FALSE}
icons::icon_style(icons::fontawesome("compass", style="solid"), fill = "#648fff")
```
) is useful to find north.

This will produce:

A compass ( ) is useful to find north.

1.10.2 Ionicons

The below code can be used to add .

```{r, echo=FALSE}
icons::icon_style(icons::ionicons("calculator"), fill = "#648fff")
```

1.10.3 Bioicons

The below code can be used to add .

```{r, echo=FALSE}
icons::bioicons("dna-7")
```

1.10.4 Searching

Search for your icons via the following websites:

• Fontawesome
• Ionicons
• Bioicons

You can check if the name will work with:

library("icons")
icon_find("rocket")

1.10.5 Installing icons

You only need to do the following once in your version of R

#Install library
install.packages("remotes")
remotes::install_github("mitchelloharawild/icons")
#You will also need to download icons
#fontawesome
icons::download_fontawesome()
#Ion icons
icons::download_ionicons()
#Bioincons
icons::download_bioicons()

1.11 Embed YouTube URLS

Handy guide: https://www.h3xed.com/web-development/how-to-make-a-responsive-100-width-youtube-iframe-embed

Add the following to your style.css

.container {
    position: relative;
    width: 100%;
    height: 0;
    padding-bottom: 56.25%;
}
.video {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}

Add the following code to where you want the URL to be embedded. Change the link to the embed link of your video.

<div class="container">
<iframe src="https://www.youtube.com/embed/U_RkeDVU2cg" 
frameborder="0" allowfullscreen class="video"></iframe>
</div>

1.12 style.css code to make page wider

Add code to your bookdown's "style.css" file

Chaning the @media from the default 1240px to 1440px fixed an issue where the nav bars overlay the text.

.book .book-body .page-wrapper .page-inner{
  max-width:1000px !important;margin:0 auto;padding:20px 0 40px
}
@media (max-width:1440px){
  .book .book-body .navigation{
    position:static;top:auto;max-width:50%;width:50%;display:inline-block;float:left
  }
  .book .book-body .navigation.navigation-unique{
  max-width:100%;width:100%
  }
}
@media (max-width:1440px){
  .book .book-body{
    -webkit-transition:-webkit-transform 250ms ease;-moz-transition:-moz-transform 250ms ease;-o-transition:-o-transform 250ms ease;transition:transform 250ms ease;padding-bottom:20px
  }
  .book .book-body .body-inner{
    position:static;min-height:calc(100% - 50px)
  }
}

1.13 Add borders to code blocks

The below instrcutions have been used on this book to alter the code block borders.

You will need 2 things to add borders to the code blocks of a book.

Add the following code block to your first page.

```{r, echo=FALSE}
#Change colour, border, and text of code chunks
#Check style.css for .Rchunk
#https://stackoverflow.com/questions/65627531/change-r-chunk-background-color-in-bookdown-gitbook
#https://bookdown.org/yihui/rmarkdown-cookbook/chunk-styling.html
knitr::opts_chunk$set(class.source="Rchunk") 
```

Add the following to your style.css page. You can of course change the colours but I find the below one is good.

.Rchunk {
  border: 3px solid #808080 !important;
  font-weight: bolder;
  background-color: #f7f7f7 !important;
  border-radius: 5px 5px 5px;
}

Ensure you also change yout code setting like in the below Font settings part. Otherwise the colouring will not be good for the Sepia and Night font settings.

1.14 Create one page html book

Add the following to _output.yml

bookdown::html_book:
  split_by: none
  css: style.css
  toc: false

Run the following command in the book dir to render

bookdown::render_book("01-XX.Rmd", "bookdown::html_book", output_dir = "one_file_book")

1.15 Font family

You can change the font-family with the style.css file.

I have used it to change the font-family of text.

• Text: Using "Lexend" which was designed to be dyslexic friendly but also helps everyone with eye strain. https://fonts.google.com/specimen/Lexend
• Code: "Fira Mono" which can differentiate between 1, l, L, 0, o, and O. (https://fonts.google.com/specimen/Fira+Mono?query=Fira+mono).

I used the instructions from the following useful book: https://rstudio4edu.github.io/rstudio4edu-book/book-fancy.html#book-font

For this I add the following to the top of my style.css code. This:

• Imports fonts from google fonts
• Changes main font.
• CHange table of contents font (sidebar navigation)
• CHanges code font.

@import url('https://fonts.googleapis.com/css2?family=Fira+Mono&family=Lexend&display=swap');
.book.font-family-1 {
  font-family: 'Lexend', sans-serif;
 }
  .summary{
  font-family: 'Lexend', sans-serif;
}
code {
  white-space: inherit;
  font-family: 'Fira Mono', monospace !important;
  font-weight: bolder !important;
  background-color: #f7f7f7 !important;
  color: #333333 !important;
  border-radius: 5px 5px 5px;
}