documentation on toc depth

[statnmap]

I see in the documentation that we can define the toc depth in articles: https://pkgdown.r-lib.org/reference/build_articles.html
I tried to add this option directly in my _pkgdown.yml, also in the yaml header of my vignette, but it seems there is no effect.
Could you add a little more information in the documentation of this "build_articles()" function to know exactly where to add this option ?

[statnmap]

If I explore the code of function, the only place I can see the source of toc_depth is through pkg$meta$toc$depth:

pkgdown/R/build-articles.R

Line 304 in 42dbedc

toc_depth = pkg$meta$toc$depth %||% 2,

which means that the information should be added in _pkgdown.yml as follows:

toc:
  depth: 3

This is what I did, but there is no effect on the TOC in pkgdown.
You can try the following reprex:

# Create fake package
temp_dir <- tempdir()
pkg_path <- file.path(temp_dir, "fake.pkg")
dir.create(pkg_path)
usethis::create_package(path = pkg_path, open = FALSE)

# Create meta yaml
yaml_file <- file.path(pkg_path, ".pkgdown.yml")
cat("toc:
  depth: 4", file = yaml_file)

# Create vignette with multiple titles
dir.create(file.path(pkg_path, "vignettes"))
cat('---
title: "Title"
author: "Sébastien Rochette"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\\VignetteIndexEntry{Title}
  %\\VignetteEngine{knitr::rmarkdown}
  %\\VignetteEncoding{UTF-8}
---
    
# Title 1a  

## Title 2a  

### Title 3a  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

### Title 3b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

## Title 2b
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

# Title 1b  

## Title 2a  

### Title 3a  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

### Title 3b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

## Title 2b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

# Title 1c  

## Title 2a  

### Title 3a
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

#### Title 4a
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

#### Title 4b
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

#### Title 4a
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

### Title 3b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

## Title 2b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

', file = file.path(pkg_path, "vignettes", "my_vignette.Rmd"))


# Build pkgdown
pkgdown::build_site(pkg = pkg_path)

This always conduct to a TOC of depth 2

[jayhesselberth]

This option has no effect because bootstrap-toc now generates the TOC. We should remove the option.

You might be able to achieve the behavior by modifying the TOC scope; you would place relevant code in pkgdown/extra.js.

[statnmap]

Thank you for the answer. I am not enough comfortable with Javascript.
I write my modified reprex here, and we'll see later if I find a solution.

# Create fake package
temp_dir <- tempdir()
pkg_path <- file.path(temp_dir, "fake.pkg")
dir.create(pkg_path)
usethis::create_package(path = pkg_path, open = TRUE)

# Create meta yaml
yaml_file <- file.path(pkg_path, ".pkgdown.yml")
cat("toc:
  depth: 4", file = yaml_file)

# Create vignette with multiple titles
dir.create(file.path(pkg_path, "vignettes"))
cat('---
title: "Title"
author: "Sébastien Rochette"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\\VignetteIndexEntry{Title}
  %\\VignetteEngine{knitr::rmarkdown}
  %\\VignetteEncoding{UTF-8}
---
    
# Title 1a  

## Title 2a  

### Title 3a  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

### Title 3b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

## Title 2b
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

# Title 1b  

## Title 2a  

### Title 3a  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

### Title 3b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

## Title 2b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

# Title 1c  

## Title 2a  

### Title 3a
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

#### Title 4a
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

#### Title 4b
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

#### Title 4a
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

### Title 3b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

## Title 2b  
', paste(sample(c(" ", letters), 300, replace = TRUE), collapse = "") , '

', file = file.path(pkg_path, "vignettes", "my_vignette.Rmd"))

# Change TOC
dir.create(file.path(pkg_path, "pkgdown"))
cat('(function($) {
$(function() {
  var navSelector = "#toc";
  var $myNav = $(navSelector);
  Toc.init({$scope: $("h3")});
  $("body").scrollspy({
    target: navSelector
  });
});
})(window.jQuery || window.$);
', file = file.path(pkg_path, "pkgdown", "extra.js"))



# Build pkgdown
pkgdown::build_site(pkg = pkg_path)

[maelle]

@statnmap bootstrap-toc doesn't support more than two levels in the TOC afeld/bootstrap-toc#27 so unless pkgdown no longer uses bootstrap-toc one day, it is not possible to change the TOC depth.

[moodymudskipper]

FYI @maelle the vignette still says it's possible : https://pkgdown.r-lib.org/reference/build_articles.html

[jayhesselberth]

@moodymudskipper those changes will only appear in the dev docs for now: https://pkgdown.r-lib.org/dev/reference/build_articles.html

[salim-b]

bootstrap-toc doesn't support more than two levels in the TOC afeld/bootstrap-toc#27 so unless pkgdown no longer uses bootstrap-toc one day, it is not possible to change the TOC depth.

There are several PRs that attempt to implement a depth > 2 in bootstrap-toc:

• Add ability for user to set depth limit by adding data-levels="#" afeld/bootstrap-toc#36
• API: add depth option afeld/bootstrap-toc#37
• Depth setting afeld/bootstrap-toc#52

But no reaction on those from the author. The project appears to basically be deprecated/unmaintained for several years now.

So the best way forward would probably be to

1. completely drop bootstrap-toc
2. let the ToC markup be generated by pkgdown (with the additional upside of making it appear for site visitors with JS disabled)
3. use Bootrap's native scrollspy functionality.