Preserve toc:true in YAML front matter for Hugo

[andrewheiss]

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/example2.md 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:

output:
  blogdown::html_page:
    toc: true

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

[andrewheiss]

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)

Maybe?

[jacob]

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:

blogdown::html_page: 
  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.

[rosingle]

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.
[menu.courses]
    parent = "blog"
    weight = 20
+++