html_chapters: Build book chapters into separate HTML files

In rstudio/bookdown: Authoring Books and Technical Documents with R Markdown

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("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, 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 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().

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.

rstudio/bookdown documentation built on April 5, 2025, 8:20 a.m.