A Ruby gem and wrapper for the Pandoc document converter
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

rakali.rb

Build Status Gem Version Code Climate Test Coverage

Rakali is a wrapper for the Pandoc document converter with the following features:

  • bulk conversion of all files in a folder with a specific extension, e.g. .md.
  • input via a configuration file in yaml format instead of via the command line
  • validation of documents via JSON Schema, using the json-schema Ruby gem.
  • Logging via stdout and stderr.

Installation

gem install rakali

Use

Provide a configuration file in yaml format as input:

rakali convert .rakali.yml

The default configuration looks like this:

from:
  folder:
  format: md
to:
  format: html
schema: default.json
citations: false
strict: false
merge: false

The only required key for the input yaml file is from folder (missing in the default file), and you can override any key in the default file.

  • schema: JSON schema used for validation. Use your_folder/schema.json for a custom schema, or use one of the built-in schemata (see pandoc-schemata for a list.)
  • citations: include -f citeproc-pandoc for citation formatting
  • strict: abort conversion on validation errors
  • merge: merge all input files into a single file

Validation against JSON Schema also works directly with Pandoc, generate a JSON representation of the internal Pandoc document format (abstract syntax tree or AST) with pandoc -o file.json, and use a JSON Schema file for validation. If possible, please contribute your schema files to the pandoc-schemata.

To integrate rakali into a continuous integration environment such as Travis CI, add a configuration file (e.g. .rakali.yml) into the root folder of your repo, install Pandoc and the rakali gem and run rakali convert .rakali.yml. Look at .travis.yml, .rakali.yml and the examples folder in this repo for a working example.

Options and variables

Include Pandoc options and variables in the yaml input file:

options:
  latex-engine: xelatex
variables:
  documentclass: article

Filters

Rakali can use Pandoc filters and uses the same conventions: they can be written in any language as long as the files are executable and they use Pandoc JSON as input and output format. Rakali includes the behead2.hs example from the Pandoc documentation, for filters that are not part of rakali include the path. Filters are processed in the order they are listed.

filters:
  - behead2.hs
  - your_folder/caps.py

Feedback

This is an early release version. Please provide feedback via the issue tracker.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Release notes

Are here.

License

MIT License.