Pandoc Tricks
Here's some tricks that is allowed by pandoc but not obvious at first sight.
using pandoc -f markdown... -t markdown... can have surprisingly useful applications. As a demo, this file is generated by
pandoc -t markdown_github --atx --normalize --reference-location=block --toc -s -o temp-github.md temp.mdBe careful of @ though, you need to escape it in pandoc since it is treated as citation in pandoc.
As shown in issue #2814, it can be used to clean up / normalize your markdown file.
e.g. you have a long markdown file in GitHub and want to have a TOC, you can use pandoc -t markdown_github --toc -o example-with-toc.md example.md
This a useful workaround to update the TOC of very long documents, but —beware!— if you use this trick for writing over the input file, you'll end stacking TOCs — each new Table of Contents being generated above the previouly built ones, and indexing them too. This technique is useful when working with different source and output files.
Also, you can add a title to the TOC using the toc-title variable, but only if you use a markdown template — as explained ahead.
Did you know that you can use pandoc template with markdown too?
Ask pandoc to write-out the default template for markdown:
pandoc --print-default-template=markdown > template.markdwonAnd now let's peek at the template we got:
$if(titleblock)$
$titleblock$
$endif$
$for(header-includes)$
$header-includes$
$endfor$
$for(include-before)$
$include-before$
$endfor$
$if(toc)$
$toc$
$endif$
$body$
$for(include-after)$
$include-after$
$endfor$
As you can see, there's plenty of conditional statements to play with, allowing for additional control over the output markdown file.
You can also use the toc-title template variable to tell pandoc to add a title on top of the generated TOC. Change the template’s toc block like this:
$if(toc)$
$if(toc-title)$
# $toc-title$
$endif$
$toc$
$endif$
And now invoke pandoc like this:
pandoc --toc -V toc-title:"Table of Contents" --template=template.markdown -o example-with-toc.md example.mdAnd you'll see in the example-with-toc.md file an auto-generated Table of Contents with a # Table of Contents title over it.
NOTE: if you also include some extra markdown contents with the
--include-before-bodyoption (eg:--include-before-body=somefile.md) the contents of the included file will go before the TOC (at least, with the template used in this example) and any headings it contais will not be included in the TOC — ie: the TOC only indexes what comes after the$toc$template tag. This is useful if you'd like to include an Abstract before the TOC.
The manual said:
Note: the
--webtexoption will affect Markdown output as well as HTML.
This can be used to put math in pure markdown. e.g. you want to put math directly in the README.md in GitHub.
For example, in the temp.md:
# Important Discovery!
$1+2\neq3!$
Try it!Run this:
pandoc --atx-headers --webtex=https://latex.codecogs.com/png.latex? -s -o temp-codecogs.md temp.mdThen the output becomes:
Try it!
Say, in your source markdown file pipe.md:
| testing | pandoc | tables |
|-------------|-------------------|---------|
| simple cell | no multiline cell | and |
| so | on | no list |In command line,
pandoc -t markdown-simple_tables-multiline_tables-pipe_tables -s -o grid.md pipe.mdIn the output grid.md:
+--------------------------+--------------------------+--------------------------+
| testing | pandoc | tables |
+==========================+==========================+==========================+
| simple cell | no multiline cell | and |
+--------------------------+--------------------------+--------------------------+
| so | on | no list |
+--------------------------+--------------------------+--------------------------+If you use auto-identifiers for the headers, and there are different headers of the same name across different folders, you'd want to catenate them together, and pandoc do this for you:
pandoc file1.md file2.md ...But if there are repeated footnotes anchors on both files, you need --file-scope, which will parsed each files individually (so the footnotes anchors are "local" to the individual file):
pandoc file1.md file2.md --file-scope ...What if the 2 files has both problems? i.e. headers of same name (hence the same id by the auto-identifier) and footnotes of the same anchors appears across the files. Either approach gives you problem.
In this case, you can use "to markdown from markdown" to write an intermediate markdown file using --file-scope, which handles the colliding footnote anchor for you, and then generate from that intermediate markdown file, the auto-identifiers will handle the headers for you:
pandoc --file-scope -o intermediate.md file1.md file2.md
pandoc intermediate.md ...If you wrote a template snippet that do not form a complete template. The -H, -B, or -A option would not help because pandoc would put your snippet as is and wouldn't process it as a template. i.e. The snippet is included after the template is processed.
A trick mentioned by @cagix in jgm/pandoc-templates#220 is this:
pandoc --template=template_snippet document.md -o processed_snippet
pandoc -H processed_snippet document.md -o document.pdfThe first line will process your template snippet according to the properties of the document, but since your snippet (probably) do not have $body$, the body would not be in the output. Now the snippet is processed and can then be included through -H as is in the 2nd line.
Based on this pandoc-discuss exchange and this TeX StackExchange topic it is possible to left-align all tables a document (in the PDF output from LaTeX) with this single invocation in the YAML header block:
---
header-includes:
- \usepackage[margins=raggedright]{floatrow}
---
This applies to all floats and fine-grained control may be achieved with the options outlined in the documentation for the floatrow LaTeX package.