This project is a wrapper around Pandoc that aims to help
organize and manage yaml
-templates and ease & accelerate overall use of Pandoc.
- 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
- arbitrary numbers of
.md
and bibliography files and directories are handled automatically
- only one Python dependency:
PyYAML
- see issues for planned features & feel free to add requests!
- 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)
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.
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 usevim
for example setCMD_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 withCMD_QUICKLOOK=qlmanage -p {} >& /dev/null
.- If
QUICKLOOK_BY_DEFAULT
is set to one of1
,true
,t
,True
orT
, 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.
-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. inpresets
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 evenp/p
would be enough to pickpresets/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, ifSAVE_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 wordnew
and save the edit withnew as SAVE_AS
analogously to the-e
option.-d, --debug
enables passing throughstdout
andstderr
of Pandoc's subprocess which is useful for debugging your custom templates.-q, --quicklook
reverses the behavior specified by the environment settingQUICKLOOK_BY_DEFAULT