TOC Flashes and Disappears

[mrkaye97]

I can't reprex this, but for my blogdown site, I've been playing around with a bunch of different ways of specifying the TOC in the YAML, but it seems like every combination I try ends up with the TOC flashing and then disappearing. It's the same issue referenced in this SO post. I'm not sure if this is a blogdown issue, a Hugo issue, or a theme issue, but the TOC seems to work fine in example_post.md but fails for example_post.Rmd, as in: I can use a TOC fine in pure markdown, but it's flashing and then disappearing in Rmarkdown, and I'm not sure why.

Has anyone else run into this issue and found a fix? I've tried a bunch of different ideas in the YAML already per @yihui's suggestions in other issues and SO posts, and no dice.

[cderv]

Hi @mrkaye97,

We understand you did not manage to create a reprex however, can you share some details on what you are trying to do ?

The SO post you linked to is about html_document and I believe is not really an issue, it is just header used for tabset pane won't be shown in the TOC.

Also,

the TOC seems to work fine in example_post.md but fails for example_post.Rmd

What are you using for the TOC ?
I ask because with blogdown a post with .md extension will be rendered by Hugo directly whereas a post with .Rmd will be rendered by Pandoc using rmarkdown. It is possible you are trying to use a feature only supported by Hugo and not Pandoc.

Can you share more details on this issue you encounter so that we can look into it more ?
Without more information, we can't say much unfortunately.

[mrkaye97]

@cderv thanks for getting back on this! Here's a screen recording of how it looks:

toc.recording.mov

The flash and disappearance of the TOC happens on the RHS. I tried to slow-mo it but wasn't sure how to. You might need to watch it a couple of times. I think it looks worse in an actual browser (as opposed to when it's server locally. probably a response time thing).

The R Script in that test ^ is just:

# TOC Test 1
# TOC Test 2
## TOC Subitem 1

I've tried a few different things for the YAML. This is how it is set up for the recording:

---
title: toc_test
author: Matt Kaye
date: '2021-01-11'
slug: []
categories: []
tags: []
lastmod: '2021-01-11T16:04:45-07:00'
keywords: []
description: ''
comment: no
toc: yes
autoCollapseToc: no
postMetaInFooter: no
hiddenFromHomePage: no
contentCopyright: no
reward: no
mathjax: no
mathjaxEnableSingleDollar: no
mathjaxEnableAutoNumber: no
hideHeaderAndFooter: no
flowchartDiagrams:
  enable: no
  options: ''
sequenceDiagrams:
  enable: no
  options: ''
---

I've also tried this:

output:
  blogdown::html_page:
    toc: true

and this:

output: 
  html_document:
    toc: true
    toc_float: true
    smart: false

And I think a few others (can't remember all of them). I've also tried making the extension on the file .Rmarkdown instead of .Rmd, but that doesn't seem to work either.

Let me know if you have any ideas! I think that the feature not being supported by Pandoc is a good guess. Is there any way to make blogdown pages knit from Rmd to markdown directly and then display them like that?

[cderv]

@mrkaye97 Just to be sure to understand correctly: is this toc feature you want to use part of a specific them you are using ? or is it the same toc that you can have using html_document ?
I think it is the former as you are trying to set the toc in the YAML header first level. Which theme do you use ?

I see a flash in your video but can't really see what it should looks like.

Regarding .Rmd to .md, there is a new method = "markdown" for that in the last version of blogdown but it would be the same ad using .Rmarkdown - so if it does not work as you wish with .Rmarkdown, it won't change.

I think this could be theme related so I need to have more info as I don't have a reproducible example. Thanks.

BTW:

• Using html_document won't have any effect. Only html_page format is used with rmarkdown
• Using html_page will change the option for the format and setting toc-true will activate a table of content at the top of a post, which is inserted by Pandoc. Not sure that is what you want.

[mrkaye97]

@cderv Honestly, I'm not sure if it's part of the theme or just whatever I can do using html_document, but I think you're right that it's the former. The theme is Even, which is here. What happens with the flash is it just shows up as a box saying "Contents" with nothing else in it, and then it goes away right away. The box looks the same as it would if it were actually showing any contents (which it should be, but for now it just shows the Contents header and no items). I'll try out html_page and report back. Thanks!

[cderv]

Thanks. Knowing the theme helps a lot as I found what I needed to check. It corresponds to what I thought you were using.

You are indeed using a feature of Hugo which is that the Hugo's Markdown Parser Goldmark can parse a Table of content to be used in a template. See https://gohugo.io/content-management/toc/
The theme you choose supports it (https://github.com/olOwOlo/hugo-theme-even/blob/da4320e8a56343ad37a4604e61915675fa18a270/layouts/partials/post/toc.html#L6) but it means you need to rely only on Hugo's Markdown to render to HTML with Goldmark and not Pandoc.

I tested quickly on a new site using your theme and I can reproduce the flashing when using .Rmd file. This is because Rmd to Html is done with Pandoc by default. You need to use .Rmarkdown - I tested and it works.

BTW the configuration for the toc in this theme, following their exampleSite, is

autoCollapseToc: true

either per post in the YAML or for the all site in the config file.

Also for such theme, you could be interested in the method = "markdown" mode that will only use Hugo renderer for Markdown. You can set the option blogdown.method to this value in the .Rprofile to activate this mode. All the .Rmd will behave like .Rmarkdown and render as .md document.

Happy to explain more if you have some issue with that still. In the meantime, I close this issue as we now know the why.

[mrkaye97]

Thanks @cderv! I'll give it a test drive later and let you know how it goes

[yihui]

Yes, I think the solution is to either use the file extension .Rmarkdown instead of .Rmd, or set options(blogdown.method = 'markdown') in your .Rprofile.

Without that, it is possible to make it work, but it would require the theme author's support. I think I know how to do it (e.g., TOC works for the hugo-prose theme no matter what your file extension or build method is), but it has to be done on a theme by theme basis, and I can't provide a universal solution.

[mrkaye97]

So, some good news and some bad news:

Good news: using the .Rmarkdown extension instead of .Rmd worked! The TOC renders now

Bad news: It seems like mathjax isn't working with .Rmarkdown? I've read through this so I've tried putting backticks around math like `$math$` and `$$more_math$$`, but that doesn't seem to work. It's just showing up as the raw LaTeX. I also tried following @yihui's instructions in this issue. This is the YAML header right now:

---
title: Test Article
author: Matt Kaye
date: '2021-01-13'
slug: []
categories: []
tags: []
lastmod: '2021-01-13T18:53:40-07:00'
keywords: []
description: ''
comment: no
toc: yes
autoCollapseToc: yes
postMetaInFooter: no
hiddenFromHomePage: no
contentCopyright: no
reward: no
mathjax: yes
mathjaxEnableSingleDollar: yes
mathjaxEnableAutoNumber: yes
hideHeaderAndFooter: no
flowchartDiagrams:
  enable: no
  options: ''
sequenceDiagrams:
  enable: no
  options: ''
---

Thanks again for all the help, and all the awesome work you guys do!

[cderv]

If you are not using Pandoc, there is indeed a possibility that math does not work well with Goldmark as it is not supported out of the box (I think there is a goldmark extension that can do it but don't know how to configure it with hugo). Anyway, as the doc you linked above says, it depends on your theme used to have a MathJax support.

Luckily, yours have it. See https://hugo-theme-even.netlify.app/post/even-preview/#math, the config part and the code
I would suggest you follow the documentation of your specific theme.

This works for me in .Rmarkdown files

---
title: "Hello R Markdown"
author: "Frida Gomam"
date: 2020-12-01T21:13:14-05:00
categories: ["R"]
tags: ["R Markdown", "plot", "regression"]
autoCollapseToc: true
mathjax: true
mathjaxEnableSingleDollar: yes
mathjaxEnableAutoNumber: yes
---

# Some Math

inline math: $ evidence\_{i}=\sum\_{j}W\_{ij}x\_{j}+b\_{i} $

Display math

$$
E(\mathbf{v}, \mathbf{h}) = -\sum_{i,j}w_{ij}v_i h_j - \sum_i b_i v_i - \sum_j c_j h_j
$$

\\[3 < 4\\]


\begin{equation}
   E = mc^2
\end{equation}

As you see if you try, special chars are escaped with \ here and the last equation does not render correctly because of the backtick that is here to protect. For them to work, you need to modify your website following the advice in the book to make it work with any type of equation.

See

• The how-to on math: https://bookdown.org/yihui/blogdown/templates.html#how-to
• Th JS script to add: https://bookdown.org/yihui/blogdown/javascript.html#javascript

You would need to add this script to the theme, or modify the theme to configure mathjax to skip the <code> tag.

So, at the end, this will also require to modify the theme as Math are not yet supported by default in Hugo markdown renderer.

This is the same as for the TOC: to make it available for .Rmd and .Rmarkdown, it would require to adapt the theme the How-o part in the book shows an example.

BTW @yihui the last equation with \begin would work in this specific theme if the backtick were not added around. I did not found where the were added and if there is a way to deactivate this backtick addition.

[yihui]

@cderv That sounds like a bug of my JS code: https://github.com/rbind/yihui/blob/ad46b111ac16b58701fef041912f8594e5d5b1d9/static/js/math-code.js#L13 The <code> tag around \begin{equation}\end{equation}should be removed. Are you able to figure out why it was not?

@mrkaye97 In case you you'd like to learn more background information about this problem: https://yihui.org/en/2018/07/latex-math-markdown/

[mrkaye97]

Awesome! Thanks again guys

[cderv]

@yihui I understood the math-code.js should be inserted in the theme. right ?
In the example above using olOwOlo/hugo-theme-even theme, math is supported by mathjax but I did not put the JS script in.

I understood blogdown will add the backtick and you need the JS script to remove. When you don't have the JS script, maybe it could be interested to deactivate the backtick insertion ?
For such theme, it would not be perfect but most math would work I believe.

So I don't think this is bug in your script. I may have misexplain what I tried 😅

[yihui]

@cderv Oh I see now. Yes, math-code.js has to be inserted in the theme. That's what I'd recommend. To deactivate the backticks (even though I don't recommend it), see #466 (comment).