Custom Markdown in Pandoc

#functional #haskell #hakyll

You can keep reading here orjump to my blog to get the full experience, including the wonderful pink, blue and white palette.

The architecture of Pandoc is well described in thedocumentation:

Pandoc consists of a set of readers and writers. When converting a document from one format to another, text is parsed by a reader into pandoc’s intermediate representation of the document—an “abstract syntax tree” or AST—which is then converted by the writer into the target format.

For example, let's take a Markdown file:

``haskellx= 1``

Pandoc translates it to the following AST:

stackinstallpandocstackexec-- pandoc-s-f markdown-t native file.markdown# Pandoc#   (Meta {unMeta = fromList []})#   [CodeBlock ("",["haskell"],[]) "x = 1"]

CodeBlock is one of the value constructors of theBlock type:

dataBlock=CodeBlockAttrText--  | ...typeAttr=(Text,[Text],[(Text,Text)])--           ^ Id--                 ^ Classes--                         ^ Key-Value pairs

Pandoc allows changing the AST before the output document is written.

One way to achieve that is by using a filter:

#!/usr/bin/envrunghc{-# LANGUAGE OverloadedStrings #-}importText.PandocimportText.Pandoc.JSONmain::IO()main=toJSONFiltertransformtransform::Block->Blocktransform(CodeBlockattrcontent)=CodeBlockattr"y = 2"transformx=x

I'm usingrunghc in this case to make sure the version of Pandoc used in the filter is the same as the one invoked on the command line:

stackexec-- pandoc-s-f markdown-t native--filter filter.hs file.markdown# Pandoc#   (Meta {unMeta = fromList []})#   [CodeBlock ("",["haskell"],[]) "y = 2"]

Notice that the code changed fromx = 1 toy = 2.

The same can be achieved in pure Haskell code:

{-# LANGUAGE OverloadedStrings #-}importData.TextimportText.PandocimportText.Pandoc.JSONimportText.Pandoc.Walkmain::IO()main=dofile<-readFile"./file.markdown"result<-runIO$dodoc<-readMarkdown(def{readerExtensions=pandocExtensions})(packfile)lettransformed=walktransformdocwriteNative(def{writerExtensions=pandocExtensions})transformedhandleErrorresult>>=putStrLn.unpacktransform::Block->Blocktransform(CodeBlockattrcontent)=CodeBlockattr"y = 2"transformx=x

stack runghc pure-haskell.hs# [CodeBlock ("",["haskell"],[]) "y = 2"]

With Hakyll, similar transformations can be achieved by usingpandocCompilerWithTransform orpandocCompilerWithTransformM.

That is how tweetable pull quotes areimplemented on this blog. In particular, the following Markdown

``pullquoteIf we are not open to silly ideas, then why even bother with a creative activity in the first place?``In a recent workshop I attended one rule was "all ideas are brilliant". Yes, at first an idea could be raw, maybe even silly. However, by thinking outside the box, it may turn into something innovative. More often than not though, it will be a draw in the blank. Still, if we are not open to silly ideas, then why even bother with a creative activity in the first place? In fact, if you always do what you've always done, you'll always get what you've always got.

becomes