Awesome Tips about Pandoc

Table of Contents

• Related Posts
• What Pandoc can Do?
• Pandoc
• Tips
• Pandoc Markdown Syntax
• EXTENSION
• Themes
  • Blockquotes CSS
  • Table CSS
  • How to have content in the top slide in 2D reveal.js slideshows
  • Use Variables in Document Body Text
  • Template
  • Filters
  • Troubleshooting
• Resources

Series: Awesome Tips about Pandoc

---

What Pandoc can Do?

• convert files from one format into another: markdown to html/pdf/word/ppt, vice verse and many other types.

Pandoc

• brew install pandoc, brew upgrade pandoc or sudo apt-get install pandoc
• Add bash-completion: eval "$(pandoc --bash-completion)" to ${HOME}/.bash_profile
• Output: -o output.df, -o output.pptx
• pandoc –list-extensions
• pandoc –list-output-formats
• Reading from the Web: pandoc -f html -t markdown http://www.fsf.org
• TOC generation:
  • --toc
  • --toc-depth=NUMBER <!– ### remark
• in-browser, markdown-driven slideshow tool –>

Tips

• set language for the inline code
  • The source: Redcarpet.new("Hello World!"){.ruby}
  • The result: Redcarpet.new("Hello World!")
• Syntax highlight: –highlight-style
  • pandoc –list-highlight-languages
  • breezedark, haddock, pygments, tango, espresso, zenburn, kate, monochrome
  • breezedark is pretty good.
• Specify image size: we can use px or percentage.
  • ![](the_image_path){.class height=20px width=20px }
  • 
• side by side images

![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

<!-- Side by Side Images -->
Header Left |  Header Right
:--------:|:-------:
![](image_link)  |  ![](image_link)

Pandoc Markdown Syntax

• fenced_code_attributes

  ~~~~ {#mycode .haskell .numberLines startFrom="100"}

• line_blocks: beginning with a vertical bar (|) followed by a space
  • useful for verse, addresses, resume
• pandoc_title_block: title, author(s), date
  • pass metadata in pandoc command: -M date="Updated at $(date "+%B %e, %Y")"
• yaml_metadata_block
  • when use --- as line break, better put a new line after it, otherwise it may be confused with yaml_metadata_block

    ---
    author: Jeffery Yuan
    title: "Awesome Tips about Pandoc"
    subtitle: How to effectively use Pandoc
    date: 6/7/2019
    description: Awesome Tips about how to effectively use Pandoc.
    ---

• attributes
  • Heading identifiers: {#identifier .class .class key=value key=value}
    • Hi {#foo .bar .baz key=val} is compiled to html <h1 id="foo" class="bar baz" key="val">Hi</h1>
  • code with class {.class} or [Span with class]{.class}
  • Use {custom-style=class} instead of {.class} to also work in word.
  • link_attributes
    • ![image](foo.jpg){#id .class width=30 height=20px}
    • [Hello, world!](http://example.com/){target="_blank"}
      • use blank as _ is special character in markdown
  • inline_code_attributes: {.haskell}
  • {.smallcaps}
  • raw_attribute: {=html}
• tex_math_dollars

• Speaker notes

  ::: notes
  :::

• Need a blank line before a block quote
• Superscript: mc^2^ mc²

• Subscript: H~2~O H₂O

EXTENSION

• +EXTENSION to the format name and disabled by adding -EXTENSION
  • --from markdown_strict+footnotes

Themes

• We can also add our own css or change the existing one.
• We can edit blogger’s theme and add the css there so the theme applies to all posts.
• Create truly standalone html files
  • -H fullpath_pandoc.css or –include-in-header=FILE
• Themes to use
  • pandoc.css

Blockquotes CSS

• alt

blockquote {
 margin: 0;
 border-left: 3px solid #ccc;
}
blockquote p {
 padding: 15px;
 background: #eee;
 border-radius: 5px;
}
/* blockquote p::before {content: '\201C';}
blockquote p::after {content: '\201D';} */

Table CSS

.post-body table {
  border-collapse: collapse;
}
.post-body table, th, td {
  border: 1px solid black;
}

How to have content in the top slide in 2D reveal.js slideshows

• in 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).

  • Must also run pandoc with --slide-level=2

Use Variables in Document Body Text

• We can use variables from command line or defined in metadata block.

---
hello:
  english: world
  german: Welt
---
$updatedDate$

Hello $hello.english$.

• pandoc -M updatedDate="Updated at $(date "+%B %e, %Y")" --template --template "${md}" "${md}" | pandoc -t html

Template

• How to add a “Table of Contents” title in the HTML template

pandoc -D html >$HOME/.pandoc/templates/default.html
pandoc --template==$HOME/.pandoc/templates/default.html

Filters

• pandoc-mustache for variable substitution
• pandoc-include
  • Install Xcode from Mac App Store (slow…)
  • Install Haskell Tool Stack
  • stack update; stack install pandoc-include

Troubleshooting

• When the output is not same as expected, start from the first place and fix it.
• Usually we can fix it by add new line, or put the text in `the_text`.

Resources

• https://github.com/jgm/pandoc
• https://github.com/jgm/pandoc/wiki
• https://pandoc.org/MANUAL.html