Pandoc Quirks

Pandoc has mostly been a joy to work with, but every so often, I hit something either confusing or a little bit painful. This page is here to document those occasional rough edges.

Table of Contents

Pandoc allows you to generate a table of contents for latex and html output formats (among others). However, if you're generating html, specifically, you cannot set toc: true inside the file with no other modification and expect to get an html table of contents. Rather, you must still add the --toc flag to the pandoc command after which toc: true or toc: false in the file metadata will control whether the file gets a table of contents.

Is this a problem? It depends on the default behavior one expects. In general, I would like to avoid is having to actively toggle off any setting that doesn't apply to the majority of the pages on this site, and all pages are generated from the same pandoc command. However, as of right now, quite a few of them are made better by having a table of contents, so it may be a non-issue.

This github issue helped me to better understand what was happening here. Thanks!