Render a servant API to Pandoc's native representation
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

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