Suggestions on styling and workflow
Alicia Johnson, Miles Ott, and I have recently finished writing our textbook Bayes Rules! using bookdown. Fellow bookdown authors have asked us questions on styling book as they are writing their book. Through this blog post, I hope to answer their questions (mostly on styling) and share some tips. This blog post is not intended to introduce CSS or LaTeX or bookdown. However, most likely you may end up here if you have been searching certain questions related to bookdown with gitbook and/or pdf output.
If you prefer looking at code rather than reading blog posts, then here is a demo repo of the changes (folder structure, styling) mentioned in this blogpost. The overview of commit history may help breakdown each step. Below I explain the set of changes step-by-step.
If you have started using bookdown with a typical route, you have started with RStudio’s demo template. This is a great template for beginners. However, when you write textbooks with multiple chapters and have separate .Rmd files for exercises as well, then there are multiple files in the main directory.
Our solution has been using child documents. In the repo, you will see that we have chapters and exercises folders. In each of these folders we have the appropriate .Rmd files. Even though not shown in the repo, we also used these folders to store /img folder as well for images we used in chapters and exercises.
If you decide to use the /chapters and /exercises folders then it is important to call the .Rmd files as child documents in the index.Rmd file.
Below is an example:
```{r child = 'chapters/01-intro.Rmd', eval = TRUE}
```
```{r child = 'exercises/01-intro-exercises.Rmd', eval = TRUE}
```
```{r child = 'chapters/02-literature.Rmd', eval = TRUE}
```A great benefit of using child documents have been easily turning eval=FALSE to prevent building all the chapters.
Do not forget to stop enumeration of sections in the index.Rmd by using {-} e.g. # Prerequisites {-} in the index.Rmd in the demo repo.
If you are not already familiar with exercise blocks, they will come in handy when writing with bookdown. It helps enumerate exercises and cross-reference them! Here is an example:
```{exercise, label = "life-meaning", name="Interesting Question"}
What is the meaning of life?
```
```{exercise, name="Interesting Question 2"}
If you answered 42 in Exercise \@ref(exr:life-meaning), consider other possible answers.
```I believe there is also an example in addition to exercise block but I have not used them before.
Custom blocks are extensively covered in the bookdown book both for HTML outputs and pdf outputs. We have utilized them throughout the book to write quiz, note, or warning boxes.
Custom blocks styling examples are provided in the sample repo as CSS file for HTML outputs and the LaTeX file for pdf outputs.
I also personally prefer keeping all style related files in one place under /style folder.
In HTML, h1, h2, h3… tags correspond to header 1, header 2, and so on.
The code below changes the font color at header 1, 2, and 3 levels and then also adds bottom and top borders for headers at header 1 and 2 level. Here is the associated commit.
h1, h2, h3{
color:#FFA500;
}
h1, h2{
border-bottom: 3px solid #FFA500;
border-top: 3px solid #FFA500;
}LaTeX can be quite different. We already were working with the CRC template in order to change the font color for headers we only needed to change certain parts.
If you would need, then you would also need to find relevant code in your own template. For instance we have switched from the first line of code to second line of code as shown below. The rest of header coloring can be done in a similar fashion in the krantz.cls(krantz.cls) file (not provided in the demo repo since it is specific to CRC).
\newcommand\ChapNumFont{\reset@font\fontsize{24}{24}\bfseries\selectfont}
\newcommand\ChapNumFont{\color{orange}\reset@font\fontsize{24}{24}\bfseries\selectfont}
Styling R code chunks and an inline code in an HTML output is similar in bookdown, xaringan etc. So you can pick a style that you can use and re-use.
In order to change the style of the inline code the CSS selector is .book .book-body .page-wrapper .page-inner section.normal code. The code below changes the background color and font family for inline code.
.book .book-body .page-wrapper .page-inner section.normal code {
background-color: #eaeff0;
font-family: Monospace;
}In order to change the style of the code chunk the CSS selector is .book .book-body .page-wrapper .page-inner section.normal pre. The code below changes the background color, font family, and sets a border for code chunks.
.book .book-body .page-wrapper .page-inner section.normal pre {
background-color:white;
border:1px solid black;
font-family: Monospace;
}