knit-haskell v0.7.0.0

Introduction

knit-haskell is an attempt to emulate parts of the RMarkdown/knitR experience in haskell. The idea is to be able to build HTML (or, perhaps, some other things Pandoc can write) inside a haskell executable.
This package has some wrapping around Pandoc and the PandocMonad as well as logging facilities and some support for inserting hvega visualizations.
All of that is handled via writer-like effects, so additions to the documents can be interspersed with regular haskell code.

Supported Inputs

• markdown
• HTML (blaze, lucid or Text)
• latex
• colonnade tables
• hvega visualizations (via blaze HTML)
• Diagrams (via Diagrams SVG backend, inserted as HTML)

Examples

There are a few examples in the "examples" directory.

• SimpleExample demonstrates the bare bones features of the library. Creating a document from a few fragments and then "knitting" it into HTML text and writing that to a file. This includes hvega, diagrams and plots examples.
• MultiDocExample demonstrates how to build multiple documents.
• MtlExample demonstrates the same simple features as above, but runs them atop an example mtl stack, allowing access to the mtl stack's functionality during document assembly.
• RandomExample builds on the mtl example to show how you can also add an additional polysemy effect (in this case, Polysemy.RandomFu from polysemy-RandomFu) to your document-building. This one also demonstrates a use of colonnade for adding a formatted table to the document.
• ErrorExample.
  Similar to "SimpleExample" but throws a user error during document assembly.

Notes

• You should be able to get everything you need by just importing the Knit.Report module. That has the main functions for "knitting" documents from fragments and re-exports all the required functions to input the supported fragment types and create/write Html.
• This uses polysemy for its effect management rather than mtl.
  Polysemy's inference and performance are greatly improved if you enable the polysemy-plugin, which involves:

1. adding "polysemy-plugin" in build-depends and
2. Add "ghc-options: -fplugin=Polysemy.Plugin" to your package configuration. Pandoc effects and writer effects for document building are also provided.

• Polysemy is capable of "absorbing" some mtl-style monad constraints. This is demonstrated in RandomExample and composable absorbers for MonadReader, MonadWriter, MonadState and MonadError can be found in the polysemy-zoo.

• Pandoc templates are included for HTML output. See the examples for how to access them or specify others.

• If you use knit-haskell via an installed executable, it will find the templates that cabal installs. But if you use from a local build directory and use "cabal new-" or "cabal v2-" style commands, you will need to run the executable via some "cabal v2-" command as well, e.g., "cabal v2-run" otherwise the templates--installed in the nix-style-build store--won't be found.

• Though you can theoretically output to any format Pandoc can write--and it would be great to add some output formats!--some features only work with some output formats. My goal was the production of Html and that is the only output format that supports the hvega charting since hvega itself is just a wrapper that builds javascript to render in a browser.
  And so far that is the only supported output format.

• This is very much a WIP. So it's rough around the edges and in the middle. If you find it useful but have suggestions, please submit issues on github.

• I'm very interested in adding to the "zoo" of input fragments. Any PRs of that sort would be most welcome!

• I'm also interested in widening the possible output types--currently only HTML is supported--but that is quite limited now by hvega which only works in html output.
  But support could be added for other output types if hvega input is not required.