Preserve toc:true in YAML front matter for Hugo

The Academic theme for Hugo has support for automatic tables of contents when using the docs page type. (See their live example here.)

By enabling toc: true in the YAML front matter of a document page (i.e. with type: docs), a TOC appears on the right side of the page.

However, this seems to only work on vanilla .md files. If you enable this on an R Markdown page, the TOC area is empty and there's an errant "true" under the title, presumably because the toc: true from the YAML front matter somehow gets partially rendered as HTML

Is there a way to use Hugo / Academic's automatic ToC creation with R Markdown files? It seems like this might be a bug, since the YAML value appears in the HTML, but I'm not sure where to even start debugging.

This is reproducible by doing the following:

  1. Create a new example blogdown/Hugo site with the academic theme:

     blogdown::new_site(theme = "gcushen/hugo-academic", theme_example = TRUE)
  2. Rename content/courses/example/ to content/courses/example/example2.Rmd

  3. Run blogdown:::serve_site() and go to http://localhost:4321/courses/example/example1/ and http://localhost:4321/courses/example/example2/ and note the differences.

The only workaround I've found is to not use Hugo's TOC capabilities (by removing the toc: BLAH entry entirely) and instead include this in the YAML front matter:

    toc: true

This add knitr's own TOC at the top of the page, but not in the sidebar, which is less than ideal.


This seems to be related to an earlier issue with citations in Hugo and R Markdown. Blogdown uses pandoc with .Rmd files and Hugo's (new) goldmark markdown renderer for .Rmarkdown and .md files.

It's likely that goldmark does the magical TOC generation, so I could ostensibly use .Rmarkdown, but then I lose the ability to do pandoc things like citations (see this table in the blogdown documentation)


As an aside, welcome to the fun that is keeping up with the many disruptive updates to this theme (not to mention the updates to Hugo!).

You have a couple options that I know of.

You can use blogdown to render a TOC at the top of the page with this in the YAML:

  toc: true

Or if you want to use the more flexible default Hugo processor (which is it now?) via .Rmarkdown, you can put the shortcode {{% toc %}} somewhere, for which no YAML is needed as far as I can tell. I should say though that I had some issues with the appearance of the TOC but it may have been due to changes I had made to the theme.

1 Like

I've succeeded by saving the file as .Rmarkdown AND using the toml syntax instead of the YAML, an example.

title = "1 article"
date = 2019-12-21
toc = true  # Show table of contents? true/false
type = "docs"  # Do not modify.
    parent = "blog"
    weight = 20

This topic was automatically closed 21 days after the last reply. New replies are no longer allowed.