Include toc in conversion to HTML from front matter

[rgoubet]

I'm still struggling with using the toc property from the yaml front matter as described here when converting an MD file to HTML. This has been discussed elsewhere, including in closed issues (see #2872) but I couldn't find a definitive answer.

I have a Markdown file starting with

---
title: My title
toc: true
---

The I run: pandoc --standalone -o out.html in.md. In the output file, the title is included, but not the toc. However, if I run pandoc --standalone --toc -o out.html in.md, then it works.

What am I missing?

[rnwst]

I agree that this is very confusing. The --toc command line option will set both the table-of-contents (the actual table of contents content) template variable, as well as the toc (whether the table of contents is to be included) template variable. Setting only the toc metadata variable (without setting the --toc command line option) results in the toc template variable becoming true, but since the table-of-contents template variable is empty, the TOC ends up being empty. You can inspect the HTML template with pandoc -D html.

I propose that the documentation is updated to remove any mention of the toc metadata variable, as it currently states

toc
include table of contents (can also be set using --toc/--table-of-contents)

and setting toc: true in the YAML metadata alone does not seem to work without also using the --toc command line option, making the statement in the documentation incorrect. Any thoughts @jgm?

[jgm]

I suppose another option would be to add a new warning to T.P.Logging, and issue a warning in the affected writers when toc is set in the user's metadata but --toc was not selected on the command line.

[rnwst]

@jgm -- what would be your thoughts on having pandoc generate a table of contents for formats where the writer needs to generate the ToC based on the toc metadata key, as @rgoubet suggested? Then the --toc CLI option would become equivalent to -M toc. I suppose many users won't be aware of which formats handle the generation of the ToC by themselves, and for which formats pandoc needs to generate it.

[jgm]

My objection to that is that conceptually, toc is not really "metadata." It is a processing instruction.

[rnwst]

Agreed. In that sense it isn't very helpful that a ToC can be added by setting toc: true in the metadata for all those formats that generate the ToC themselves. I think using toc as a metadata key should be discouraged, as that would avoid any confusion to begin with.

[jgm]

Agreed. But note that we are not encouraging using toc as a metadata key. The only place in the docs that mention it can be done is a section specific to LaTeX. People just do it and find that it works....sometimes.

[rgoubet]

OK, indeed very confusing. The --toc command will add a table of content even if toc is not present in the YAML block, which means that the latter does nothing. I would have expected YAML variable to cause the ToC to be generated even if --toc is not called. That would be interesting as it allows to add a a ToC as part of the MD file, while always using the same conversion command.

[rnwst]

I'm not sure it would be wise to mix up options and document metadata. I think the inclusion of a ToC should only be controlled via the command line option.