Pandoc Tips and Tricks

https://github.com/jgm/pandoc/issues/2872

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

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.

https://github.com/jgm/pandoc/wiki/How-to-add-a-%22Table-of-Contents%22-title-in-the-HTML-template
pandoc -D html >$HOME/.pandoc/templates/default.html
pandoc --template==$HOME/.pandoc/templates/default.html

https://pandoc.org/lua-filters.html#replacing-placeholders-with-their-metadata-value
There's actually a sample lua filter in the docs for doing just this: https://pandoc.org/lua-filters.html#replacing-placeholders-with-their-metadata-value
https://github.com/jgm/pandoc/issues/1950

It could be modified to use the `[%my name]` syntax.

However, nothing stops you from using a Markdown file as a template
for itself. Take this my.md:

---
hello:
  english: world
  german: Welt
...

Hello $hello.english$.

Now do

% pandoc my.md --template my.md | pandoc -t html
<p>Hello world.</p>

https://pandoc.org/lua-filters.html#replacing-placeholders-with-their-metadata-value

--template=FILE|URL

Use the specified file as a custom template for the generated document. Implies --standalone. 

-V KEY[=VAL], --variable=KEY[:VAL]

Set the template variable KEY to the value VAL when rendering the document in standalone mode. This is generally only useful when the --template option is used to specify a custom template, since pandoc automatically sets the variables used in the default templates. If no VAL is specified, the key will be given the value true.

-M KEY[=VAL], --metadata=KEY[:VAL]

Set the metadata field KEY to the value VAL. A value specified on the command line overrides a value specified in the document using YAML metadata blocks. Values will be parsed as YAML boolean or string values. If no value is specified, the value will be treated as Boolean true. Like --variable, --metadata causes template variables to be set. But unlike --variable, --metadata affects the metadata of the underlying document (which is accessible from filters and may be printed in some output formats) and metadata values will be escaped when inserted into the template.

https://github.com/jgm/pandoc/issues/2523

echo 'hi :smile: :one:' | pandoc -f markdown+emoji --pdf-engine=lualatex -o foo.pdf --variable mainfont="DejaVu Sans"

https://www.xaprb.com/blog/how-to-style-images-with-markdown/

https://stackoverflow.com/questions/39400160/centering-text-pictures-with-markdown-and-pandoc

Think of markdown as a nicer syntax for HTML – it's only the content, no styling. (Centering would be styling.) You cannot center text in HTML either. But you can add classes, then style them with CSS (in your Hakyll theme).

Pandoc markdown currently supports attributes on images:

![](img.jpg){.myClass}

but not paragraphs, however you can wrap stuff in divs:

# my markdown header

<div class="myClass">

  one paragraph

  second paragraph, **strong**

</div>

http://pages.stat.wisc.edu/~yandell/statgen/ucla/Help/Producing%20slide%20shows%20with%20Pandoc.html

https://stackoverflow.com/questions/30988306/level-1-and-level-2-slides-in-reveal-js-using-pandoc

If you want to nest slides to level 2, you cannot put content under a level 1 header. This limitation is by design. According to developer John MacFarlane, as of June 2015:

Pandoc has a method of carving content into slides (described in the User's Guide) that works the same for all slide formats, so you can use the same source for reveal.js and beamer. That is what motivated the present system, though I'm open to a better way, as long as it works uniformly with all formats.

You need a hero with a patch.

As of pandoc 2.7:

Slide show formats behavior change: content under headers less than slide level is no longer ignored, but included in the title slide (for HTML slide shows) or in a slide after the title slide (for beamer). This change makes possible 2D reveal.js slideshows with content in the top slide on each stack (#4317, #5237).

https://github.com/jgm/pandoc/issues/4317

Add this to the pandoc command you use:

-M date="$(date "+%B %e, %Y")"




-M KEY[=VAL], --metadata=KEY[:VAL]

Set the metadata field KEY to the value VAL. A value specified on the command line overrides a value specified in the document using YAML metadata blocks. 

https://stackoverflow.com/questions/23226224/inline-code-syntax-highlighting-in-github-markdown

GitHub comments, wikis etc. use GFM, essentially CommonMark with some extensions. There it's not possible.

However, GitHub Pages uses Jekyll and by extension kramdown where you can use:

`Redcarpet.new("Hello World!")`{:.ruby}

P.S. If you happen to use pandoc, the syntax is:

`Redcarpet.new("Hello World!")`{.ruby}

https://github.com/jgm/pandoc/wiki/User-contributed-templates

https://tex.stackexchange.com/questions/253262/pandoc-markdown-to-pdf-doesnt-show-images

Pandoc includes raw HTML only if the output format is HTML-like. From the web-site:

The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, and Textile output, and suppressed in other formats.

In order to get images to work for both, HTML and PDF writer, you have to use pandoc's own format:

 ![la lune](lalune.jpg "Voyage to the moon")

https://pandoc.org/MANUAL.html

pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
  http://www.fsf.org




Generate a bash completion script. To enable bash completion with pandoc, add this to your .bashrc:

eval "$(pandoc --bash-completion)"

A “lazy” form, which requires the > character only on the first line of each block, is also allowed:

> This is a block quote. This
paragraph has two lines.




Indented code blocks

A block of text indented four spaces (or one tab) is treated as verbatim text: that is, special characters do not trigger special formatting, and all spaces and line breaks are preserved. For example,

    if (a > 3) {
      moveShip(5 * gravity, DOWN);
    }




Like regular code blocks, fenced code blocks must be separated from surrounding text by blank lines.

Extension: fenced_code_attributes

Optionally, you may attach attributes to fenced or backtick code block using this syntax:

~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~







Extension: line_blocks

A line block is a sequence of lines beginning with a vertical bar (|) followed by a space. The division into lines will be preserved in the output, as will any leading spaces; otherwise, the lines will be formatted as Markdown. This is useful for verse and addresses:

| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718







A bulleted list item begins with a bullet (*, +, or -)




This will produce a “compact” list. If you want a “loose” list, in which each item is formatted as a paragraph, put spaces between the items:




A list item may contain multiple paragraphs and other block-level content. However, subsequent paragraphs must be preceded by a blank line and indented to line up with the first non-space content after the list marker.

  * First paragraph.

    Continued.

  * Second paragraph. With a code block, which must be indented
    eight spaces:

        { code }










- [ ] an unchecked task list item
- [x] checked item







To “cut off” the list after item two, you can insert some non-indented content, like an HTML comment, which won’t produce visible output in any format:

-   item one
-   item two

<!-- end of list -->

    { my code block }

You can use the same trick if you want two consecutive lists instead of one big list:

1.  one
2.  two
3.  three

<!-- -->

1.  uno
2.  dos
3.  tres







A line containing a row of three or more *, -, or _ characters (optionally separated by spaces) produces a horizontal rule:




To make a short span of text verbatim, put it inside backticks:

What is the difference between `>>=` and `>>`?

If the verbatim text includes a backtick, use double backticks:

Here is a literal backtick `` ` ``.




Attributes can be attached to verbatim text, just as with fenced code blocks:

`<$>`{.haskell}




Extension: implicit_figures

An image with nonempty alt text, occurring by itself in a paragraph, will be rendered as a figure with a caption. The image’s alt text will be used as the caption.




![This is the caption](/url/of/image.png)




Extension: link_attributes

Attributes can be set on links and images:

An inline ![image](foo.jpg){#id .class width=30 height=20px}
and a reference ![image][ref] with attributes.













https://pandoc.org/MANUAL.html#extensions

An extension can be enabled by adding +EXTENSION to the format name and disabled by adding -EXTENSION. For example, --from markdown_strict+footnotes is strict Markdown with footnotes enabled, while --from markdown-footnotes-pipe_tables is pandoc’s Markdown without footnotes or pipe tables.

The markdown reader and writer make by far the most use of extensions. Extensions only used by them are therefore covered in the section Pandoc’s Markdown below (See Markdown variants for commonmark and gfm.) In the following, extensions that also work for other formats are covered.

https://stackoverflow.com/questions/4425198/can-i-create-links-with-target-blank-in-markdown

In particular, pandoc has an extension to enable link_attributes, which allow markup in the link. e.g.

[Hello, world!](http://example.com/){target="_blank"}

• For those coming from R (e.g. using rmarkdown, bookdown, blogdown and so on), this is the syntax you want.
• For those not using R, you may need to enable the extension in the call to pandoc with +link_attributes

Note: This is different than the kramdown parser's support, which is one the accepted answers above. In particular, note that kramdown differs from pandoc since it requires a colon -- : -- at the start of the curly brackets -- {}, e.g.

[link](http://example.com){:hreflang="de"}




https://lee-phillips.org/panflute-gnuplot/

https://stackoverflow.com/questions/33748781/pandoc-inline-class-and-id-elements

pandoc got updated recently, now you can do:

`code with class`{.class}

and

[Span with class]{.class}

To use this feature in word as well (style), it's {custom-style=class} instead of {.class}
https://github.com/jgm/pandoc/wiki/Pandoc-Tricks

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 previously 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.

https://github.com/michelf/php-markdown/issues/157

https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown

Pandoc allows ordered lists to have different numbering styles and delimiters; these are recorded and reproduced, where possible, in the output format.

(a) My list
(b) Lowercase letters
    i. Roman sublist
    ii. Next

Superscript

Pandoc supports superscripts: mc^2^.

Subscript

Pandoc supports subscripts: H~2~O.

Multiline table:

----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

https://alvinalexander.com/text/how-put-multiple-lines-markdown-table-cell-multiline-table

| Format   | Tag example |
| -------- | ----------- |
| Headings | =heading1=<br>==heading2==<br>===heading3=== |
| New paragraph | A blank line starts a new paragraph |
| Source code block |  // all on one line<br> {{{ if (foo) bar else   baz }}} |

https://stackoverflow.com/questions/19950648/how-to-write-lists-inside-a-markdown-table

Github Flavored Markdown supports basic HTML in .md file. So this would be the answer:

Markdown mixed with HTML:

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |
| <ul><li>item1</li><li>item2</li></ul>| See the list | from the first column|




https://github.com/jgm/pandoc/wiki/Pandoc-Filters

mermaid-pandoc for inserting images expressed in mermaid syntax
r-pandoc for inserting plots expressed in the R language

• pandoc-mustache replaces variables like {{varname}} in a pandoc document with their values, which are stored in a separate YAML file.

• filter_pandoc_run_py for executing python codes written in code blocks and also embedding print output and pyplot figures

https://github.com/htdebeer/paru-filter-collection#paru-screenshotrb
paru-insert.rb, inserting other pandoc markdown files
paru-code.rb, inserting source code files in a code block
paru-screenshot.rb, automatically take screenshot of a web page and insert in markdown file

https://github.com/jgm/pandoc/wiki/Pandoc-Extras