markup-export

This project is a wrapper around Pandoc that aims to help organize and manage yaml-templates and ease & accelerate overall use of Pandoc.

Features

Templates

• everything native Pandoc yaml-templates can do
• include templates into other templates for modular structure and reusability
• specify Pandoc CLI options in templates
• sensible template presets for reference & quick start
• interactive template picker with tree structure

Source files

• arbitrary numbers of .md and bibliography files and directories are handled automatically

Other

• only one Python dependency: PyYAML
• see issues for planned features & feel free to add requests!

Setup

• install Pandoc
• install requirements from requirements.txt, e.g. /usr/bin/env python3 -m pip install -r requirements.txt
• set up .env (cp .env.example .env and optionally modify to your liking)

Usage

Execute main with sources as positional arguments. Sources can be files or directories; all found .md files will be treated as textual content (sorted alphabetically in traversing order) and all bibliography files will be added as bibliographic references.

Environment options

Specify environment variables before executing markup-export or set them in your .env file.

• CMD_EDITOR is the command to run to open your editor. The string {} will be replaced with the file to edit. To use vim for example set CMD_EDITOR=vim {}
• CMD_QUICKLOOK is the command to run to quick-look / preview an exported file (again, given by {}). On MacOS you can use Finder's Quicklook action with CMD_QUICKLOOK=qlmanage -p {} >& /dev/null.
• If QUICKLOOK_BY_DEFAULT is set to one of 1, true, t, True or T, an exported file will be previewed when the CLI argument -q is not given; otherwise it is the other way around.
• TEMPLATE_DIR specifies the (relative) template directory used to store template files.
• TEMPLATE_RECENT is the name the last used template is stored as in the template directory.

Optional CLI arguments

• -o FILENAME, --out FILENAME to specify the output. This can be a .pdf or any other output format supported by Pandoc
• -t TEMPLATE, --template TEMPLATE to specify the template to use. TEMPLATE is used to identify a template (.yaml-file) in the template directory. Templates in subdirectories, e.g. in presets are identified by preceding their name with the subdirectory's name, e.g. presets/plain for the given preset Plain. Note that a directory or file name's prefix is sufficient to identify it, i.e. pre/pl or even p/p would be enough to pick presets/plain if no other template matching this string exists.
• -r, --recent lets you use the last used template again.
• -e [SAVE_AS], --edit [SAVE_AS] lets you edit and optionally save the chosen template before using it for the export. It will open the template in your editor and, if SAVE_AS was given, save it with this name (subdirectories can be set with / separators) into your template directory.
• -i, --interactive is an alternative to -t and -e; it will display your templates as a tree and ask you to input a template analogous to the -t option. You can edit the template by suffixing the word new and save the edit with new as SAVE_AS analogously to the -e option.
• -d, --debug enables passing through stdout and stderr of Pandoc's subprocess which is useful for debugging your custom templates.
• -q, --quicklook reverses the behavior specified by the environment setting QUICKLOOK_BY_DEFAULT