[BOOKDOWN second] output

The bookdown package primarily supports three types of output formats: HTML, LaTeX/PDF, and e-books. In this chapter, we introduce the possible options for these formats.
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.
Eg:
Here is a brief example of the former (output formats are specified in the output field of the YAML metadata):

---
title: "An Impressive Book"
author: "Li Lei and Han Meimei"
output:
  bookdown::gitbook:
    lib_dir: assets
    split_by: section
    config:
      toolbar:
        position: static
  bookdown::pdf_book:
    keep_tex: true
  bookdown::html_book:
    css: toc.css
documentclass: book
---

Here is an example of _output.yml:

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

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

1. Gitbook

The easiest way to get started writing a new gitbook is to use the RStudio Project Wizard (File > New Project > New Directory > Book project using bookdown) and select gitbook from the dropdown menu.

If you do not use RStudio or prefer a function, you can create the same project template with bookdown::create_gitbook() from your R console. See ?bookdown::create_gitbook for help.

The output format function for the GitBook style in bookdown is gitbook(). Here are its arguments:

gitbook(fig_caption = TRUE, number_sections = TRUE,
  self_contained = FALSE, anchor_sections = TRUE,
  lib_dir = "libs", global_numbering = !number_sections,
  pandoc_args = NULL, extra_dependencies = list(),
  ..., template = "default", split_by = c("chapter",
    "chapter+number", "section", "section+number",
    "rmd", "none"), split_bib = TRUE, config = list(),
  table_css = TRUE, code_folding = c("none", "show",
    "hide"))

We strongly recommend you to use fig_caption = TRUE for two reasons: 1) it is important to explain your figures with captions; 2) enabling figure captions means figures will be placed in floating environments when the output is LaTeX, otherwise you may end up with a lot of white space on certain pages. The format of figure/table numbers depends on if sections are numbered or not: if number_sections = TRUE, these numbers will be of the format X.i, where X is the chapter number, and i in an incremental number; if sections are not numbered, all figures/tables will be numbered sequentially through the book from 1, 2, …, N.

Please note that if you change self_contained = TRUE to make self-contained HTML pages, the total size of all HTML files can be significantly increased since there are many JS and CSS files that have to be embedded in every single HTML file.

Besides these html_document() options, gitbook() has three other arguments: split_by, split_bib, and config. The split_by argument specifies how you want to split the HTML output into multiple pages, and its possible values are:

• rmd: use the base filenames of the input Rmd files to create the HTML filenames, e.g., generate chapter3.html for chapter3.Rmd.
• none: do not split the HTML file (the book will be a single HTML file).
• chapter: split the file by the first-level headers.
• section: split the file by the second-level headers.
• chapter+number and section+number: similar to chapter and section, but the files will be numbered.

The header identifier is automatically generated from the header text by default,⁹ and you can manually specify an identifier using the syntax {#your-custom-id} after the header text, e.g.,

# An Introduction {#introduction}

The default identifier is `an-introduction` but we changed
it to `introduction`.

By default, the bibliography is split and relevant citation items are put at the bottom of each page, so that readers do not have to navigate to a different bibliography page to see the details of citations. This feature can be disabled using split_bib = FALSE, in which case all citations are put on a separate page.

There are several sub-options in the config option for you to tweak some details in the user interface. Recall that all output format options (not only for bookdown::gitbook) can be either passed to the format function if you use the command-line interface bookdown::render_book(), or written in the YAML metadata. We display the default sub-options of config in the gitbook format as YAML metadata below (note that they are indented under the config option):

归根结底还是YAML

bookdown::gitbook:
  config:
    toc:
      collapse: subsection
      scroll_highlight: true
      before: null
      after: null
    toolbar:
      position: fixed
    edit : null
    download: null
    search:
      engine: lunr # or fuse
      # options to control/tune search engine behavior (for
      # fuse.js, refer to https://fusejs.io/api/options.html)
      options: null
    fontsettings:
      theme: white
      family: sans
      size: 2
    sharing:
      facebook: true
      github: false
      twitter: true
      linkedin: false
      weibo: false
      instapaper: false
      vk: false
      whatsapp: false
      all: ['facebook', 'twitter', 'linkedin', 'weibo', 'instapaper']
    info: true

Finally, there are a few more top-level options in the YAML metadata that can be passed to the GitBook HTML template via Pandoc. They may not have clear visible effects on the HTML output, but they may be useful when you deploy the HTML output as a website. These options include:

• description: A character string to be written to the content attribute of the tag <meta name="description" content=""> in the HTML head (if missing, the title of the book will be used). This can be useful for search engine optimization (SEO). Note that it should be plain text without any Markdown formatting such as _italic_ or **bold**.
• url: The URL of book’s website, e.g., https\://bookdown.org/yihui/bookdown/.¹⁰
• github-repo: The GitHub repository of the book of the form user/repo.
• cover-image: The path to the cover image of the book.
• apple-touch-icon: A path to an icon (e.g., a PNG image). This is for iOS only: when the website is added to the Home screen, the link is represented by this icon.
• apple-touch-icon-size: The size of the icon (by default, 152 x 152 pixels).
• favicon: A path to the “favorite icon”. Typically this icon is displayed in the browser’s address bar, or in front of the page title on the tab if the browser support tabs.

Below we show some sample YAML metadata (again, please note that these are top-level options):

---
title: "An Awesome Book"
author: "John Smith"
description: "This book introduces the ABC theory, and ..."
url: 'https\://bookdown.org/john/awesome/'
github-repo: "john/awesome"
cover-image: "images/cover.png"
apple-touch-icon: "touch-icon.png"
apple-touch-icon-size: 120
favicon: "favicon.ico"
---

A nice effect of setting description and cover-image is that when you share the link of your book on some social network websites such as Twitter, the link can be automatically expanded to a card with the cover image and description of the book.

2. Three-column Bootstrap style

3. The default Bootstrap style

4. Tufte style

5. LaTeX/PDF

与HTML的主要区别就在于label与reference的差异
The LaTeX/PDF output format is provided by pdf_book() in bookdown. There is not a significant difference between pdf_book() and the pdf_document() format in rmarkdown. The main purpose of pdf_book() is to resolve the labels and cross-references written using the syntax described in Sections 2.4, 2.5, and 2.6. If the only output format that you want for a book is LaTeX/PDF, you may use the syntax specific to LaTeX, such as \label{} to label figures/tables/sections, and \ref{} to cross-reference them via their labels, because Pandoc supports LaTeX commands in Markdown. However, the LaTeX syntax is not portable to other output formats, such as HTML and e-books. That is why we introduced the syntax (\#label) for labels and \@ref(label) for cross-references.

There are some top-level YAML options that will be applied to the LaTeX output. For a book, you may change the default document class to book (the default is article), and specify a bibliography style required by your publisher. A brief YAML example:

---
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
---

There are a large number of other YAML options that you can specify for LaTeX output, such as the paper size, font size, page margin, line spacing, font families, and so on. See http://pandoc.org/MANUAL.html#variables-for-latex for a full list of options.

The pdf_book() format is a general format like html_book(), and it also has a base_format argument:

pdf_book(toc = TRUE, number_sections = TRUE, fig_caption = TRUE,
  pandoc_args = NULL, ..., base_format = rmarkdown::pdf_document,
  toc_unnumbered = TRUE, toc_appendix = FALSE, toc_bib = FALSE,
  quote_footer = NULL, highlight_bw = FALSE)

You can change the base_format function to other output format functions, and bookdown has provided a simple wrapper function tufte_book2(), which is basically pdf_book(base_format = tufte::tufte_book), to produce a PDF book using the Tufte PDF style (again, see the tufte package).

6. E-Books

7. A single document

Sometimes you may not want to write a book, but a single long-form article or report instead. Usually what you do is call rmarkdown::render() with a certain output format. The main features missing there are the automatic numbering of figures/tables/equations, and cross-referencing figures/tables/equations/sections. We have factored out these features from bookdown, so that you can use them without having to prepare a book of multiple Rmd files.

The functions html_document2(), tufte_html2(), pdf_document2(), word_document2(), tufte_handout2(), and tufte_book2() are designed for this purpose. If you render an R Markdown document with the output format, say, bookdown::html_document2, you will get figure/table numbers and be able to cross-reference them in the single HTML page using the syntax described in Chapter [2].

Below are a few examples of these output formats in the YAML metadata of a single Rmd file (you can also add these formats to the _output.yml file):

output:
  bookdown::html_document2: default
  bookdown::pdf_document2:
    keep_tex: true
  bookdown::word_document2:
    toc: true

The above HTML and PDF output format functions are basically wrappers of output formats bookdown::html_book and bookdown::pdf_book, in the sense that they changed the base_format argument. For example, you can take a look at the source code of pdf_document2:

bookdown::pdf_document2

## function (...) 
## {
##     pdf_book(..., base_format = rmarkdown::pdf_document)
## }
## <bytecode: 0x7f8af3bc4e78>
## <environment: namespace:bookdown>

After you know this fact, you can apply the same idea to other output formats by using the appropriate base_format. For example, you can port the bookdown features to the jss_article format in the rticles package (Allaire et al. 2022) by using the YAML metadata:

output:
  bookdown::pdf_book:
    base_format: rticles::jss_article

所以这个包的核心就在basic部分,也就是第二章节,就是cross-reference.
这个base_format挺可以的
Then you will be able to use all features we introduced in Chapter 2.

Although the gitbook() format was designed primarily for books, you can actually also apply it to a single R Markdown document. The only difference is that there will be no search button on the single page output, because you can simply use the searching tool of your web browser to find text (e.g., press Ctrl + F or Command + F). You may also want to set the option split_by to none to only generate a single output page, in which case there will not be any navigation buttons, since there are no other pages to navigate to. You can still generate multiple-page HTML files if you like. Another option you may want to use is self_contained = TRUE when it is only a single output page.