Some things I learned about bookdown::gitbook

Bookdown is an R package that makes writing technical documents based on R much easier. One of the nice things is that you can create a corporate identity using LaTeX styles for pdf output and Cascading Style Sheets for HTML output. I’m in the process of preparing such styles for the Research Institute for Nature and Forest.

Here are a few things that I figured out while testing a complex bookdown report. You can find the document in the inbomd_examples repository on GitHub.

split_by

gitbook will split the document in several pages. The default is by “chapter” (level 1 header: #). Another option is by “section” (level 2 header: ##). Each page must start with a header of the selected level.

So in case of split_by = "chapter", you can’t have text starting without a #. The example below therefore won’t work due to the text prior to the first chapter.

Some text before the first chapter

# First chapter
Text in the first chapter

Things are a bit more tricky in case of split_by = "section". Here text must always start after a ##. Here are a list of things that can go wrong

 Text before the first chapter will yield an error.
 
 # First chapter
 
 Text between the chapter and the first second will yield the same error.
 
 ## First section in first chapter
 
 This is ok.
 
 # Second chapter
 
 A chapter without sections will fail as well.

If such errors occur, you get the following error message when rendering the document:

Error in split_chapters(output, gitbook_page, number_sections, split_by,  :
The document must start with a first (#) or second level (##) heading
Calls: <Anonymous> ... render_cur_session -> <Anonymous> -> <Anonymous> -> split_chapters`

split_by has currently two more options: "chapter+number" and "section+number". They work in exactly the same way. The only difference is that they will add the heading number the filename of each page.

Long titles

The filename of each page is based on the title of the heading of that page. All text is converted to lower case and space are replaced by dashes. E.g. This is a long title becomes this-is-a-long-title.html. If the title is really long, then the filename is too long. Probably you should rethink the title anyway and make it shorter and easier to read.

However you can use an neat trick: add a label to the title. Bookdown will base the filename of the label when a label is available. Adding a label is easy. Just place {#my-label} at the end of the title.

Using labels adds two bonusses: 1) you can use to label to refer to create cross-references to the heading; 2) the url of the page becomes more stable because only changing the title won’t change the filename.

Unnumbered headings

Unnumbered headings are created by adding {-} at the end of the table. Note that unnumbered headings currently (bookdown version 0.4.1) don’t work levels 5 and 6 for pdf output.

In case you want both and unnumbered heading and a labelled heading, you need to combine both within a single set of curly braces. E.g. {- #my-label}