# Build book chapters into separate HTML files

Split the HTML output into chapters while updating relative links (e.g.
links in TOC, footnotes, citations, figure/table cross-references, and
so on). Functions `html_book()` and `tufte_html_book()` are simple
wrapper functions of `html_chapter()` using a specific base output
format.

## Usage

``` r
html_chapters(
  toc = TRUE,
  number_sections = TRUE,
  fig_caption = TRUE,
  lib_dir = "libs",
  template = bookdown_file("templates/default.html"),
  global_numbering = !number_sections,
  pandoc_args = NULL,
  ...,
  base_format = rmarkdown::html_document,
  split_bib = TRUE,
  page_builder = build_chapter,
  split_by = c("chapter", "section", "0", "1", "2", "3", "4", "5", "6", "chapter+number",
    "section+number", "0+number", "1+number", "2+number", "3+number", "4+number",
    "5+number", "6+number", "rmd", "none")
)

html_book(...)

tufte_html_book(...)
```

## Arguments

- toc, number_sections, fig_caption, lib_dir, template, pandoc_args:

  See
  `rmarkdown::`[`html_document`](https://pkgs.rstudio.com/rmarkdown/reference/html_document.html),
  `tufte::`[`tufte_html`](https://rdrr.io/pkg/tufte/man/tufte_handout.html),
  or the documentation of the `base_format` function.

- global_numbering:

  If `TRUE`, number figures and tables globally throughout a document
  (e.g., Figure 1, Figure 2, ...). If `FALSE`, number them sequentially
  within sections (e.g., Figure 1.1, Figure 1.2, ..., Figure 5.1, Figure
  5.2, ...). Note that `global_numbering = FALSE` will not work with
  `number_sections = FALSE` because sections are not numbered.

- ...:

  Other arguments to be passed to `base_format`. For `html_book()` and
  `tufte_html_book()`, `...` is passed to `html_chapters()`.

- base_format:

  An output format function to be used as the base format.

- split_bib:

  Whether to split the bibliography onto separate pages where the
  citations are actually used.

- page_builder:

  A function to combine different parts of a chapter into a page (an
  HTML character vector). See
  [`build_chapter`](https://pkgs.rstudio.com/bookdown/reference/build_chapter.md)
  for the specification of this function.

- split_by:

  How to name the HTML output files from the book: `rmd` uses the base
  filenames of the input Rmd files to create the HTML filenames, e.g.
  generate `chapter1.html` for `chapter1.Rmd`; `none` or `"0"` means do
  not split the HTML file (the book will be a single HTML file);
  `chapter` or `"1"` means split the file by the first-level headers;
  `section` or `"2"` means the second-level headers, `"3"`-`"6"` means
  split the file by the \[3-6\]-level headers. For `chapter`, `section`
  and `"1"`-`"6"`, the HTML filenames will be determined by the header
  ID's, e.g. the filename for the first chapter with a chapter title
  `# Introduction` will be `introduction.html`; for `"chapter+number"`,
  `"section+number"` and `"[1-6]+number"` the chapter/section (and
  higher level section) numbers will be prepended to the HTML filenames,
  e.g. `1-introduction.html` and `2-1-literature.html`.

## Value

An R Markdown output format object to be passed to
[`bookdown::render_book()`](https://pkgs.rstudio.com/bookdown/reference/render_book.md).

## Note

These functions are expected to be used in conjunction with
[`render_book()`](https://pkgs.rstudio.com/bookdown/reference/render_book.md).
It is almost meaningless if they are used with
[`rmarkdown::render()`](https://pkgs.rstudio.com/rmarkdown/reference/render.html).
Functions like
[`html_document2`](https://pkgs.rstudio.com/bookdown/reference/html_document2.md)
are designed to work with the latter.

If you want to use a different template, the template must contain three
pairs of HTML comments: `<!--bookdown:title:start-->` and
`<!--bookdown:title:end-->` to mark the title section of the book (this
section will be placed only on the first page of the rendered book);
`<!--bookdown:toc:start-->` and `<!--bookdown:toc:end-->` to mark the
table of contents section (it will be placed on all chapter pages);
`<!--bookdown:body:start-->` and `<!--bookdown:body:end-->` to mark the
HTML body of the book (the HTML body will be split into separate pages
for chapters). You may open the default HTML template
(`bookdown:::bookdown_file('templates/default.html')`) to see where
these comments were inserted.