akshaybadola/pndconf

Pandoc configuration manager, file watcher and document generator.

pndconf

Highly customizable pandoc configuration manager, file watcher and document generator. Useful for easy conversion of documents with sensible defaults.

Automatic conversion of markdown to various formats with pre defined settings via templates and folder watch with preview.

Installation

• Requires python>=3.7.
• Can be installed via pip by pip install -U git+https://github.com/akshaybadola/pndconf.
• PyPi package coming soon.

Usage

• pndconf watch -g pdf,html watches all directories and subdirectories for .md files and compiles if it notices any changes to pdf and html format.
• pndconf convert -g pdf yourfile.md will convert yourfile.md to yourfile.pdf
• pndconf convert -g pdf,html yourfile.md will convert yourfile.md to yourfile.pdf and yourfile.html
• pndconf convert -g reveal,beamer yourfile.md will convert yourfile.md to yourfile.pdf and yourfile.html in presentation formats

Options

• pandoc is used for generation and should be in the current path. pandoc switches for the formats are stored in a configuration file in ini format.
• If no config file is provided then a default config is used.
• See pndconf watch --help and pndconf convert --help for the list of options.
• You can pass additional pandoc options at the end of the command line e.g. pndconf convert -g pdf yourfile.md --template=yourtemplate.
• An optional pandoc path can be specified with --pandoc-path switch.
• Current pandoc options can be dumped with pndconf -po
• Current config can be dumped with pndconf --dump-default-config

Templates

Pandoc templates usually come installed with pandoc but you can check search templates online and specify accordingly.

One revealjs template is given in examples. Run pndconf convert -g reveal beamer.md --template=reveal.template to see the result.

Beamer

By running pndconf convert -g beamer beamer.md you select pandoc’s internal template. Instead if you run pndconf convert -g beamer beamer.md --template=beamer.template then the template present in the examples directory is chose. Keep in mind that some options will work only with that template.

The beamer.template file in the examples directory will work only with pandoc>==2.14 For older versions use beamer_old.template.

See examples/beamer.md for additional options.

Pandoc installation

• You can either install pandoc through your distribution
  • apt-get install pandoc,{-citeproc,-data} for debian/ubuntu
  • dnf install pandoc,{-citeproc,-common} for fedora See your distribution packages for others.
• You can also install via cabal-install for the latest version
  • pandoc-2.14 has citeproc inbuilt and has some extra features which are quite useful. For versions of pndconf>==0.4.2 only pandoc>=2.14 is supported.
  • While installing via cabal-install it’s preferable to update your haskell compiler first to the latest version.
  • For GHC use at least 8.8.2
    • Then do cabal update cabal-install first
    • Then cabal update pandoc

Templates and CSL

pandoc comes with default templates which can be used for simple document generation. However if you need to customize it you can search for other templates. Path to the templates directory can be specified via --templates-dir option.

If no templates-dir is given and a template is specified it’s searched in the following order: - Absolute path of the template - In the same path as the input file(s). - A templates directory if it exists, in the same directory as the input file(s)

A beamer.template is present in examples directory to help in generating a beamer document. CSL files are searched in a similar manner.

A compendium of citation styles is available at styles. You can either clone the repository or download the required style files to a directory and give the path to pndconf with --csl-dir.

Examples

A couple of examples are provided in the examples directory. After installation run: - pndconf -g pdf This will watch for all markdown files and generate an article for each of them as they change

• pndconf --input-files beamer.md -g beamer. This requires a beamer template which is included in the templates directory.
• pndconf -ro --input-files beamer.md -g beamer. This does not watch the filesystem for changes and only generates the beamer slides.

You can check the input files and the metadata there. beamer.md specifies the beamer template for generation and also ieee csl file. That is also included in the csl directory.

Configuration

A sensible default configuration is included in the distribution but it can always be customized.

Todo

• [X] Remove the settings folder from the repo. It should be standalone.
• [X] Remove blog generator as that’s a separate repo now.
• [X] Simpler generation of basic files
• [X] Hierarchical command line parser for separate commands for generation, watching etc.
• [ ] Documentation for LaTeX requirements
• [ ] Documentation for templates
• [ ] Examples of complex pipelines
• [ ] Auto installation of TeX includes, user TeX setup
• [ ] Fix include and exclude regex options.
• [ ] Clean the code up
• [ ] Better colorization possibly with colorama
• [ ] A A/WSGI server for async communication
• [ ] Add documentation of internals
• [ ] Add tests
• [ ] Issue warning when incompatible options are used, e.g. –biblatex and pandoc-citeproc conflict.