README.Rmd

---
output: pal::gitlab_document
---

```{r}
#| label: init
#| include: false

knitr::opts_knit$set(root.dir = getwd())
```

# `r pal::desc_value("Package")`

```{r}
#| label: pkg-desc
#| child: !expr pkgsnip::snip_path("pkg-desc.Rmd")
```

## Details

tocr uses the following two [HTML comments](https://www.w3schools.com/TAGS/tag_comment.asp) to mark the beginning and end of an auto-generated TOC:

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

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

`tocr::add_toc()` supports the comment format of [other similar software](#see-also) like [doctoc](https://github.com/thlorenz/doctoc). If you stumble upon
software-generated Markdown TOCs which aren't recognized by `tocr::add_toc()`, feel free to [file an issue](http://gitlab.com/rpkg.dev/tocr/issues) or even add
support for it on your own and submit a [merge request](https://gitlab.com/rpkg.dev/tocr/merge_requests).

```{r}
#| label: pkg-doc
#| eval: !expr '!isTRUE(getOption("pal.build_readme.is_pkgdown"))'
#| results: asis
#| echo: false

pkgsnip::md_snip(id = "pkgdown_site") %>%
  paste0("## Documentation\n\n",
         "[![Netlify Status](https://api.netlify.com/api/v1/badges/0bb75d33-429c-4295-8de9-94a11ebc27d2/deploy-status)]",
         "(https://app.netlify.com/sites/tocr-rpkg-dev/deploys)\n\n",
         .) %>%
  pal::cat_lines()
```

## Installation

```{r}
#| label: pkg-instl-dev
#| child: !expr pkgsnip::snip_path("pkg-instl-dev-gitlab.Rmd")
```

```{r}
#| label: pkg-usage
#| eval: !expr isTRUE(getOption("pal.build_readme.is_pkgdown"))
#| results: asis
#| echo: false

pkgsnip::md_snip(id = "pkg_usage") %>%
  paste0("## Usage\n\n", .) %>%
  pal::cat_lines()
```

## Development

### R Markdown format

```{r}
#| label: pkgpurl
#| child: !expr pkgsnip::snip_path("pkgpurl.Rmd")
```

### Coding style

```{r}
#| label: pkg-code-style
#| child: !expr pkgsnip::snip_path("pkg-code-style.Rmd")
```

## See also {#see-also}

-   [doctoc](https://github.com/thlorenz/doctoc) for a similar solution to add TOCs to Markdown documents implemented in JavaScript. It served as some sort of
    inspiration for tocr.
-   [Markdown TOC](https://github.com/nok/markdown-toc) for an [Atom](https://atom.io/) package that auto-generates TOCs.
-   [remark-toc](https://github.com/remarkjs/remark-toc) for a TOC generator plugin for the JavaScript-based Markdown processor
    [remark](https://github.com/remarkjs/remark).
-   [Tocdown](https://github.com/dohliam/tocdown) for another Markdown TOC generator written in JavaScript and Ruby.
-   [`render_toc()`](https://gist.github.com/gadenbuie/c83e078bf8c81b035e32c3fc0cf04ee8) by Garrick Aden-Buie, a simple function to extract headers from an (R)
    Markdown document and build a TOC. [This blog post](https://www.garrickadenbuie.com/blog/add-a-generated-table-of-contents-anywhere-in-rmarkdown/) provides
    some background.