12.2 Project structure

Below shows the basic structure of a default bookdown project:

directory/
├──  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 one chapter lives in one 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

By default, all Rmd files are merged to render the book. The index.Rmd file is the first file when merging all Rmd files. You should and should only specify the YAML metadata in this file, 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

The rest of Rmd files must start immediately with the chapter title using the first-level heading, e.g., # Chapter Title.

  • 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:

bookdown::gitbook:
  lib_dir: assets
  split_by: section
  config:
    toolbar:
      position: static
bookdown::pdf_book:
  keep_tex: yes
bookdown::html_book:
  css: toc.css