12.2 Project structure

Below shows the basic structure of a default bookdown project:

├──  index.Rmd
├── 01-intro.Rmd
├── 02-literature.Rmd
├── 03-method.Rmd
├── 04-application.Rmd
├── 05-summary.Rmd
├── 06-references.Rmd
├── _bookdown.yml
├── _output.yml
├──  book.bib
├──  preamble.tex
├──  README.md
└──  style.css

As a summary of these files:

  • index.Rmd: This is the only Rmd document to contain a YAML frontmatter as described within Chapter 2, and is the first book chapter.

  • Rmd files: A typical bookdown book contains multiple chapters, and each chapter lives in one separate Rmd file.

  • _bookdown.yml: A configuration file for bookdown.

  • _output.yml: It specifies the formatting of the HTML, LaTeX/PDF, and e-books.

  • preamble.tex and style.css: They can be used to adjust the appearance and styles of the book output document(s). Knowledge of LaTeX and/or CSS is required.

These files are explained in greater detail in the following subsections.

12.2.1 Index file

The index.Rmd file contains the first chapter and the YAML metadata, e.g.,

title: "A Minimal Book Example"
author: "Yihui Xie"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
description: "This is a minimal example of using
  the bookdown package to write a book."

12.2.2 Rmd files

By default, all Rmd files are merged with the index.Rmd to render the book. The Rmd files must start immediately with the chapter title using the first-level heading, e.g., # Chapter Title. Note that YAML metadata should not be included in these Rmd files, as it is inherited from the index.Rmd file.

  • 01-intro.Rmd

    # Introduction
    This chapter is an overview of the methods that
    we propose to solve an **important problem**.
  • 02-literature.Rmd

    # Literature
    Here is a review of existing methods.

By default, bookdown merges all Rmd files by the order of filenames, e.g., 01-intro.Rmd will appear before 02-literature.Rmd. Filenames that start with an underscore _ are skipped.

12.2.3 _bookdown.yml

The _bookdown.yml file allows you to specify optional settings to build the book. For example, you may want to override the order in which files are merged by including the field rmd_files:

rmd_files: ["index.Rmd", "02-literature.Rmd", "01-intro.Rmd"]

12.2.4 _output.yml

The _output.yml file is used to specify the book output formats (see Section 12.4). Here is a brief example:

  lib_dir: assets
  split_by: section
      position: static
  keep_tex: yes
  css: toc.css