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 "api.mw" (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 manual.md 

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), toJSONFilter) import Text.Pandoc.Options (def) import Text.Pandoc.Walk (walkM) main :: IO () main = toJSONFilter append where 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] where toMarkdown = either (const [bl]) unPandoc . readMarkdown def unPandoc (Pandoc _ bls) = bls