BlogLiterately-0.8.6: A tool for posting Haskelly articles to blogs

Text.BlogLiterately.Transform

Description

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

Synopsis

# Standard transforms

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

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

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

Load options from a profile if one is specified.

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

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

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

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

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

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

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

Perform syntax highlighting on code blocks.

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

Format citations.

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
github::userrepo@hash
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.

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.

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

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

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

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 Source #

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 FieldsgetTransform :: 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 -> BoolA condition under which to run the transformation.

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

Construct a transformation from a pure function.

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

Construct a transformation from a function in the IO monad.

Run a Transform (if its condition is met).

Run a pipeline of Transforms.

# Transforming documents

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

# Utilities

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