html_chapters {bookdown}

Build book chapters into separate HTML files

Description

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

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("section+number", "section", "chapter+number", "chapter", "rmd", "none")
)

html_book(...)

tufte_html_book(...)

Arguments

toc, number_sections, fig_caption, lib_dir, template, pandoc_args

See rmarkdown::html_document, tufte::tufte_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 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 means do not split the HTML file (the book will be a single HTML file); chapter means split the file by the first-level headers; section means the second-level headers. For chapter and section, 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 and section+number, the chapter/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().

Note

These functions are expected to be used in conjunction with render_book(). It is almost meaningless if they are used with rmarkdown::render(). Functions like html_document2 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.