### Update label prefix for Example blocks

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Changes the required label prefix for Example blocks from `ex:` to `exm:`. This standardization ensures consistency in how examples are referenced.

```R
```{exm:example-label}
This is an example.
```
```

--------------------------------

### Theorem Environment Syntax

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Provides an example of using the Theorem environment with fenced Div syntax in Markdown for beamer_presentation2 output.

```Markdown
::: {.theorem #label name="My Theorem"}
Content
:::
```

--------------------------------

### Install bookdown Development Version from GitHub

Source: https://github.com/rstudio/bookdown/blob/main/README.md

Installs the development version of the bookdown R package directly from its GitHub repository using the 'pak' package. This allows users to access the latest features and bug fixes before they are released on CRAN.

```R
# install.packages("pak")
pak::pak('rstudio/bookdown')
```

--------------------------------

### Install bookdown from CRAN

Source: https://github.com/rstudio/bookdown/blob/main/README.md

Installs the bookdown R package from the Comprehensive R Archive Network (CRAN). This is the standard method for obtaining the latest stable release of the package.

```R
install.packages("bookdown")
```

--------------------------------

### Gitbook Search Input Keybinding Information

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Includes information about the Enter/Up/Down keybindings within the placeholder text and tooltip of the search input in `gitbook` output. This guides users on how to effectively use the search and navigation features.

```R
bookdown::gitbook()
```

--------------------------------

### Fix serve_book() with rstudioapi installed

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Corrects an error in `serve_book()` that occurred when `rstudioapi` was installed but RStudio was not actively being used. This allows `serve_book()` to function correctly in various environments.

```R
bookdown::serve_book()
```

--------------------------------

### Markdown Document with Base Format

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces `markdown_document2` which allows the use of cross-references in an arbitrary format specified by the `base_format` argument. This enables flexible customization of Markdown output, for example, using `prettydoc::html_pretty`.

```R
bookdown::markdown_document2(base_format = prettydoc::html_pretty)
```

--------------------------------

### Ignore Files Starting with Underscore

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Implements a change where files with a leading underscore (`_`) in their names are always ignored, even if listed in `rmd_files` in `_bookdown.yml`. This also applies to such files within subdirectories.

```R
# _bookdown.yml configuration example
# rmd_files: ["index.Rmd", "_sidebar.Rmd", "01-intro.Rmd"]
# (File "_sidebar.Rmd" will be ignored)
```

--------------------------------

### Support Theorem and Proof Environments

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Re-enables support for Theorem and Proof environments in the `slidy_presentation2()` HTML slide format. This allows for structured presentation of mathematical or logical proofs.

```R
slidy_presentation2()
```

--------------------------------

### Applying GPL to New Programs

Source: https://github.com/rstudio/bookdown/blob/main/LICENSE.txt

This section provides a template for incorporating the GNU General Public License into new software projects. It includes standard copyright notices and statements regarding redistribution and warranty.

```Text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
```

--------------------------------

### Support for Exercises and Solutions environments

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adds support for two new theorem-like environments: 'Exercises' and 'Solutions'. These can be used to structure and format specific types of content within the book.

```R
```{exercise}
# Content for an exercise
```

```{solution}
# Content for a solution
```
```

--------------------------------

### Interactive Program Notice (GPL)

Source: https://github.com/rstudio/bookdown/blob/main/LICENSE.txt

This snippet shows how a program licensed under the GNU GPL should display a notice when run in interactive mode, informing users about its free software status, warranty, and redistribution conditions.

```Text
<program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
```

--------------------------------

### Create Theorem/Proof Environments using Pandoc's Fenced Divs

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces an alternative method for creating theorem and proof environments using Pandoc's fenced Divs (e.g., `::: {.theorem}`). The `bookdown::fence_theorems()` helper function can convert the older code chunk syntax to this new fenced Div syntax. This allows for arbitrary content within theorem environments, including R code chunks.

```R
bookdown::fence_theorems()
::: {.theorem}
```

--------------------------------

### Code Highlighting Initialization (JavaScript)

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/gitbook.html

Initializes highlight.js for code syntax highlighting once the document is fully loaded. This script is conditionally included if highlightjs is enabled.

```JavaScript
if (window.hljs && document.readyState && document.readyState === "complete") {
  window.setTimeout(function() {
    hljs.initHighlighting();
  }, 0);
}
```

--------------------------------

### MathJax Configuration (JavaScript)

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/gitbook.html

Configures and loads MathJax for rendering mathematical equations. It dynamically creates a script tag to include the MathJax library, with options for CDN source and configuration.

```JavaScript
(function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    var src = "$if(mathjax)$ $mathjax$ $endif$";
    if (src === "" || src === "true") src = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/latest.js?config=$if(mathjax-config)$$mathjax-config$$else$TeX-MML-AM_CHTML$endif$";
    if (location.protocol !== "file:")
        if (/^https?:/.test(src))
            src = src.replace(/^https?:/, '');
    script.src = src;
    document.getElementsByTagName("head")[0].appendChild(script);
})();
```

--------------------------------

### Initialize highlight.js for Code Highlighting

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/default.html

This JavaScript code initializes highlight.js for code syntax highlighting in the document. It ensures that code blocks are properly styled after the document is fully loaded. It includes conditional loading based on the 'highlightjs' variable and applies a white background to preformatted text if a theme is specified.

```JavaScript
if (window.hljs && document.readyState && document.readyState === "complete") {
  window.setTimeout(function() {
    hljs.initHighlighting();
  }, 0);
}
```

--------------------------------

### Update Theorem/Proof Environment Syntax Requirement

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The new syntax for theorem and proof environments in bookdown now requires Pandoc version 2.3 or higher, an update from the previous requirement of Pandoc 2.0. This change supports enhanced theorem and proof formatting.

```R
Pandoc >= 2.3
```

--------------------------------

### Build Bookdown Book using RStudio IDE

Source: https://github.com/rstudio/bookdown/blob/main/README.md

Demonstrates how to build the HTML version of a bookdown project using the RStudio IDE. This involves navigating to the Build Pane and selecting 'Build Book' with the 'bookdown::gitbook' format.

```R
bookdown::gitbook
```

--------------------------------

### Correct Refreshing of serve_book() with Subdirectories

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `serve_book()` function now refreshes correctly when subdirectories are used with `rmd_subdir`. This ensures that live previews update accurately when the project structure includes subfolders.

```R
serve_book(rmd_subdir = TRUE)
```

--------------------------------

### Update Documentation for render_book() output_format

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The documentation for the `output_format` parameter in `render_book()` has been updated to provide clearer instructions on how to set options. This helps users configure the output formats more effectively.

```R
render_book()
```

--------------------------------

### Create Gitbook Project Template

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Provides R functions to create a new RStudio project template for an HTML book using the bookdown::gitbook format.

```R
bookdown::create_gitbook()
```

--------------------------------

### Render bookdown from Directory

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `render_book()` function now accepts a directory as input, allowing rendering of a book using the `index.Rmd` file within that directory. The default behavior has also changed to look for `input.Rmd` in the current working directory.

```R
render_book("book_dir")
render_book()
```

--------------------------------

### Configure bookdown LaTeX Preamble

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Allows opting out of bookdown's theorem and proof definitions in the LaTeX preamble by setting `bookdown.theorem.preamble` to `FALSE` in `custom-enviromnent.lua`. This is useful for resolving conflicts with specific LaTeX formats.

```Lua
bookdown.theorem.preamble = FALSE
```

--------------------------------

### Render Bookdown Book using R Console

Source: https://github.com/rstudio/bookdown/blob/main/README.md

Provides the R console command to render a bookdown project. This function processes the R Markdown files and generates the output book in the specified format.

```R
bookdown::render_book()
```

--------------------------------

### Process Markdown Content in Special Environments

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enables the support for specific markdown content, such as lists or code chunks, within Theorem and Proof special environments. This enhances the flexibility of content creation within these structured elements.

```R
render_book()
```

--------------------------------

### Configure Gitbook Search Engine

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Demonstrates how to configure the bookdown::gitbook output format to use 'fuse.js' as the search engine by modifying the YAML configuration.

```YAML
output:
  bookdown::gitbook:
    config:
      search:
        engine: fuse
```

--------------------------------

### Adapt CSS for <details><summary> in gitbook() and html_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

This fix ensures that the content within `<details><summary>` tags is displayed correctly in gitbook() and html_book() outputs by adapting the CSS. It addresses an issue related to the rendering of collapsible content.

```R
gitbook()
html_book()
```

--------------------------------

### MathJax Configuration in bookdown

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/bs4_book.html

This JavaScript snippet configures MathJax for rendering mathematical equations within a bookdown project. It dynamically loads the MathJax library, allowing for customization of the configuration and ensuring proper rendering of TeX and MathML content.

```JavaScript
function () {
  var script = document.createElement("script");
  script.type = "text/javascript";
  var src = "$if(mathjax)$ $mathjax$ $endif$";
  if (src === "" || src === "true") src = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/latest.js?config=$if(mathjax-config)$$mathjax-config$$else$TeX-MML-AM_CHTML$endif$";
  if (location.protocol !== "file:") if (/^https?:/.test(src)) src = src.replace(/^https?:/, '');
  script.src = src;
  document.getElementsByTagName("head")[0].appendChild(script);
}
```

--------------------------------

### Handle Text References for Theorem Environments

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an issue where text references do not work correctly for 'theorem' environments. This ensures that cross-referencing for theorem environments functions as expected.

```R
# bookdown::render_book() with theorem environments
# (Issue related to text references, fix not explicitly coded)
```

--------------------------------

### Handle Asset Display Across Output Formats

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Addresses an issue where certain parts, like figures, might not display correctly when switching between output formats (e.g., HTML to LaTeX) using the 'new_session: yes' option in _bookdown.yml.

```yaml
_bookdown.yml:
  new_session: yes
```

--------------------------------

### Fix Proof and Remark blocks for EPUB output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Addresses issues with the 'Proof' and 'Remark' blocks not rendering correctly in EPUB output. This ensures these specialized content blocks are displayed properly in the EPUB format.

```R
```{proof}
Content of the proof.
```

```{remark}
Content of the remark.
```
```

--------------------------------

### Create BS4 Book Project Template

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Provides R functions to create a new RStudio project template for an HTML book using the bookdown::bs4_book format.

```R
bookdown::create_bs4_book()
```

--------------------------------

### Suppress Warnings for Multiple Input Files in render_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

When passing several input files to `render_book(preview = TRUE)`, no more warnings are thrown. This streamlines the rendering process for projects with multiple source files.

```R
render_book(preview = TRUE)
```

--------------------------------

### Define Theorem Environments for LaTeX Output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Ensures that theorem environments are properly defined for LaTeX output only when a 'theorem' block is present in the R Markdown document.

```markdown
:::{theorem}
This is a theorem.
:::
```

--------------------------------

### Untitled

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

No description

--------------------------------

### Support Multiple Authors in gitbook() Output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `gitbook()` output format now properly supports multiple authors. This enhancement allows for accurate representation of all contributors in the book's metadata and display.

```R
gitbook()
```

--------------------------------

### Render Math in epub3 with Pandoc

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Addresses an issue where Pandoc 2.19 did not render math by default in `epub3` format. This fix ensures mathematical expressions are correctly displayed in EPUB3 outputs.

```R
epub3()
```

--------------------------------

### Enable YAML 'includes: before_body' for Gitbook

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Ensures that the YAML option 'includes: before_body' functions correctly for Gitbook output, allowing content to be inserted before the main body.

```yaml
output:
  bookdown::gitbook:
    includes:
      before_body:
        - text: "My custom content"
          when: "after_body"
```

--------------------------------

### Apply CSS for Code Highlighting and Themes

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/default.html

This snippet applies CSS rules for code highlighting, including setting white-space to pre and potentially overriding default background colors for preformatted text when a theme is active. It also includes the 'highlighting-css' variable if provided.

```CSS
code {
  white-space: pre;
}
$if(theme)$ pre:not([class]) {
  background-color: white;
}
$endif$
$if(highlighting-css)$ $highlighting-css$
$if(theme)$ pre:not([class]) {
  background-color: white;
}
$endif$
$endif$
```

--------------------------------

### Handle Multiple Files in render_book with R 4.3.x

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an error that occurred in R 4.3.x when multiple files were passed to `render_book()` without an `output_format` specified. This ensures compatibility with newer R versions.

```R
render_book(output_format = "bookdown::gitbook")
```

--------------------------------

### Configure WhatsApp Sharing for gitbook

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enables WhatsApp sharing for the `gitbook()` format by configuring the `sharing` key in `config`. This allows users to share bookdown URLs via WhatsApp on mobile and desktop devices.

```YAML
sharing:
  whatsapp: true
```

--------------------------------

### Footnote Popover Rendering with MathJax

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/bs4_book.html

This JavaScript code enhances footnote references by enabling popovers with MathJax support. It targets footnote links with specific attributes, creates temporary divs for rendering, and uses MathJax to typeset any mathematical content within the popovers before displaying it.

```JavaScript
const popovers = document.querySelectorAll('a.footnote-ref[data-toggle="popover"]');
for (let popover of popovers) {
    const div = document.createElement('div');
    div.setAttribute('style', 'position: absolute; top: 0, left:0; width:0, height:0, overflow: hidden; visibility: hidden;');
    div.innerHTML = popover.getAttribute('data-content');
    var has_math = div.querySelector("span.math");
    if (has_math) {
        document.body.appendChild(div);
        MathJax.Hub.Queue(["Typeset", MathJax.Hub, div]);
        MathJax.Hub.Queue(function() {
            popover.setAttribute('data-content', div.innerHTML);
            document.body.removeChild(div);
        })
    }
}
```

--------------------------------

### Correctly copy URL-encoded resources

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Ensures that resources with URL-encoded special characters are correctly copied to the output directory. This prevents issues with assets that have non-standard characters in their paths.

```R
# Ensure resource paths are correctly handled, e.g., "my%20folder/image.png"
```

--------------------------------

### Add template argument to gitbook() and epub_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces the 'template' argument to the gitbook() and epub_book() functions, allowing for customization of output formats. This feature enhances flexibility in bookdown's output generation.

```R
gitbook(template = "your_template")
epub_book(template = "your_template")
```

--------------------------------

### Handle Language UI Options in _bookdown.yml

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Moves configuration options 'edit: text' and 'chapter_name' to sub-options of 'language: ui' within _bookdown.yml for better internationalization management.

```yaml
language:
  ui:
    edit: text
    chapter_name: "Chapter Name"
```

--------------------------------

### Correct Chunk Option 'name' for Remark and Proof Blocks

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes the behavior of the chunk option 'name' for 'remark' and 'proof' blocks, ensuring it works correctly for non-LaTeX output formats.

```markdown
```{remark, name='myremark'}
This is a remark.
```
```

--------------------------------

### Opt-out of bookdown theorem syntax

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Demonstrates how to disable bookdown's special syntax for theorem and proof environments by setting an option. This is useful for advanced users who manage these environments manually or use custom block syntax.

```r
options(bookdown.theorem.enabled = FALSE)
```

--------------------------------

### Specify custom config file for render_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adds the 'config_file' argument to the render_book() function, allowing users to specify a custom configuration file instead of relying solely on the default '_bookdown.yml'. This provides greater flexibility in project configuration.

```R
bookdown::render_book("index.Rmd", config_file = "my_config.yml")
```

--------------------------------

### Set EPUB Version

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Illustrates how to specify the EPUB version for the epub_book function, allowing the creation of EPUB version 2 books.

```R
epub_book(epub_version = "epub2")
```

--------------------------------

### Cross-Reference Equations in Multi-Page HTML and EPUB

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enables cross-referencing of equations within multi-page HTML output and EPUB formats, facilitating easier navigation and citation of mathematical content.

```markdown
See equation \@ref(eq:myequation) for details.

```{{r myequation}}
1 + 1
```
```

--------------------------------

### Configure Github Button in Gitbook Output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enables the display of a Github button in the toolbar for Gitbook output. Requires setting 'github: yes' in Gitbook configurations and specifying the 'github-repo' in the index.Rmd YAML metadata.

```yaml
gitbook:
  sharing:
    github: yes
github-repo: rstudio/bookdown
```

--------------------------------

### Gitbook Toolbar Information Button

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adds an Information button to the `gitbook` toolbar. This button displays keybindings, making it easier for users to discover and utilize the interactive features of the book.

```R
bookdown::gitbook()
```

--------------------------------

### Configure MathJax in bookdown

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Allows setting a custom MathJax configuration string for `bs4_book` and `gitbook` output formats. This can be done via YAML metadata or as a `pandoc_args` variable. Supported settings include default, HTML+CSS, and SVG rendering.

```R
bs4_book(mathjax_config = "TeX-AMS-MML_HTMLorMML")
# or in YAML:
# output:
#   bookdown::bs4_book:
#     mathjax_config: "TeX-AMS-MML_HTMLorMML"
```

--------------------------------

### Enable Rmd downloads for Gitbook

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Extends the 'downloads' option for the Gitbook output format to include 'rmd', allowing users to download the R Markdown source files if an edit link to Github is provided. This facilitates collaboration and content sharing.

```R
# Example in _bookdown.yml:
# output:
#   bookdown::gitbook:
#     config:
#       download: ["pdf", "epub", "rmd"]
```

--------------------------------

### Remove 'daemon' Argument from serve_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The 'daemon' argument has been removed from serve_book(). Users can now pass this argument to servr::httw() via the '...' argument.

```R
servr::httw(daemon = TRUE)
```

--------------------------------

### Configure bookdown search engine to lunr

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

This snippet shows how to configure the bookdown package to use the 'lunr' search engine for the 'gitbook' output format. This is an alternative to the default 'fuse' engine.

```yaml
output:
  bookdown::gitbook:
    config:
      search:
        engine: lunr
```

--------------------------------

### Enable Cross-referencing with Gitbook split_by

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Ensures that cross-referencing works correctly with the `gitbook` output format when using `split_by: section` or `split_by: section+number`. This improves the reliability of internal links within the book.

```R
# _bookdown.yml configuration example
# split_by: section
# output: bookdown::gitbook
# (Fix ensures cross-references work with this configuration)
```

--------------------------------

### Add 'View' Button to GitBook Toolbar

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adds an optional 'view' button to the GitBook toolbar, similar to the 'edit' and 'history' buttons. This button allows readers to view the page's source `.Rmd` file on GitHub without requiring a login or fork.

```JavaScript
// Configuration for adding 'view' button in GitBook
// (Details of implementation not provided, but functionality added)
```

--------------------------------

### Render Book Failure with rmd_files and Non-HTML/LaTeX

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes a bug where `render_book()` would fail if `rmd_files` was configured in `_bookdown.yml` and the output format was neither HTML nor LaTeX. This ensures consistent behavior across different output types.

```R
render_book(rmd_files = "_bookdown.yml")
```

--------------------------------

### Handle Long Sentences in CJK Languages

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes a bug in `bs4_book()` that caused errors when generating document descriptions for very long sentences without spaces, typically found in CJK languages. This ensures proper document description generation for all languages.

```R
bs4_book()
```

--------------------------------

### Overwrite file in fence_theorems

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Illustrates how to overwrite the input file when using the 'fence_theorems()' function by setting both 'input' and 'output' to the same file path. This addresses an issue where the 'output' argument was previously ignored.

```r
fence_theorems(input = "your_file.Rmd", output = "your_file.Rmd")
```

--------------------------------

### Add Arguments to pdf_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces new arguments toc_unnumberred, toc_appendix, toc_bib, and quote_footer to the pdf_book() function for enhanced control over PDF output generation.

```R
pdf_book(toc_unnumberred = TRUE, toc_appendix = TRUE, toc_bib = TRUE, quote_footer = "– Someone")
```

--------------------------------

### bookdown HTML Structure

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/bs4_book.html

This HTML snippet represents the basic structure of a bookdown-generated HTML page. It includes placeholders for the page title, author information, table of contents, and the main content body, along with directives for including custom CSS and JavaScript.

```HTML
<!DOCTYPE html>
<html>
<head>
$for(header-includes)$
$header-includes$
$endfor$
<title>$title$</title>
</head>
<body>
<div id="content" class="tab-content">
$body$
</div>
</body>
</html>
```

--------------------------------

### Support for unnumbered part headers

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces special syntax `# (PART\*)` for unnumbered part headers in bookdown documents. Numbered parts continue to use `# (PART)`.

```R
# Unnumbered Part
# (PART*)

# Numbered Part
# (PART)
```

--------------------------------

### Add Default Pandoc CSL CSS Dependencies

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

This update adds the same CSS as in the default Pandoc template for cases where a CSL (Citation Style Language) file is used. This provides consistent styling for citations.

```R
CSL
```

--------------------------------

### New Output Formats: rtf_document2, odt_document2, powerpoint_presentation2

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces new output formats: `rtf_document2`, `odt_document2`, and `powerpoint_presentation2`. These formats expand the capabilities for generating documents in Rich Text Format, OpenDocument Text, and Microsoft PowerPoint.

```R
bookdown::rtf_document2()
```

```R
bookdown::odt_document2()
```

```R
bookdown::powerpoint_presentation2()
```

--------------------------------

### Add abstract support to Gitbook

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Extends the `gitbook` output format to support the `abstract` field in the YAML header. This allows for a dedicated abstract section to be included in the Gitbook output.

```R
---
title: "My Book"
abstract: "This is the abstract of my book."
---

# Introduction
```

--------------------------------

### Basic Document Structure and Metadata

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/default.html

This section defines the basic structure of an R Markdown document, including placeholders for title, subtitle, authors, affiliations, emails, dates, and the abstract. It also includes logic for including the table of contents (toc) and the main document body.

```R
$if(cover-image)$$endif$
$if(description)$$endif$
$if(github-repo)$$endif$
$for(author-meta)$  $endfor$
$if(date-meta)$  $endif$
$if(title)$

$title$
=======

$if(subtitle)$

### _$subtitle$_

$endif$
$for(author)$
$if(author.name)$

#### _$author.name$_

$if(author.affiliation)$

$author.affiliation$
$endif$
$if(author.email)$
[$author.email$](mailto:#)

$endif$
$else$

#### _$author$

$endif$
$endfor$
$if(date)$

#### _$date$

$endif$

$if(abstract)$

$if(abstract-title)$$abstract-title$$else$Abstract$endif$

$abstract$

$endif$
$endif$
$if(toc)$

$toc$

$endif$
$body$
$for(include-after)$ $include-after$ $endfor$
```

--------------------------------

### HTML Document with Clean Highlight Tags Argument

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces the `clean_highlight_tags` argument to `html_document2()`. This argument controls whether HTML tags within syntax-highlighted code blocks are cleaned up, offering more control over code block presentation.

```R
bookdown::html_document2(clean_highlight_tags = TRUE)
```

--------------------------------

### Fix Footnote Rendering with KaTeX

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Addresses a problem where footnotes were not rendered correctly when `katex` was used for LaTeX math expressions. This ensures proper display of footnotes alongside mathematical content.

```R
gitbook(math = "katex")
```

--------------------------------

### Gitbook Copy to Clipboard Buttons

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adds 'copy to clipboard' buttons to code blocks in the gitbook output format. This feature enhances usability by allowing users to easily copy code snippets.

```R
bookdown::gitbook()
```

--------------------------------

### Fix render_book with output_dir = '.'

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Resolves an issue where `render_book()` did not work correctly when `output_dir` was set to the current directory (`.`). This ensures proper output generation in the current directory.

```R
bookdown::render_book(output_dir = ".")
```

--------------------------------

### Fix Resource Parsing from HTML

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Corrects an issue with parsing resources from raw HTML code, improving the handling of external assets and references within the bookdown build process.

```R
render_book()
```

--------------------------------

### Gitbook Search Highlighting Hyphenated Words

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Ensures that hyphenated words are correctly highlighted in search results within the `gitbook` output format, even when spaces are used instead of dashes in the search query (e.g., searching for 'hand off' highlights 'hand-off').

```R
bookdown::gitbook()
```

--------------------------------

### Add github_document2 Output Format

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces a new output format `github_document2`, which is a wrapper around `rmarkdown::github_document` and `markdown_document2`. This format is designed for generating GitHub-compatible Markdown documents with enhanced features.

```R
bookdown::render_book(output_format = "github_document2")
```

--------------------------------

### Identify and Move CSS Dependencies with Single Quotes

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

This fix correctly identifies and moves CSS dependencies that use single quotes, such as `url('truetype/Spectral-ExtraLight.ttf')`. This ensures that all necessary CSS assets are properly included in the output.

```R
url('truetype/Spectral-ExtraLight.ttf')
```

--------------------------------

### Add context_document2 Output Format

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces a new output format `context_document2`, which is based on the `rmarkdown::context_document` function. This provides enhanced capabilities for context-aware document generation.

```R
bookdown::render_book(output_format = "context_document2")
```

--------------------------------

### General Document Styling and Layout

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/default.html

This CSS snippet sets general document styling, including the maximum width for the main container, auto margins for centering, and styles for code blocks (color inheritance and subtle background). It also ensures images are responsive and adds styling for collapsible 'details' elements.

```CSS
.main-container {
  max-width: 940px;
  margin-left: auto;
  margin-right: auto;
}
code {
  color: inherit;
  background-color: rgba(0, 0, 0, 0.04);
}
img {
  max-width:100%;
  height: auto;
}
/* show arrow before summary tag as in bootstrap TODO: remove if bootstrap in updated in html_document (rmarkdown#1485) */
details > summary {
  display: list-item;
  cursor: pointer;
}
```

--------------------------------

### Gitbook Toolbar Icon Alt/Hover Text

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adds alternative text (alt text) and hover text to icons on the `gitbook` toolbar. This improves accessibility and user experience by providing descriptive information for toolbar elements.

```R
bookdown::gitbook()
```

--------------------------------

### Ensure gitbook extra_dependencies Work

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an issue where `extra_dependencies` in `gitbook()` was not correctly applied. This ensures that custom JavaScript or CSS files added via `extra_dependencies` are properly included in the output.

```R
gitbook(extra_dependencies = list(htmltools::htmlDependency(...)))
```

--------------------------------

### Customizable Abstract Title in HTML Output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Allows customization of the abstract title for HTML output formats like `gitbook` via the `abstract-title` field in the YAML frontmatter. This provides greater control over document presentation.

```yaml
---
abstract-title: "My Custom Abstract Title"
---

```

```R
bookdown::gitbook()
```

--------------------------------

### Gitbook Search Functionality Improvements

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enhances the search functionality in `gitbook` output. This includes fixing issues with keyword highlighting, persistence of search terms across pages, and ensuring keybindings work correctly for navigation within search results.

```R
bookdown::gitbook()
```

--------------------------------

### Enable Split Bibliography in BS4 Book

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Shows how to enable split bibliography for the bookdown::bs4_book format, displaying references at the end of each chapter.

```R
bs4_book(splib_bib = TRUE)
```

--------------------------------

### Define Abstract Styling

Source: https://github.com/rstudio/bookdown/blob/main/inst/templates/default.html

This CSS defines styles for abstract sections, including text alignment and font weight for the abstract title, and margin adjustments for the abstract container.

```CSS
p.abstract {
  text-align: center;
  font-weight: bold;
}
div.abstract {
  margin: auto;
  width: 90%;
}
```

--------------------------------

### Equation Rendering in Fenced Code Blocks

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Corrects an issue in `word_document2`, `powerpoint_presentation2`, and `odt_document2` output formats where `$$` was incorrectly added to equation environments within fenced code blocks. This ensures cleaner output for documents with embedded code and equations.

```R
bookdown::word_document2()
```

```R
bookdown::powerpoint_presentation2()
```

```R
bookdown::odt_document2()
```

--------------------------------

### Suppress stdout in serve_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces the 'quiet' argument to the serve_book() function, allowing users to suppress standard output messages during book serving. This can be useful for cleaner logs or when running in automated environments.

```R
bookdown::serve_book(quiet = TRUE)
```

--------------------------------

### bs4_book Theme Styling

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces style changes for the `bs4_book()` theme, specifically for code blocks within callout blocks. These code blocks will now have their background fill the entire width of the bordered block, improving visual consistency.

```CSS
.callout-code-block {
  background-color: #f8f9fa; /* Example background color */
  width: 100%;
}
```

--------------------------------

### Configure preview mode cutoff for render_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces a global option 'bookdown.preview.cutoff' to control the preview mode of render_book(). When a chapter's line count is less than or equal to this cutoff, the full chapter is included; otherwise, only section titles are shown.

```R
# Set the global option
options(bookdown.preview.cutoff = 50)

# Render the book with preview
bookdown::render_book(preview = TRUE)
```

--------------------------------

### Synchronize rmd_files and rmd_subdir parameters

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an issue where the `rmd_files` parameter in `_bookdown.yml` would override `rmd_subdir`. Now, both parameters can be used simultaneously, providing more flexible control over Rmd file inclusion.

```R
# Example in _bookdown.yml:
# rmd_subdir: true
# rmd_files: ["chapter1.Rmd", "chapter2.Rmd"]
```

--------------------------------

### Order Rmd Subdirectories Correctly

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an issue where subdirectories specified in `rmd_subdir` were always alphabetically ordered. Now, they follow the order defined in the `rmd_subdir` configuration.

```R
# _bookdown.yml configuration example
# rmd_subdir: ["chapter1/", "chapter3/", "chapter2/"]
# (Fix ensures chapters are processed in the specified order)
```

--------------------------------

### Handle book_filename with dots

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an issue where the book could not be rendered properly if the 'book_filename' option in '_bookdown.yml' contained a dot. This ensures correct file naming and rendering.

```R
# Example in _bookdown.yml:
# book_filename: "my.book.v1"
```

--------------------------------

### Deprecate clean_envir Argument in render_book()

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `clean_envir` argument in `bookdown::render_book()` has been deprecated and will be removed in future versions. Users should be aware of this change and adjust their workflows accordingly.

```R
bookdown::render_book(clean_envir = TRUE)
```

--------------------------------

### Correct Sidebar Transition Background Color

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

In sepia or night mode, the background color during sidebar transitions is now correct and no longer white. This improves the visual consistency of the book's theme.

```R
sepia mode
night mode
```

--------------------------------

### Add history button to Gitbook toolbar

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enables the addition of a 'history' button to the Gitbook toolbar, providing users with access to the Git history of source files. This feature aids in tracking changes and understanding the evolution of content.

```R
# Example usage (conceptual, actual implementation might vary)
# bookdown::gitbook(toolbar = list(history = TRUE))
```

--------------------------------

### Fix bookdown_site YAML Comment Issue

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Addresses an issue where comments in the `site:` line of YAML data were not supported in `bookdown_site()`. This fix ensures that the root directory of the book is correctly identified even with comments present.

```YAML
site: bookdown::bookdown_site # This is a comment
```

--------------------------------

### Enable Math Expressions in Gitbook Table of Contents

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes an issue where math expressions were not appearing in the table of contents for gitbook output, ensuring proper rendering of mathematical notation.

--------------------------------

### Fix HTML Output File Movement

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Corrects an issue where the HTML output file was not moved to the output directory when the 'split_by' option was set to 'none' in bookdown::gitbook or bookdown::html_book.

```R
bookdown::gitbook(split_by = "none")
```

--------------------------------

### Fix gitbook Search Index Generation

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Resolves a bug where `gitbook()` might generate an empty search index on certain platforms. This ensures that the search functionality is consistently available and populated.

```R
gitbook()
```

--------------------------------

### Adapt epub_book for Pandoc 3+

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Adjusts an internal command-line argument passed to Pandoc for the `epub_book()` format to accommodate changes in Pandoc versions 3.0 and above. This ensures compatibility with newer Pandoc releases.

```R
epub_book()
```

--------------------------------

### Enable Code Folding in gitbook

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `code_folding` argument for the `gitbook()` output format is now functional, allowing users to enable or disable code folding in the generated HTML output. This feature helps in managing the display of code chunks.

```R
gitbook(code_folding = "show")
```

--------------------------------

### Improve Text References for HTML and Word Output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Enhances the functionality of text references to work reliably for both HTML and Word output formats.

```markdown
See section \ref{sec:intro} for more details.
```

--------------------------------

### Post-process LaTeX output with a function

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Allows post-processing of LaTeX output for the pdf_book format by setting the global R option 'bookdown.post.latex' to a custom function. This enables fine-grained control over the generated LaTeX code.

```R
# Define a post-processing function
my_latex_postprocessor <- function(latex_string) {
  # Modify the latex_string here
  return(latex_string)
}

# Set the global option
options(bookdown.post.latex = my_latex_postprocessor)

# Render the PDF book
bookdown::pdf_book()
```

--------------------------------

### Handle before/after_chapter_script in Knit-and-Merge

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Improves the Knit-and-Merge approach (`new_session: true`) by ensuring that `before_chapter_script` and `after_chapter_script` are evaluated separately without modifying the original Rmd files. This maintains correct line numbers for knitr errors.

```R
# _bookdown.yml configuration example
# new_session: true
# before_chapter_script: "scripts/setup.R"
# after_chapter_script: "scripts/cleanup.R"
# (Fix ensures scripts are evaluated correctly without altering Rmds)
```

--------------------------------

### Handle File Renaming Across Volumes

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes a bug where `render_book()` failed due to `file.rename()` being unable to rename files across different disk volumes. This ensures smoother operation when dealing with files on different drives.

```R
render_book()
```

--------------------------------

### Customize bookdown Labels with Functions

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `label` fields (`fig`, `tab`, `eq`) in `_bookdown.yaml` can now accept a function for `ui` fields like `chapter_name` and `appendix`. This function takes the reference number and returns a character string for the label, offering greater flexibility for internationalization.

```YAML
_bookdown.yaml:
  label:
    fig: "Figure {number}"
    tab: "Table {number}"
    eq: "Equation {number}"
  ui:
    chapter_name: !expr function(n) paste0("Chapter ", n)
    appendix: !expr function(n) paste0("Appendix ", n)
```

--------------------------------

### Control Line Spacing in gitbook

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Introduces a new option in the `gitbook` font settings menu to control line spacing. This enhances the readability and customization of the generated HTML output.

```R
gitbook(fontsettings = TRUE)
```

--------------------------------

### Gitbook Sidebar Filtering for Search Results

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Improves the `gitbook` sidebar to only display relevant Table of Contents (TOC) items that link to HTML pages containing the search keyword. This makes navigation more efficient by filtering out irrelevant TOC entries.

```R
bookdown::gitbook()
```

--------------------------------

### Configure Rmd Subdirectory Handling

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Configures bookdown to correctly locate and process R Markdown files within subdirectories by setting the 'rmd_subdir' option to true in the _bookdown.yml configuration file.

```yaml
rmd_subdir: true
```

--------------------------------

### Deprecate kindlegen() Function

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `kindlegen()` function has been deprecated because Amazon no longer provides KindleGen. Users are advised to consider using `bookdown::calibre()` for `.mobi` output instead.

```R
bookdown::kindlegen()
bookdown::calibre()
```

--------------------------------

### Handle Rmd Files Option in _bookdown.yml

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Fixes the 'rmd_files' option in _bookdown.yml when it is specified as a list containing both 'html' and 'latex' options, ensuring correct file processing for different output formats.

```yaml
rmd_files:
  html: [index.Rmd, intro.Rmd]
  latex: [index.Rmd, intro.Rmd]
```

--------------------------------

### Include .md Files in Search

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

A new configuration setting `include_md` allows users to control whether `.md` source files are included in the input search, in addition to `.Rmd` files. This improves the search functionality for projects with mixed markdown file types.

```R
gitbook(include_md = TRUE)
# or in YAML:
# output:
#   bookdown::gitbook:
#     include_md: TRUE
```

--------------------------------

### Transform Implicit Label in fenced_theorems() to Fenced Divs ID

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

The `fenced_theorems()` function now correctly transforms implicit labels in chunk headers into fenced divs IDs. This improves the handling of theorem and proof environments, especially when using Pandoc's fenced divs syntax.

```R
fenced_theorems()
```

--------------------------------

### Multiple Labels on Same Line for Word Output

Source: https://github.com/rstudio/bookdown/blob/main/NEWS.md

Allows multiple labels to be placed on the same line for Word output. This provides more flexibility in document structuring and referencing.

```R
bookdown::word_document2()
```