HTML table of contents with toc :true in the yaml metablock?

[joelostblom]

When I generate an html-document from a markdown-file with toc: true in the yaml-metablock, the resulting html-file has the word "true" at the top of the document instead of an actual table of contents. When I add --toc to the pandoc command, it still only prints "true". When I remove toc: true from the markdown file and add --toc to the pandoc command, the html-document displays a table of contents.

Is it possible make toc: true in the yaml-metablock generate a table of contents in the html document, similar to how the generation of pdf files works (where toc: true and --toc produce the same output)?

[jgm]

Pandoc's writers populate the toc variable with the actual
table of contents. But pandoc never gives a value to a
variable if a corresponding metadata field is set. So,
if you set toc to true in the metadata, pandoc won't
replace it with the actual table of contents.

The difference between HTML and LaTeX (PDF) is that in
LaTeX, the table of contents is automatically generated,
so the template just has

$if(toc)$\tableofcontents$endif$

while in HTML, there is nothing like a \tableofcontents
command, so pandoc has to create the table of contents
itself.

It would be possible to treat toc specially, so that in
formats where pandoc has to create the toc itself, it
sets writerTableOfContents if toc metadata is true,
and then overwrites the toc variable with the toc
contents. (I'd want to do this not just for HTML but for
every format involving toc.) This seems a bit ad hoc,
though.

+++ joelostblom [Apr 22 16 15:09 ]:

When I generate an html-document from a markdown-file with toc: true in
the yaml-metablock, the resulting html-file has the word "true" at the
top of the document instead of an actual table of contents. When I add
--toc to the pandoc command, it still only prints "true". When I remove
toc: true from the markdown file and add --toc to the pandoc command,
the html-document displays a table of contents.

Is it possible make toc: true in the yaml-metablock generate a table of
contents in the html document, similar to how the generation of pdf
files works (where toc: true and --toc produce the same output)?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or [1]view it on GitHub

References

1. HTML table of contents with toc :true in the yaml metablock? #2872

[joelostblom]

Thank you for the explanation!

If I understand you correctly, the solution I was imagining is similar to what you suggested. Simply activating --toc (or maybe more correctly writerTableOfContents), when toc: true is found in the yaml metadata block and the output format does not already handle this variable (like you described LaTeX does).

I can't say if this is a satisfactory solution technically, but just from a user standpoint, I would intuitively expect toc: true to generate consistent output between formats. Another possible solution could be to ignore toc: true in formats that don't support it, instead of the current behavior which prints "true" and prevents --toc from generating a table of contents.

[ickc]

I faced the same problem and like the proposed solution.

[equaeghe]

It would be possible to treat toc specially, so that in
formats where pandoc has to create the toc itself, it
sets writerTableOfContents if toc metadata is true,
and then overwrites the toc variable with the toc
contents. (I'd want to do this not just for HTML but for
every format involving toc.) This seems a bit ad hoc,
though.

Well, it seems to me that toc is used for two different purposes currently, once as a Boolean switch and once as a string containing the actual table of contents. I think that is the underlying issue here and the reason why the proposed solution feels ad hoc. Wouldn't it be better to fix the issue by replacing the second toc usage with its own variable, tableofcontents, say, and then for every format create that variable. So for LaTeX, it would be "\tableofcontents" by default, whereas in html it would contain the output of the custom functionality you built into pandoc.

[harmic]

I had the same issue, and it took me a while to stumble across this bug report.

I vote for @equaeghe's idea, that looks like the cleanest solution. Also, to provide backward compatibility for existing templates, if --toc is specified on the command line, and not defined in the metadata, then set $toc$ to the same as $tableofcontents$ (ie. the generated toc content)

[jgm]

Yes, I think @equaeghe's idea is a good one.
(Though we have to get a clearer idea of how many changes in the templates and writers would be needed.)

[mathias-sm]

Hi,

To me the behaviour is a bit unexpected. Take this minimal file:

---
title: Title1
toc: true
---

## Title2

Paragraph

toc being set to true, I expect the html output to contain the table of content, however if I run pandoc -s minimal_example.md (without the --toc option) the <nav id="TOC"></nav> is present but empty.

In order to get the table of content I need to add the --toc option, which seems redundent, but even worse I can have the --toc option and set toc: false resulting in no table of content nor <nav></nav>.

After reading the templates I understand how this was designed to be the expected behaviour in the sense that --toc tells pandoc to populate a variable and toc: true is the conditional check to add the html nav or not, however it took me a while and close inspection of the templates to figure this out.

Thanks for this amazing tool!