4.1 bookdown 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, 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.

_output.yml

_output.yml Output formats can be specified either in the YAML metadata of the first Rmd file of the book, or in a separate YAML file named _output.yml under the root directory of the book. See Section 12.4 in R Markdown: The Definitive Guide for a complete list of bookdown output formats. A quick takeaway is that bookdown supports both book types and single documents.

Common uses of _output.yml:

  • Add an edit link, e.g., https://github.com/my1396/R-Notes/edit/main/%s

    This will configure which remote repo to link to and hence allow the page to be downloadable as an .Rmd. Also need to specify download: ["rmd"].

  • Link to your GitHub in the toolbar (also need index.Rmd)

  • Add other sharing links

  • Header and footer of your TOC

  • Collapse the TOC by (sub)section

  • Code highlighting

Here is a brief example of _output.yml:

bookdown::gitbook:
  css: style.css
  highlight: tango
  split_by: section
  includes:
    in_header: head.html
  config:
    fontsettings:
      theme: sky
    toc:
      collapse: section+number
      before: |
        <li><a href="./">R Notes</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
    toc_depth: 3
    edit: 
        link: https://github.com/my1396/R-Notes/edit/main/%s
    sharing:
        github: yes
    download: ["pdf", "epub", "rmd"]
    enableEmoji: true
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

You do NOT need the three dashes --- in _output.yml. In this case, all formats should be at the top level, instead of under an output field in individual Rmds.

  • split_by= c("chapter", "chapter+number", "section", "section+number", "rmd", "none") defaults to chapter, which splits the file by the first-level headers.

    • section splits the file by the second-level headers.
    • chapter+number and section+number: the chapter/section numbers will be prepended to the HTML filenames. For example: if using chapter or section, the HTML file names will be introduction.html, literature.html, etc.; but with the numbering setting, the HTML file names will be 1-introduction.html, 2-literature.html, etc.
    • I prefer section+number as it orders all html in the book’s section order.

  • The includes option allows you to insert arbitrary custom content before and/or after the body of the output.

    It has three sub-options: in_header, before_body, and after_body. You need to know the basic structure of an HTML or LaTeX document to understand these options.

    • The source of an HTML document looks like this:
    <html>

  <head>
  <!-- head content here, e.g. CSS and JS -->
  </head>

  <body>
  <!-- body content here -->
  </body>

</html>

    The in_header option takes a file path and inserts it into the <head> tag. The before_body file will be inserted right below the opening <body> tag, and after_body is inserted before the closing tag </body>.

    Use example of includes option in HTML output.

    For example, when you have LaTeX math expressions rendered via the MathJax library in the HTML output, and want the equation numbers to be displayed on the left (default is on the right), you can create a text file (named mathjax-number.html) that contains the following code:

    <script type="text/x-mathjax-config">
MathJax.Hub.Config({
  TeX: { TagSide: "left" }
});
</script>

    Let’s assume the file mathjax-number.html is in the root directory of your book (the directory that contains all your Rmd files). You can insert this file into the HTML head via the in_header option, e.g.,

    ---
output:
  bookdown::gitbook:
    includes:
      in_header: mathjax-number.html
---

    Example of MathJax config files:

      - [`0007bookdown/mathjax_header.html`](https://github.com/matthew-towers/0007bookdown/blob/master/mathjax_header.html) by matthew-towers

      @matthew-towers uses a very clever approach, probably the easiest setup -- define the command directly in LaTeX and enclode in `<span class="math inline">$...$</span>` to indicate this is inline math.

  - [Using inline config options](https://docs.mathjax.org/en/v2.7-latest/configuration.html#using-in-line-configuration-options)
  - [Stack Overflow MathJax](https://stackoverflow.com/questions/76312006/how-to-load-mathjax-extensions-in-bookdown)

    Bookdown uses MathJax 2.7 by default.

    Define TeX macros

    You can include macro definitions in the Macros section of the TeX blocks of your configuration:

    MathJax.Hub.Config({
  TeX: {
    Macros: {
      RR: "{\\bf R}",
      bold: ["{\\bf #1}",1]
    }
  }
});

    Note that MathJax.Hub.Config is used in inline configuration. It is case-sensitive. Macros has capital M, and TeX, rather than tex, is used.

    • A LaTeX source document has a similar structure:
    \documentclass{book}

% LaTeX preamble
% insert in_header here

\begin{document}
% insert before_body here

% body content here

% insert after_body here
\end{document}

  • You can add a table of contents using the toc option and specify the depth of headers that it applies to using the toc_depth option.

    • If the TOC depth defaults to 3 in html_document.
    • For pdf_document, if the TOC depth is not explicitly specified, it defaults to 2 (meaning that all level 1 and 2 headers will be included in the TOC).
    ---
bookdown::gitbook:
    toc:
        collapse: subsection
    toc_depth: 3
---

    collapse specifies a level to expand to by default, aka at #, ##, or ###.

    I suggest ollapsing at level 2. This way, you get a good overview of what each major topic (level 1 heading) includes, without showing the most detailed items.

    • collapse: subsection: At startup, the toc will collapse at the level 2 headings. As you go to one specific subsection, the content inside will expand. You can see level 3 headings. ✅
    • collapse: section: At startup, the toc will collapse at the level 1 headings, which keeps the appearance concise. However, a side effect is that level 3 headings will never be displaied when navigating to a specific level 2 heading.

bookdown 中文书籍 _output.yml 范例: https://github.com/yihui/bookdown-chinese/blob/96d526572f0c6648d06c2d4bebf57c5fb4eafce3/_output.yml

  • You can set up a tex template.

    Yihui sets up the Chinese support in the template file (latex/template.tex).

    bookdown::pdf_book:
  includes:
    in_header: latex/preamble.tex
    before_body: latex/before_body.tex
    after_body: latex/after_body.tex
  keep_tex: yes
  dev: "cairo_pdf"
  latex_engine: xelatex
  citation_package: natbib
  template: latex/template.tex

    The base format for bookdown::pdf_book is rmarkdown::pdf_document.

    dev: Graphics device to use for figure output, defaults to pdf.

_bookdown.yml

_bookdown.yml allows you to specify optional settings to build the book. For example:

delete_merged_file: true
output_dir: "docs"
new_session: yes
language:
  ui:
    chapter_name: "Chapter "

Note that you don’t need to manually create the docs folder, bookdown will create one if it doesn’t exists.

  • delete_merged_file: whether to delete the main Rmd file after the book is successfully rendered. An Rmd file that is merged from all chapters; by default, it is named _main.Rmd.

  • before_chapter_script: one or multiple R scripts to be executed before each chapter.

  • After you serve your site locally, all supporting files will be output to docs. Be sure to add one .nojekyll file in docs to tell GitHub that your website is not to be built via Jekyll.

  • Because bookdown only overwrites existing files and does not delete unused ones, you can simply delete the docs folder so that bookdown will recreate everything necessary without any redundancy.

    Remember to recreate .nojekyll too after bookdown has created the new docs.

index.Rmd

index.Rmd homepage of your website. Contains the first chapter and the YAML metadata which will be applied to all other Rmd pages. See Chapter 2.2 in R Markdown: The Definitive Guide for YAML details.

Note that index.Rmd is the only Rmd document to contain a YAML frontmatter.

Common uses of index.Rmd’s YAML frontmatter:

  • Book cover, title, author, date, and description

  • Add bibliography

  • Link to your GitHub in the toolbar (also need _output.yml)

  • Add a favicon

    Add the following line to index.Rmd YAML:

    favicon: "images/r-project-favicon.ico"

    Issue: Favicon shows ok on Chrome but couldn’t display on Safari. Same issue reported in Stack Overflow.
    Fix: There is a delay for Safari to show Favicon. Wait for two hours and the issue resolves itself…

An example of index.Rmd

---
title: "A Minimal bookdown Project"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
csl: chicago-fullnote-bibliography.csl
github-repo: my1396/R-Notes
favicon: "images/r-project-favicon.ico"
# typesetting for LaTeX output
papersize: a4 # The printed size of the thesis
geometry:
  - top=25.4mm
  - bottom=25.4mm
  - left=25.4mm
  - right=38.1mm
  # - bindingoffset=6.4mm  # removes a specified space from the inner-side for twoside.
  # - asymmetric  # disable alternating margins on odd/even pages
classoption: 
  - twoside
  - openright
---

# Preface

Some content
  • site: bookdown::bookdown_site tells rmarkdown to use bookdown to build all Rmd files, instead of rendering a single Rmd file.

.Rmd files

  • Chapters (also sections) are based on separate Rmd files.

  • Besides index.Rmd, other R Markdown files will make up the chapters of your book. By default, bookdown merges all Rmd files by the order of filenames, e.g., 01-intro.Rmd will appear before 02-literature.Rmd.

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