# Pandoc

- Page: https://shared.btbytes.com/p/pandoc
- Date: 2020-04-13
- Tags: markdown, pandoc

[Pandoc](http://johnmacfarlane.net/pandoc/index.html) is a program that converts between various text markup formats.

Pandoc allows you to customise the output via extensive command line arguments and by templates.

## My projects related to Pandoc

- [Semantic CSS for Pandoc](https://www.btbytes.com/pandoc-semantic-css/) -- an attempt at finding and using various semantic Cascading Style Sheets with Pandoc'd default HTML rendering.
- [Pandoc + Missing.css](https://www.btbytes.com/pandoc-missing/) -- is instructions on how to use [missing.css](https://missing.style) to style pandoc output. *Summary:* you will have to wrap the \$body\$ variable in `<main> </main>` tag.

## Writing Papers

- [mpark/wg21: Framework for Writing C++ Committee Papers](https://github.com/mpark/wg21); you can see an example output [here](https://www.circle-lang.org/interop.html)


## Guides on using Pandoc to write books

- This guide on [how to setup pandoc to write fiction](https://web.archive.org/web/20130327234448/http://web.archive.org/web/20101029210046/http://eugenkiss.com/blog/2011/fiction-in-markdown-with-pandoc/) by [Eugene Kiss](http://web.archive.org/web/20101029210046/http://eugenkiss.com/) is a very good introduction to using Pandoc to produce print-ready material.
- [words](https://github.com/steveklabnik/words) by Steve Klabnik.

## Editors

- [Build an Amazing Markdown Editor Using Visual Studio Code and Pandoc | thisDaveJ](http://thisdavej.com/build-an-amazing-markdown-editor-using-visual-studio-code-and-pandoc/)
- [PanWriter](https://panwriter.com/) Markdown editor for macOS, Windows and Linux.

## Customising pandoc

These are some of the examples of users customising pandoc to output `LaTeX`, `HTML` to their taste and requirements.

- [github.com/smile/pandoc-templates](https://github.com/smile/pandoc-templates)
- [github.com/claes/pandoc-templates](https://github.com/claes/pandoc-templates)
- [github.com/kjhealy/pandoc-templates](https://github.com/kjhealy/pandoc-templates)
- [pandoc academic publication](https://github.com/claymcleod/pandoc-academic-publication)
- [IEEE Pandoc template by cscorley](https://github.com/cscorley/ieee-pandoc-template) -- is what i used for writing a IEEE style paper.
- [Typesetting automation · A plain-text workflow for painless production of personal documents & offline correspondence—featuring Pandoc, LaTeX, and a simple makefile](http://mrzool.cc/writing/typesetting-automation/)
- [a makefile for pandoc](https://gist.github.com/btbytes/ac7a8698c2356a64e86070520680eb5a)
- [msprev/panzer: pandoc + styles](https://github.com/msprev/panzer)
- [Heer de Beer.org—Pandocomatic](https://heerdebeer.org/Software/markdown/pandocomatic/) "... is a tool to re-use these common configurations by specifying a so-called pandocomatic template in a YAML configuration file."

My own attempts are here:

- [github.com/btbytes/dotpandoc](https://github.com/btbytes/dotpandoc)

## Templates

- [pandoc-templates.org](https://pandoc-templates.org/)
- <https://github.com/btbytes/pandoc-ebook-template> an updated fork of <https://notabug.org/kmac/pandoc-ebook-template>
- [mre/pandoc-memoir](https://github.com/mre/pandoc-memoir/tree/master) Convert Markdown to beautiful [PDF](https://shared.btbytes.com/p/pdf) using [pandoc](https://shared.btbytes.com/p/pandoc), [LaTeX](https://shared.btbytes.com/p/latex), and chocolate donuts.

## Filters

[Pandoc filters](http://johnmacfarlane.net/pandoc/scripting.html) can be written in Haskell which modify the document structure programmatically. These are some of the user written filters that are instructive:

- [pandoc-emphasize-code](https://owickstrom.github.io/pandoc-emphasize-code/) -- "A Pandoc filter for emphasizing code in fenced blocks."
- [bitbucket.org/mpastell/pandoc-filters](https://bitbucket.org/mpastell/pandoc-filters/wiki/Home)
- [pandoc-reference-filter](https://github.com/aaren/pandoc-reference-filter) -- This pandoc filter implements an internal reference manager for pandoc, making it possible to reference images and sections that have attribute tags.
- Aditya Mahajan shows how to use gpp preprocessor to [include source code files](http://randomdeterminism.wordpress.com/2012/06/01/how-i-stopped-worring-and-started-using-markdown-like-tex/)
- [baig/pandoc-csv2table: A Pandoc filter that renders CSV as Pandoc Markdown Tables.](https://github.com/baig/pandoc-csv2table)
- [Panflute: pandoc filters made simple — panflute 1.9.7 documentation](http://scorreia.com/software/panflute/)
- [CSV Tables in Markdown — Pandoc Filter for CSV Tables](https://ickc.github.io/pantable/)
- [PP - A generic Preprocessor (with Pandoc in mind)](http://cdsoft.fr/pp/)
- [ChartSS.css](https://rbitr.github.io/ChartS.css/) -- to allow easy creation of simple charts for documentation, data storytelling / journalism, etc. It features plots of 1-D lists, and has a custom markdown filter that converts suitably formatted lists directly to charts. It has no dependencies (other than a modern browser), and is very small compared to javascript based charting tools. The html is based on `<ul>` lists and will collapse back to readible lists in the absence of css support, making it accessible to all readers.


## Exporters

[Ox-pandoc](https://github.com/kawabata/ox-pandoc) is an exporter that
translates Org-mode file to various other formats via Pandoc.

[Markdown to InDesign](http://rhythmus.be/md2indd/); Pandoc now ships
with a writer able to produce an ICML file from any Pandoc-supported
input file format.13 ICML is the document format of Adobe InCopy; Dec 2015.

## Books written using pandoc

- [The little Redis book](https://github.com/karlseguin/the-little-redis-book)
- My own attempts at converting Chuck Moore's [Programming a Problem-oriented language](http://www.colorforth.com/POL.htm) into a "book" using pandoc and some elbow grease. The result is available on github - <https://github.com/btbytes/pol>
- [littleosbook](https://github.com/littleosbook/littleosbook/) -- "The little book about OS development". Outputs HTML and PDF.
-  [Customizing pandoc to generate beautiful pdfs from markdown | learnbyexample](https://learnbyexample.github.io/tutorial/ebook-generation/customizing-pandoc/)
- [beejjorgensen/bgipc: Beej's Guide to Unix Interprocess Communication source](https://github.com/beejjorgensen/bgipc); uses [Beej's Guide Build System for Pandoc](https://github.com/beejjorgensen/bgbspd).


## See also

- [Laika](http://planet42.github.io/Laika/index.html) -- Text Markup Transformer for sbt and Scala applications, transforming [markdown](https://shared.btbytes.com/p/markdown) and reStructuredText to [HTML](https://shared.btbytes.com/p/html) and PDF
- [lise-henry/crowbook](https://github.com/lise-henry/crowbook) -- converts books written in Markdown to HTML, [LaTeX](https://shared.btbytes.com/p/latex)/PDF and EPUB.
* [Gotenberg · A Docker-powered stateless API for converting HTML, Markdown and Office documents to PDF.](https://thecodingmachine.github.io/gotenberg/#introduction)

## Styling

- [jez/pandoc-sidenote: Convert Pandoc Markdown-style footnotes into sidenotes](https://github.com/jez/pandoc-sidenote)
- [panam stylesheet for pandoc](http://benjam.info/panam/)
- [cysouw/toc-css: Pandoc Lua Filter to add table of contents to the side](https://github.com/cysouw/toc-css)
- Use [GitHub - jez/pandoc-sidenote: Convert Pandoc Markdown-style footnotes into sidenotes](https://github.com/jez/pandoc-sidenote) along with [GitHub - jez/tufte-pandoc-css: Starter files for using Pandoc Markdown with Tufte CSS](https://github.com/jez/tufte-pandoc-css) to render markdown into [Edward Tufte](https://www.btbytes.com/people/Edward-Tufte) style documents, as seen here - [Tufte Pandoc CSS](https://jez.io/tufte-pandoc-css/) and [Tufte CSS](https://edwardtufte.github.io/tufte-css/)


## Sites built using Pandoc

* [Openresty.org](https://github.com/openresty/openresty.org/blob/master/v2/Makefile) uses Pandoc, makefile and perl.
* [website/make at master · kisslinux/website](https://github.com/kisslinux/website/blob/master/make)

## Book publishing

* [The Tools I Use To Write Books - Thorsten Ball](https://thorstenball.com/blog/2018/09/04/the-tools-i-use-to-write-books/)
		* [pp](https://github.com/CDSoft/pp) is a text preprocessing tool written in [haskell](https://shared.btbytes.com/p/haskell) (just like pandoc), the implements - macros, literate programming, diagrams - graphviz, plantuml, ditaa,  blockdiag, figures - asymptote, R, scripts - bash, cmd, python, lua, R, and mustache  templating. apparently to be replace by [ypp](https://cdelord.fr/ypp.html) and [panda](https://cdelord.fr/panda.html)
* [Writing a Book with Pandoc, Make, and Vim — Vladimir Keleshev](http://web.archive.org/web/20200412210227/https://keleshev.com/my-book-writing-setup/)
* [Technical Writing with Pandoc and Panflute](https://lee-phillips.org/panflute-gnuplot/)
* [max-heller/mdbook-pandoc: A mdbook backend powered by Pandoc.](https://github.com/max-heller/mdbook-pandoc?tab=readme-ov-file)


> + [output.pandoc.profile.pdf] + output-file = "output.pdf" + to = "latex"


## Using with weasyprint

From an [HN thread](https://news.ycombinator.com/item?id=22856362):

It's even possible to replace (Xe)LaTeX with [weasy](https://weasyprint.org/), a [Python](https://shared.btbytes.com/p/python) HTML-to-PDF converter. It supports two-colums via CSS, automatic CSS hypens, [CSS](https://shared.btbytes.com/p/css) page counters and embedding SVGs. I just needed an HTML header with CSS in the markdown file.

```
$ pandoc --filter pandoc-citeproc --csl ieee.csl --bibliography=paper.bib --smart --normalize -f markdown+multiline_tables+inline_notes -t html5 -V margin-top:0.5in -V margin-bottom:0.5in -V margin-left:0.5in -V margin-right:0.5in -o output.html input.md
$ python3 -c "from weasyprint import HTML; HTML('output.html').write_pdf('output.pdf', presentational_hints=True)"
```

For LaTeX-style math equations I added [mathjax-pandoc-filter](https://github.com/lierdakil/mathjax-pandoc-filter) as filter to the pandoc args:

    --filter ~/node_modules/.bin/mathjax-pandoc-filter -Mmathjax.centerDisplayMath -Mmathjax.noInlineSVG

## SVG2PDF

^b5a0d2

If you are trying to convert an HTML page to PDF using Pandoc, and the [HTML](https://shared.btbytes.com/p/html) page has [svg](https://shared.btbytes.com/p/svg) drawings (e.g.: this excellent post - [The Big LLM Architecture Comparison](https://magazine.sebastianraschka.com/p/the-big-llm-architecture-comparison) by [Sebastian Raschka](https://www.btbytes.com/people/Sebastian-Raschka)), pandoc might choke on it unless you have `rsvg-convert` installed (on [macOS](https://shared.btbytes.com/p/macos): `brew install svg2pdf`). As you can see from this [commit](https://github.com/jgm/pandoc/commit/6b72c5e35ba9b0872704b77b2bd8793657adcaba) that added passing svg through `rsvg-convert` command to covnert it into a png file.

also had to install the [latex](https://shared.btbytes.com/p/latex) svg package.

![](https://files.btbytes.com/screenshots/2025/latex-svg-package.png)

even after this the PDF generation failed with:
```
pdflatex: major issue: User/administrator updates are out-of-sync.                                                                                                    Error producing PDF.
! Package svg Error: File `1e7afdcc9b596b58d739c7d01b66c47cb52f6c23_svg-tex.pdf                                                                                       ' is missing.
                                                                                                                                                                      See the svg package documentation for explanation.
Type  H <return>  for immediate help.                                                                                                                                  ...
                                                                                                                                                                      l.140 ...dcc9b596b58d739c7d01b66c47cb52f6c23.svg}}

```