Chapter 4 Chapters, sections, etc.

4.1 File Structure

Bookdown organises your notes into a book. The main page you see when you open a bookdown page is the index.Rmd file.

Each chapter in the book has it’s own markdown file. There are two options for defining the order of your chapters: using numbers in the file name, or specifying the order in the _bookdown.yml file.

To avoid any issues with file names in the html version, you need to make sure to add the following to your index.Rmd file:

output: 
  bookdown::gitbook:
    split_by: rmd

The first two lines of the above may already be there, so you’ll probably just need to add the split_by: rmd line. Note that indentation matters here (and in all yml code.)

4.1.1 Specifying the order in _bookdown.yml

The easiest way to organise chapters is to specify the order in the _bookdown.yml file. For this method you don’t need to have the numbers in the file name, and it’s much easier to rearrange things. To specify the order, add an rmd_files section to the _bookdown.yml file and put the file names in the order you want them to appear:

rmd_files:
  - index.Rmd
  - 01-intro.Rmd
  - 02-latex-conversion.Rmd
  - intro-markdown.Rmd
  - 03-chapters.Rmd
  ...
  - 99-references.Rmd

You’ll see here that the intro-markdown.Rmd chapter doesn’t have a number at the start. You don’t need them for this method; bookdown will ignore the numbers and render things in your listed order. More details (that you probably won’t need) about how this works are here. Your references chapter should be the last one, otherwise it doesn’t work properly.

4.1.2 Order by filename

This is the old method of ordering chapters. If you start from the bookdown template (described in Section 1), you’ll see that the template files all start with a number. Bookdown will put the chapters in numerical order. For example, the following file names would order the chapters as they are in this book:

index.Rmd
01-intro.Rmd
02-latex-conversion.Rmd
03-intro-markdown.Rmd
04-chapters.Rmd
... etc

I find this works reasonably well if you know beforehand what order you’re going to put things in, but it quickly gets annoying if you decide later on that you want to add a chapter between two existing ones (you’d have to rename all the subsequent chapters), so I recommend using the method in Section 4.1.1.

4.2 Section labels

The chapter title and label are given in the first line of the file.

# Chapters, sections, etc. {#sec:chapters}

The # at the start of the line denotes a chapter heading (see Section 3.2.1). The label is given in {#sec:chapters}. I think bookdown can create its own labels from the chapter/section heading, but it’s easier to cross-reference if you set them yourself.

You can make sections using two # at the start of the line:

## Section labels {#sec:sec-lables}

Note that the {#sec:label} syntax is still the same - you don’t need to say whether it’s a chapter, section, subsection etc.

Subsections are done similarly, with three # at the start of the line.

You can change the section heading from “Chapter” to e.g. “Section” by editing the following in the _bookdown.yml file:

language:
  ui:
    chapter_name: "Section "

4.3 Cross referencing

You can reference other chapters, sections etc. throughout the book with the following syntax:

Section \@ref(sec:cross-ref) is this section.

Section 4.3 is this section.

When cross-referencing, you don’t need the # before sec. That’s only used to define the label.