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.

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")
#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:

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?

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 Icons

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

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

1.9.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.9.2 Ionicons

The below code can be used to add .

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

1.9.3 Bioicons

The below code can be used to add .

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

1.9.4 Searching

Search for your icons via the following websites:

You can check if the name will work with:

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

1.9.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.10 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.11 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.12 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.13 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.14 Font family

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

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

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;
}