Skip to main content


pandy is a command line wrapper for pandoc plus cool stuff (if you use Markdown - HTML). Basically takes a file/folder, the input markup to convert from, the output markup and runs it through Pandoc.


  • Output folder keeping or not the folder structure
  • Source can be a file, a folder, .list containing file paths or .ini
  • Formats: some of them have abbreviations (see below)
  • Output format: you can have more than one! just separate them with spaces
  • You can create a nice book (HTML, just adds navigation links between files) like a wiki or for documentation. If you don't like/want Next-Prev navigation links, you can use the file's title. It creates a nice simple index file or you can include your own.
  • Use a config file: so you don't have to remember all the arguments or write a 'wrapper' script for a 'wrapper' script :)
  • [TOC] support. That means that a file that has it, will have a TOC. No more separating files: these ones with TOC, these ones without, and finally place them in the same folder.
  • If you use Markdown and convert to HTML there are some goodies for you! abbreviations (real abbreviations; they are parsed and not ignored as pandoc does), admonitions and WikiLinks
  • No-so-ugly default template for book :)


Run it as pandy SOURCE [options]

Formats are stripped down to the most common ones:

  • from: docbook, html, json, latex, markdown, markdown_github, markdown_mmd, markdown_phpextra, markdown_strict, mediawiki (or mw), opml, rst, textile
  • output: all the above + asciidoc, beamer, docx (or doc), epub, epub3, fb2, html5, odt, opendocument (or opendoc), pdf, plain, rtf, slides (or slide)
All "markdown"s can be entered as "md". So: markdown -> md; markdown_github -> md_github; etc. Also, "link_attributes" and "hard_line_breaks" are automatically enabled.

The slides are specified with --slides

If you merge and use output, you must only specify the folder. It takes the name from the parent folder/source.

pandy accepts some of the pandoc's commands but with different names:

File, folder, .list or .ini. A .list is a file that contains the paths to files in order to be parsed.
--from, -f
Input format
--to, -t
output format/s (can be a space separated list)
--output FOLDER, -o FOLDER
Output folder
self contained file
--header FILE
Header file. Included as it is (raw, verbatim)
--footer FILE
Footer file. Included as it is (raw, verbatim)
--index FILE
Custom index file for book. Can use wiki links
Use html4 output instead of html5
--merge, -m
Merge files.
--slides FORMAT
Slides format.
--bib FILE
Use bibliography file
--css FILE
External CSS
--highlight STYLE
Highlight style.
No highlight
--tpl FILE
Template file.
--toc, -t
Include TOC
--depth NUMBER
TOC depth.
e-mail obfuscation
Wrap sections in <section>s, attach identifiers instead of titles
--pandoc PANDOC
Pandoc path. Default: pandoc
--data-dir FOLDER
Data directory
Don't keep folder structure
--book, -b
Make a book with navigation (next/prev) and index
--no-nav, -nn
(For book) disable book navigation
--nav-title, -nt
(For book) use titles in navigation
--no-side, -ns
(For book) Disable sidebar navigation
--no-side-toc, -nst
(For book) disable TOC in sidebar (keep in doc)
--config FILE
Use a configuration file (key=value)
(For book) Pandy's embebed template: simple and not so ugly

If you use Markdown and convert to HTML, there are some goodies for you. You can have abbreviations, as PHP Markdown Extra (that are parsed as they should be):

 Some text with an ABBR and a REF. Ignore REFERENCE and ref.

  *[ABBR]: Abbreviation
  *[REF]: Abbreviation Reference

And admonitions with this markup:

 [class/type:optional title]
  - markdown
  - super
  - content

The class/type would be something like "information", "danger", "tip", "hint", "hungry", "duck", "yay"...

You can also include a tag for TOC ([TOC]) to have that file with a TOC instead of remembering to enter --toc or separating files in two groups and then placing them together. (It just adds it automatically after searching the file, no magic here).

"Book" converts all files to HTML and adds navigation links. Useful to make simple documentation.


To see a live example of this usage, check my japanese notes

If you use Markdown you have more goodies: create your own index (as and have wikiLinks. Wikilinks can be in any file as [:filename][optional title] where filename can have extension or not, and if you don't include a title, it finds the file title. The order of the files in the index affect the sidebar navigation. With this you can create cooler documentation or use it as a simple wiki.


If you wish to create your own template for book, pandy adds some variables for you to include:

Variable Explanation
side_navigation the sidebar navigation
book_navigation book navigation (previous/index/next)
project-index link to index. Useful if you have subfolders
project-title Index title. Useful if you create your own index with a title

If you don't like setting the options in the CLI, or having a script which calls pandy with the arguments you prefer, you can create your configuration in a key = value file (like ini). Example:

 PANDOC_DATA_DIR = C:\Program Files\Pandoc
 TEMPLATE = github.html
 HIGHLIGHT= zenburn
 FORMATS_TO = html pdf
 NAV = True

Specify the configuration file with --config (the extension doesn't matter, INI headers are ignored. Don't worry) or just have a settings.ini where you run pandy.


pandy 2.0.3
Needs Pandoc and Python 3

Python 3


Version 2.0.3

  • misc fixes/bugs
  • fixes for css

Version 2.0

  • Total rewrite! Many fixes and (internal) cleanup/improvement.
  • new wiki links: like markdown reference links but inverted: [:file][title]
  • wikilinks in any file (not only index) (book)
  • auto discover index
  • if custom index has title, use it as project title
  • list all titles (and toc) in index
  • order files according to custom index
  • navigation: pages titles in sidebar, next-prev
  • option to hide navigation in book
  • option to exclude toc from sidebar navigation
  • Navigations in pandoc variables
  • built-in template (book)
  • modify command options
  • read .ini automatically in folder where runs/source
  • args take precedence over ini, which take precedence over default
  • change .ini format. See examples (basically remove quotes, lists are space separated)

Version 1.9

  • only python 3
  • fixes for book
  • prints file being converted
  • Filter extensions for converting, only html (hardcoded)
  • add titles in sidebar for navigation (--navside). Include book_navigation in your Pandoc template

Version 1.8.1

  • New admonition syntax

Version 1.8

  • Clean up code and refactoring
  • default config in dictionary
  • minor fix for admonitions
  • Fix finding H1
  • config file support (ini without sections)
  • changes to args
  • add processing messages
  • no more tmp files
  • Fix merging
  • merge (HTML): now can parse metadata block and have toc for full document
  • book: include toc ONLY on selected file
  • book: fix having title twice in file when declared with meta-block
  • fix titles in book: add them, if not found add the filename (no extension)
  • wikiLinks: if md link has no title and it's an existing file, use the filename as title
  • Book: warn if no output path (defaults to current directory) and source directory is the running one
  • config dict takes precedence over args

Version 1.5

  • Rewritten!
  • Add abbreviations parsing: markdown -> html
  • Add admonition parsing
  • Add warning when book also have other output formatting & html
  • Add warning custom index with wiki links only for markdown
  • Add more formats for input and output
  • fix: formats_to: no duplicates
  • fix: --nav only for book
  • fix: add html5 output default, can change to html with --html4
  • fix: when merging add title HTML tag

Version 1.0

  • First release
  • folder (recursive) support
  • merge files in directory (automatically)