TOC Generation for (R) Markdown Documents • tocr

tocr allows to automatically add/update/remove a table of contents (TOC) to/from an (R) Markdown document. Internal links are compatible with HTML “anchors”, commonly referred to as “# links” pointing to HTML fragment identifiers generated by sites like GitHub or GitLab when rendering the Markdown. tocr supports backlinks to ease navigation within large documents as well as other options to tailor the TOC to specific needs. It can also convert a wide range of similar auto-generated TOC formats to its own one.

Details

tocr uses the following two HTML comments to mark the beginning and end of an auto-generated TOC:

<!-- TOC BEGIN -- leave this comment untouched to allow auto update -->

<!-- TOC END -- leave this comment untouched to allow auto update -->

tocr::add_toc() supports the comment format of other similar software like doctoc. If you stumble upon software-generated Markdown TOCs which aren’t recognized by tocr::add_toc(), feel free to file an issue or even add support for it on your own and submit a merge request.

Installation

To install the latest development version of tocr, run the following in R:

if (!("remotes" %in% rownames(installed.packages()))) {
  install.packages(pkgs = "remotes",
                   repos = "https://cloud.r-project.org/")
}

remotes::install_gitlab(repo = "rpkg.dev/tocr")

Usage

An introduction to this package is given here. The (function) reference is found here.

Development

R Markdown format

This package’s source code is written in the R Markdown file format to facilitate practices commonly referred to as literate programming. It allows the actual code to be freely mixed with explanatory and supplementary information in expressive Markdown format instead of having to rely on # comments only.

All the .gen.R suffixed R source code found under R/ is generated from the respective R Markdown counterparts under Rmd/ using pkgpurl::purl_rmd()¹. Always make changes only to the .Rmd files – never the .R files – and then run pkgpurl::purl_rmd() to regenerate the R source files.

Coding style

This package borrows a lot of the Tidyverse design philosophies. The R code adheres to the principles specified in the Tidyverse Design Guide wherever possible and is formatted according to the Tidyverse Style Guide (TSG) with the following exceptions:

Line width is limited to 160 characters, double the limit proposed by the TSG (80 characters is ridiculously little given today’s high-resolution wide screen monitors).

Furthermore, the preferred style for breaking long lines differs. Instead of wrapping directly after an expression’s opening bracket as suggested by the TSG, we prefer two fewer line breaks and indent subsequent lines within the expression by its opening bracket:
```
# TSG proposes this
do_something_very_complicated(
  something = "that",
  requires = many,
  arguments = "some of which may be long"
)

# we prefer this
do_something_very_complicated(something = "that",
                              requires = many,
                              arguments = "some of which may be long")
```
This results in less vertical and more horizontal spread of the code and better readability in pipes.
Usage of magrittr’s compound assignment pipe-operator %<>% is desirable².
Usage of R’s right-hand assignment operator -> is not allowed³.
R source code is not split over several files as suggested by the TSG but instead is (as far as possible) kept in the single file Rmd/tocr.Rmd which is well-structured thanks to its Markdown support.

As far as possible, these deviations from the TSG plus some additional restrictions are formally specified in the lintr configuration file .lintr, so lintr can be used right away to check for formatting issues:

pkgpurl::lint_rmd()

tocr