Text.BlogLiterately.Transform

Tools for putting together a pipeline transforming the source for a post into a completely formatted HTML document.

Standard transforms

These transforms are enabled by default in the standard BlogLiterately executable.

standardTransforms :: [Transform]

The standard set of transforms that are run by default (in order from top to bottom):

• optionsXF: extract options specified in [BLOpts] blocks in the file
• profileXF: load the requested profile (if any)
• passwordXF: prompt the user for a password if needed
• titleXF: extract the title from a special title block
• rawtexifyXF: pass LaTeX through unchanged
• wptexifyXF: turn LaTeX into WordPress format if requested
• ghciXF: run and typeset ghci sessions if requested
• uploadImagesXF: upload images if requested
• centerImagesXF: center images occurring in their own paragraph
• specialLinksXF: replace special link types with URLs
• highlightOptsXF: load the requested highlighting style file
• highlightXF: perform syntax highlighting
• citationsXF: process citations

optionsXF :: Transform

Extract blocks tagged with [BLOpts] and use their contents as options.

profileXF :: Transform

Load options from a profile if one is specified.

highlightOptsXF :: Transform

Read a user-supplied style file and add its contents to the highlighting options.

passwordXF :: Transform

Prompt the user for a password if the blog field is set but no password has been provided.

titleXF :: Transform

Potentially extract a title from the metadata block, and set it in the options record.

rawtexifyXF :: Transform

Pass LaTeX (inline or display) through unchanged (if the rawlatex flag is set).

wptexifyXF :: Transform

Format embedded LaTeX for WordPress (if the wplatex flag is set).

ghciXF :: Transform

Format embedded ghci sessions (if the ghci flag is set).

uploadImagesXF :: Transform

Upload embedded local images to the server (if the uploadImages flag is set).

highlightXF :: Transform

Perform syntax highlighting on code blocks.

centerImagesXF :: Transform

Center any images which occur in a paragraph by themselves. Inline images are not affected.

citationsXF :: Transform

Format citations.

Link generation

specialLinksXF :: Transform

Replace special links with appropriate URLs. Currently, the following types of special links are supported:

lucky::search

The first Google result for search.

wiki::title

The Wikipedia page for title. Note that the page is not checked for existence.

hackage::pkg

The Hackage page for pkg.

github::user/repo

The top page for the given repo on github.

github::userrepo#nnn

Link to a particular issue.

github::userrepo@hash

Link to a particular commit.

post::nnnn

Link to the blog post with post ID nnnn. Note that this form of special link is invoked when nnnn consists of all digits, so it only works on blogs which use numerical identifiers for post IDs (as Wordpress does).

post::search

Link to the most recent blog post (among the 20 most recent posts) containing search in its title.

For example, a post written in Markdown format containing

      This is a post about the game of [Go](wiki::Go (game)).
  

will be formatted in HTML as

      pThis is a post about the game of href="https://en.wikipedia.org/wiki/Go%20(game)"Go/a./p
  

You can also create a Transform with your own special link types, using mkSpecialLinksXF, and I am happy to receive pull requests adding new types of standard special links.

mkSpecialLinksXF :: [SpecialLink] -> Transform

Create a transformation which looks for the given special links and replaces them appropriately. You can use this function with your own types of special links.

standardSpecialLinks :: [SpecialLink]

The standard special link types included in specialLinksXF: luckyLink, wikiLink, postLink, githubLink, and hackageLink.

luckyLink :: SpecialLink

Turn lucky::search into a link to the first Google result for search.

wikiLink :: SpecialLink

Given wiki::title, generate a link to the Wikipedia page for title. Note that the page is not checked for existence.

postLink :: SpecialLink

postLink handles two types of special links.

post::nnnn

Link to the blog post with post ID nnnn. Note that this form of special link is invoked when nnnn consists of all digits, so it only works on blogs which use numerical identifiers for post IDs (as Wordpress does).

post::search

Link to the most recent blog post (among the 20 most recent posts) containing search in its title.

Transforms

data Transform

A document transformation consists of two parts: an actual transformation, expressed as a function over Pandoc documents, and a condition specifying whether the transformation should actually be applied.

The transformation itself takes a BlogLiterately configuration as an argument. You may of course ignore it if you do not need to know anything about the configuration. The --xtra (or -x) flag is also provided especially as a method of getting information from the command-line to custom extensions. Arguments passed via -x on the command line are available from the xtra field of the BlogLiterately configuration.

The transformation is then specified as a stateful computation over both a BlogLiterately options record, and a Pandoc document. It may also have effects in the IO monad.

• If you have a pure function of type @BlogLiterately -> Pandoc
• > Pandoc@, you can use the pureTransform function to create a Transform.
• If you have a function of type BlogLiterately -> Pandoc -> IO Pandoc, you can use ioTransform.
• Otherwise you can directly create something of type StateT (BlogLiterately, Pandoc) IO ().

For examples, see the implementations of the standard transforms below.

Constructors

Transform

Fields

• getTransform :: StateT (BlogLiterately, Pandoc) IO ()

  A document transformation, which can transform both the document and the options and have effects in the IO monad. The options record can be transformed because the document itself may contain information which affects the options.

• xfCond :: BlogLiterately -> Bool

  A condition under which to run the transformation.

pureTransform :: (BlogLiterately -> Pandoc -> Pandoc) -> (BlogLiterately -> Bool) -> Transform

Construct a transformation from a pure function.

ioTransform :: (BlogLiterately -> Pandoc -> IO Pandoc) -> (BlogLiterately -> Bool) -> Transform

Construct a transformation from a function in the IO monad.

runTransform :: Transform -> StateT (BlogLiterately, Pandoc) IO ()

Run a Transform (if its condition is met).

runTransforms :: [Transform] -> BlogLiterately -> Pandoc -> IO (BlogLiterately, Pandoc)

Run a pipeline of Transforms.

Transforming documents

xformDoc :: BlogLiterately -> [Transform] -> String -> IO (Either PandocError (BlogLiterately, String))

Transform a complete input document string to an HTML output string, given a list of transformation passes.

Utilities

fixLineEndings :: String -> String

Turn CRLF pairs into a single LF. This is necessary since readMarkdown is picky about line endings.