How to add table of contents in Rmarkdown?

Question

I am using RStudio for writing markdown documents and want to add Table of Contents (TOC) at top of the documents so that the user could click the relevant section for reading. There were some relevant examples on rpubs but now I can't seem to find them. Please note that I don't use pandoc and am quite new to Rmd & knitr. Is there any way to add TOCs without using pandoc? If using pandoc is must then which functions are relevant?

EDIT

Here's a small sample page:

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
---

Header 1
---------------
This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
    
## Header 2
When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
    
```{r}
summary(cars)
```

You can also embed plots, for example:

```{r, echo=FALSE}
plot(cars)
```
### Header 3
Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.

I tried running this in RStudio v 0.98.864 and it worked! but sadly it didn't work on 0.98.501 and 0.98.507. I am working on my thesis in 0.98.501 and after updating RStudio, some of my analyses didn't work. So, I reverted back to 0.98.501. What should I do now? I really want TOCs but without harming the outputs of other analyses.

I believe the rmarkdown package used by Rstudio is a wrapper around pandoc, so you should be able to pass the relevant option. In fact, `toc: true` in the YAML front-matter should do it. — baptiste, May 30 '14 at 16:30
@baptiste Please pardon my ignorance. What do you mean by 'YAML'? Where am I supposed to add the `toc: true` option, in knitr global options? — umair durrani, May 30 '14 at 17:07
I put `--- title: "Sample Document" output: html_document: toc: true theme: united ---` at the very top of my Rmd document but after pressing knit HTML no TOC was generated. Am I missing something? — umair durrani, May 30 '14 at 17:23
try indenting, following the examples in http://rmarkdown.rstudio.com/ and updating Rstudio if everything else fails — baptiste, May 30 '14 at 18:30
@umairdurrani Ok. the sample doesn't have any headers. What do you want to be in the table of contents? — MrFlick, May 31 '14 at 06:02
it sounds like the problem is the version of Rstudio; what problems did you encounter specifically with the newest release? — baptiste, May 31 '14 at 13:28
With the newest release the global chunk options give error. If I remove them, it seems to work (didn't wait till end because without `cache=TRUE` analyses take long to complete). Also, I don't want to risk working with a preview release software. — umair durrani, May 31 '14 at 23:33
thanks @baptiste, I had a problem with this as well, but indenting properly fixed it. — Alex, Jul 12 '16 at 06:13
I had the same problem but after some tries I realized that your document has to start with this chunk, LITERALLY. I had it initially after the libraries' loading and it was failing. I hope it helps. — Yannis, Feb 16 '17 at 10:33

MrFlick · Accepted Answer · 2019-05-20T19:24:45.857

110

The syntax is

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
---

in the documentation. Make sure this is at the beginning of your document. Also make sure your document actually has headers otherwise R can't tell what you want in the table of contents.

edited May 20 '19 at 19:24

answered May 30 '14 at 20:53

MrFlick

195,160
17
277
295

2

This is is the exact same thing that I put on top of Rmd file (before the title) and clicked knit HTML. The resulting document has no table of contents and was created without any error. Is there any other option to change some where? – umair durrani May 30 '14 at 23:13
2

I have now tried RStudio versions 0.98.501, .507 and .897 (preview release), but this metadata thing didn't work. – umair durrani May 31 '14 at 00:01
1

@umairdurrani can you edit your question to include a small, sample document that doesn't work for you. That way we can try the exact same thing to see what happens. – MrFlick May 31 '14 at 00:19

Manoj Kumar · Answer 2 · 2020-06-19T17:47:00.470

96

Syntax with more options:

---
title: "Planets"
author: "Manoj Kumar"
date: "`r format(Sys.time(), '%B %d, %Y')`"
output: 
  html_document:
    toc: true # table of content true
    toc_depth: 3  # upto three depths of headings (specified by #, ## and ###)
    number_sections: true  ## if you want number sections at each table header
    theme: united  # many options for theme, this one is my favorite.
    highlight: tango  # specifies the syntax highlighting style
    css: my.css   # you can add your custom css, should be in same folder
---

edited Jun 19 '20 at 17:47

answered Mar 03 '16 at 11:30

Manoj Kumar

5,273
1
26
33

4

I think this is `toc_depth` instead of `depth` – F. Privé Jul 13 '17 at 10:16
1

@F.Privé I wrote this answer some 1 year ago. Not sure if the package has made these changes. Thanks for update. – Manoj Kumar Jul 14 '17 at 19:04
1

How to add a click in each section to return back to TOC? thanks – Daniel Aug 13 '18 at 23:47
2

@Daniel - Try using anchor link HTML such as : ` Back To Top ` at the location (the lines of code) where you want it to appear. Hope this works. – Manoj Kumar Aug 14 '18 at 20:38
1

this is best answer... – LeMarque Aug 02 '23 at 05:36

score 42 · Answer 3 · answered May 14 '18 at 12:35

If you are using pdf_document, you might want to add table of contents in a new page, which toc: true does not allow. It puts the table of contents right after the document title, author and date--because it is in yaml.

If you want to have it in a new page, you have to use some latex language. Here is what I did.

---
title: \vspace{3.5in}"Title"
author: "Name"
date: "`r Sys.Date()`"
output:
   pdf_document:
      fig_caption: true
      number_sections: true
---

\newpage # adds new page after title
\tableofcontents # adds table of contents
\listoffigures
\listoftables
\newpage

So, after yaml (the chunk between ---), I added a new page using \newpage, then a table of contents using \tableofcontents, a list of figures using \listoffigures, a list of tables \listoftables, and a new page before everything else.

Note, \vspace{3in} in the title adds vertical space of 3 inch from the top before printing yaml (title, etc.).

Read more here: https://www.sharelatex.com/learn/Table_of_contents

How to add table of contents in Rmarkdown?

EDIT

3 Answers3

Linked

Related