Use Pandoc to render servant API documentation

Version on this page:
LTS Haskell 10.3:
Stackage Nightly 2018-01-18:
Latest on Hackage:

See all snapshots servant-pandoc appears in

MIT licensed by Matthew Pickering, Ivan Miljenovic
Maintained by

Module documentation for

Hackage Build Status

An extension to servant-docs that allows you to use Pandoc to render your Servant API documentation.

How to use this package

Generate documentation directly

A very simple program to render the API documentation as a mediawiki document might look as follows.

import Text.Pandoc
import Servant.Docs.Pandoc
import Servant.Docs
import Data.Default (def)

myApi :: Proxy MyAPI myApi = Proxy

writeDocs :: API -> IO ()
writeDocs api = writeFile "" (writeMediaWiki def (pandoc api))

Create a Pandoc filter

The makeFilter function allows you to make a filter which can be used directly with pandoc from the command line. This filter will just append the API documentation to the end of the document. Example usage:

-- api.hs
main :: IO ()
main = makeFilter (docs myApi)

Then to run this:

pandoc -o api.pdf --filter=api.hs

Custom filters

A more sophisticated filter might be to actually convert introduction and note bodies to Markdown before processing (note: this is not enabled by default as the pandoc library is GPL-licensed, whereas this library uses pandoc-types which is BSD3-licensed):

import Data.Monoid         (mconcat, (<>))
import Servant.Docs.Pandoc (pandoc)
import Text.Pandoc         (readMarkdown)
import Text.Pandoc.JSON    (Block(Para, Plain), Inline(Str), Pandoc(Pandoc),
import Text.Pandoc.Options (def)
import Text.Pandoc.Walk    (walkM)

main :: IO ()
main = toJSONFilter append
    append :: Pandoc -> Pandoc
    append = (<> mconcat (walkM parseMarkdown (pandoc myApi)))

parseMarkdown :: Block -> [Block]
parseMarkdown bl = case bl of
                     Para  [Str str] -> toMarkdown str
                     Plain [Str str] -> toMarkdown str
                     _               -> [bl]
    toMarkdown = either (const [bl]) unPandoc . readMarkdown def

    unPandoc (Pandoc _ bls) = bls


## -- 2018-01-17

This release has behavioural changes to match how servant-docs 0.11.1
works (hence the major version bump).

API Change:

* Add `pandocWith` that takes in a `RenderOptions`. This allows for:

- Selecting whether to show all or just one mime-type for requests
and responses.

- Optionally group all Notes under a common header.

Behavioural Changes:

* Display notes, auth

* Rationalise header depths

* Document the HTTP method the parameters of an endpoint belong to
(rather than assuming `GET` for all of them).

* Handle multiple content types for request/response bodies.

* Add a grouping header for the Headers and endpoint is sensitive to.

## -- 2017-07-25

Supports servant-docs 0.11. Changed behaviour means that this release
can no longer support older versions.

## -- 2017-07-25

Updated dependencies for http-media, pandoc-types and servant-docs.

New maintainer: Ivan Miljenovic

## -- 2015-11-18

Explicit import list for lens to hopefully avoid dependency problems.

## -- 201-07-26

Modify version bounds

## 0.4.1 -- 2015-06-26

Put end points in canonical order.

## 0.4.0 -- 2015-05-23

Update for servant 0.4

## -- 2015-01-04

Fix breaking interface change from servant-docs 0.3

## -- 2015-01-04

Fix trailing "," when rendering list of values

## 0.1 -- 2015-01-04

Initial release
comments powered byDisqus