-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
93 lines (71 loc) · 2.89 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
---
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",
"[]",
"(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.