hgpandoc mercurial extension
The extension works by configuring hooks that, when executed, look for documentation "source files" matching a given set of patters and call pandoc with those files as its inputs.
It is possible to select the pandoc output formats (e.g. pdf, docx, html, etc) as well as when should the documentation files be updated (i.e. on commit, update and/or tag).
You must have pandoc installed. You can download it from pandoc's download page
By default hgpandoc assumes that pandoc is on the system or user path (which is the case if you use the pandoc installer on windows, for example). If it is not, or if you want to use some other pandoc executable, you can configure the extension to specify the pandoc executable location (see below).
Additionally, to generate PDF files (which is the default) you must also install pdflatex or other LaTeX engine. On windows MiKTeX works pretty well.
Note that in order for pandoc to be able to find pdflatex you must ensure that the MiKTeX bin folder is on your path.
Follow these steps to enable and configure the extension
- Enable the extension in your mercurial config file by adding:
hgpandoc = /path/to/hgpandoc.py
to the [extensions] section in your mercurial config file
- Select which files must be converted by setting the "hgpandoc.sources" key in a mercurial config file.
That is, add an [hgpandoc] section and in it add an "sources" key, which must contain a list of patterns matching the files that will be converted.
- Select the output formats that will be generated:
By default, the input files will be converted to PDF. To change the default format or to select more than one output format, set the "hgpandoc.to" key to a list of output extensions.
Any extension of any output format supported by pandoc can be used.
- Set when to call pandoc to generate the output files:
By default, pandoc is run whenever the user commits a revision or updates to a different revision. To can change the default setting add an "hgpandoc.hooks" key to your mercurial config file.
"hgpandoc.hooks" must be set to a list of hooks in which pandoc will be run. Valid hooks are:
- commit - update - tag
- Set the pandoc command line switches
You can use the "hgpandoc.switches" configuration key to select the options which will be passed as is to pandoc.
You can use this to enable the TOC generation, for example (by adding setting "hgpandoc.options" to --toc), etc.
It is also possible to configure per output format command line switches, by setting "hgpandong.switches.format", where "format" is a valid output format (susch as pdf, html, etc). and must be written in lower case.
- If necessary, set the location of the pandoc executable:
By default hgpandoc assumes that the pandoc executable is on the system or user path. If you want or need to specify the location of the pandoc executable you can do so by setting "hgpandoc.exe".
[hgpandoc] exe = "C:\Program Files\Pandoc\bin\pandoc.exe"
Note that the use of quotes is necessary if the path has spaces.
Depending on your configuration, the output files will be automatically updated whenever you udpate, commit or tag your repo.
Additionally, it is possible to update all or a subset of the output files at any time by running the "hg pandoc" command, which takes the following parameters:
hg pandoc [FILE_PATTERN] [--to FORMATS] [--switches PANDOC_SWITCHES] Look for files matching the sources patterns and call pandoc on them options: -t --to VALUE list of output formats (default: pdf) -s --switches VALUE conversion switches
Run pandoc on all markdown (.md) files whenever you update or commit
[extensions] hgpandoc = /path/to/hgpandoc.py [hgpandoc] sources = *.md
generate pdf and docx files from all markdown and textile files
[extensions] hgpandoc = /path/to/pandoc [hgpandoc] sources = *.md, *.textile to = pdf, docx hooks = update
Acknowledgements and License
This extension is Free Software and licensed under the terms of the GPL v2. Pandoc is a tool made by John MacFarlane. This tool uses pandoc through its command line interface.