⇠ chan.dev / posts

Pandoc

🌱 This post is in the growth phase. It may still be useful as it grows up.

Contents

Install Pandoc on mac with Homebrew

Terminal window
brew install pandoc

This requires Homebrew.
Find additional installation options here.

Once installed, run which pandoc to verify your installation. If you don’t see a result, try again in a new terminal window.

Install MacTeX for PDF generation

MacTeX is a typesetting tool. And it’s required for PDF generation.

MacTex is enormous enormous at ~4GB.
See alternative Latex installation options here. MacTex recommends installing the full version, if you have the disk space. It’s unpredictable when you’ll need specific features.

Basic usage

Out of the box, Pandoc is configured for markdown to html conversion.

Bare command

Terminal window
pandoc

Run pandoc with no arguments to open a Pandoc shell. Type some markdown there and hit CTRL-D twice and see the resulting HTML.

Terminal window
chantastic@local % pandoc
Hello *pandoc*!


❤️, [chan](https://chan.dev)


<p>Hello <em>pandoc</em>!</p>
<p>❤️, <a href="https://chan.dev">chan</a></p>

This makes a great demo but a terrible workflow.

Feed pandoc source files

Pandoc takes source files as input.

Terminal window
pandoc my-markdown-file.md

When fed multiple source files, it combines them.

Terminal window
pandoc file1.md file2.md file3.md
Terminal window
chantastic@local % pandoc file1.md file2.md file3.md


<h2 id="this-is-file-one">This is File One</h2>
<p>Contents from file one.</p>
<h2 id="this-is-file-two">This is File Two</h2>
<p>Contents from file two.</p>
<h2 id="this-is-file-three">This is File Three</h2>
<p>Contents from file three.</p>

Use the --output option to set an output file

Pipe Pandoc transformations into a file on disk by providing an --output location.

Terminal window
pandoc my-markdown-file.md --output transformed-file.html

Use -o for short.

Terminal window
pandoc my-markdown-file.md -o transformed-file.html

Pandoc infers format from filename extensions

Pandoc is smart enough to infer the output format based on the provided extension.

Let’s get weird and change the output file extension to .docx (lol, remember Microsoft Word?).

Terminal window
pandoc my-markdown-file.md --output transformed-file.docx

Pandoc made a Microsoft Word doc for us!

Type ls to see it.

Set input format with the --from option

We can explicitly set the input format with the --from option.

Pandoc defaults to markdown (specifically Pandoc Markdown).

Terminal window
# the default without options
pandoc my-markdown-file.md --from markdown

Set the input format to commonmark if you prefer strict markdown.

Terminal window
pandoc my-markdown-file.md --from commonmark

Pandoc offers a lot formats. So you’re not limited to markdown.
We can transform document from html to markdown as well.

Terminal window
pandoc some-webpage.html --from html --to markdown

Find the full list of input formats here.

Set output format with the --to option

We can explicitly set the output format with the --to option.

Pandoc defaults to html.

Terminal window
# the default without options
pandoc my-markdown-file.md --to html

Set the output format to .pdf to create a PDF.

Terminal window
# This requires a latex installation. See Install.
pandoc my-markdown-file.md --to pdf

The console output will look real strange.

Find the full list of output formats here.

Create standalone html files with the --standalone option

Produce complete HTML documents with the --standalone option. This will wrap your content in a standard HTML template.

Terminal window
pandoc my-markdown-file.md --standalone

You can introduce layouts with templating syntax. I won’t be covering that here.

*Note that if it can’t find an H1, it will use the filename as a title. If more than one filename is provided, you’ll need to provide a title via frontmatter or the --metadata option.

Add metadata with the --metadata option

Metadata can be provided as key pairs to the —metadata option

Terminal window
pandoc my-markdown-file.md --standalone --metadata=title:"My Greatest Work",

Use the [--metadata-file] option can also be used to reduce the command size.

Include frontmatter in markdown files

A better way to include metadata is via a YAML metadatablock in your first markdown file.

You can put anything here but here is a sampling of ePub metadata

---
title:
  - type: main
    text: A Beginner's Guide to Pandoc
  - type: subtitle
    text: Build ebooks with ease!
creator:
  - role: author
    text: Michael Chan
  - role: editor
    text: Michael Chan
identifier:
rights: © 2022 Michael Chan, CC BY-NC
ibooks:
  version: 0.0.1
---


# This is a standard markdown file


And this will be the first page in my ebook.

Generate an ePub and the frontmatter metadata will be used to populate the required ePub fields.

Terminal window
pandoc my-markdown-file.md -o my-book.epub

Full list of ePub attributes

Compile multiple markdown files

  • Can’t have individual frontmatter
  • Title page title must be in markdown
  • Doesn’t seem to worry to much about structure, as long as

Other docs I’d like to dive into but haven’t yet.

like to learn more:

Bug me for more…

[Bug me on twitter if you’d like me to keep working on this doc.

Metadata

Easiest thing to do is apply metadata file last. This will override any metadata from previous files.

https://www.uv.es/wikibase/doc/cas/pandoc_manual_2.7.3.wiki?96