banias is a simple MIT-licensed shellfire script wrapping pandoc to make it easy to create PDF and Latex documents directly from markdown stored in Git. It's intended to be used as a git submodule.
- If there is a Pandoc extension
pandoc_title_block
then the values of Author, Title and Date from this will take preference over those in aREPORT.yaml
metadata section - When concatentating markdown files, we insert a line feed between each file
- If there is a file called
REPORT.FORMAT.yaml
, then this will be concatenated beforeREPORT.yaml
- This allows one to have format-specific settings and overrides
- Only files ending
.md
are included - The metadata
.yaml
files are included before any markdown
- banias is designed so that most of what you want can be achieved using symlinks.
- Use symlinks to re-use template fragements that are common to only a subset of documents
- Use folder symlinks to share common sets of templates
- Use symlinks to re-use per-report YAML metadata
- Settings for PDF and Latex documents are frequently the same. Use a symlink from
REPORT.latex.yaml
toREPORT.pdf.yaml
to keep these in-sync
- Pandoc-as-a-service (solves a lot of deployment issues)
- Add in
---
before and after YAML documents in case it's missing- Could use the
file
command to detect YAML
- Could use the
- Yaml Metadata
- Explore a folder-based approach (like conf.d) to allow re-use of snippets
- Do this at a reports level, too
- Explore using
pandoc-options: -VstandardWaiver=$(cat include/standardWaiver.md)
(see https://groups.google.com/forum/#!topic/pandoc-discuss/pe63zLmNwtk)
- Templates
- Re-use the pandoc data-dir approach (overriding the user data dir or merging the pandoc directories together)
- Pre-Processing
- Generation of images (eg stormmq logo from vector graphics)
- Images
- What about when using HTML? Can we differentiate between embedded and re-used?
- Formatting
- Nice borders for figures in PDFs (but not inline images, perhaps)
- Bibliography
- Embed revision history, authors from git
- Explore default yaml for documents
- Default the 'lang' to english (en)
- Default the date from git revision
- Likewise, default the author [this is first author, not last author]
- ?default title to something obviously wrong?
- Could have default-per-format, too
- Consider generating 'lot: true' and 'lof: true' by detecting presence of tables with captions and figures
- More formats
- latex-snippet
- html-snippet
- html
- Explore: Unlike pandoc, banias has separate templates for PDFs and Latex; this is because they differ in needs
- Review:-
- Filter support: https://github.com/jgm/pandoc/wiki/Pandoc-Filters
curl -LH "Accept: text/bibliography; style=bibtex" "http://dx.doi.org/10.1017/S0022112061000019"
citations!- jgm/pandoc#813