Table of Contents Does Not Work With `blogdown.method = "html"`

[amarakon]

I use the hugo-theme-fuji theme, but I think this issue has nothing to do with that. When I had blogdown.method = "markdown" in root/.Rprofile, the table of contents worked perfectly fine but citations in figure captions didn't work. So I switched blogdown.method to html, but this caused the table of contents to not work (There are section headers in all of my blog posts.)

My website, source code

Reproducible example:

1. Create a new website by using blogdown::new_site()
2. Use the fuji hugo theme as mentioned above
3. Set blogdown.method = "html" in root/.Rprofile
4. Create a blog post with section headers

[yihui]

https://bookdown.org/yihui/blogdown/output-format.html

For html output, you need to enable the toc option:

output:
  blogdown::html_page:
    toc: true

Please consider using a public form for future questions: https://github.com/rstudio/blogdown#getting-help Github issues is mainly for bug reports and feature requests. Normally we don't have the bandwidth to help you with every question here. You have filed several issues in the past few days, and none are bugs or feature requests.

Thanks for your understanding!

[amarakon]

Setting that toc option makes the table of contents appear in an unordered bulleted list, instead of where it should be. Also, I will ask issues on commmunity.rstudio.com next time, but I'm pretty sure my past post (Citation in Figure Caption Does Not Work) is a bug that occurs when using markdown blogdown method.

[yihui]

The html and markdown method each has their pros and cons. Both this TOC issue and that citation in figure caption issue are quite tricky. In general, if you need sophisticated features for technical writing (such as citations), the html method can offer them, because this method is based on Pandoc, and Pandoc's Markdown is much more powerful than Hugo's goldmark. If you want features that work better with Hugo, the markdown method is usually better.

The citation in figure caption issue is a bug, but it's very difficult to fix from my side and I don't consider it a blogdown bug. The underlying issue is that Hugo's Markdown rendering engine, goldmark, cannot process Markdown text inside HTML blocks. Unfortunately this is beyond my control. If you really desire it, you may file a feature request to goldmark. By comparison, Pandoc supports Markdown in HTML: https://pandoc.org/MANUAL.html#extension-markdown_in_html_blocks

Even for bugs, it's okay to ask on a public forum before coming here. Someone else might help you confirm whether it is a bug, or a matter of usage. If no one helps you there, you are always welcome back to Github issues. I was asking you to try forums because there are only two people reading and dealing with Github issues in this repo on a daily basis, and we have several other repositories to maintain, too. With the limited resources, we would like you to try the community help first, where there could way more people who could potentially help you. Not only we have less burden, but you can also get quicker help (I just happen to be working on blogdown this week; normally I wouldn't be so responsive :).

BTW, even if you set blogdown.method = 'html', you can still render a post to markdown by using the .Rmarkdown extension (as mentioned in the documentation https://bookdown.org/yihui/blogdown/output-format.html), so if you want the TOC but do not need citation in figure caption, this is one way to go. If you want both, there isn't a perfect solution.

[amarakon]

The temporary solution I am using is setting blogdown.method = "markdown", but putting the citation below the figure caption. Thanks for helping me.

[yihui]

Sounds good, and you are welcome! If I were you, I'd also avoid using citations in the figure caption but in the post body instead.