BlogLiterately-0.8.8.2: A tool for posting Haskelly articles to blogs
Copyright(c) 2008-2010 Robert Greayer 2012-2013 Brent Yorgey
LicenseGPL (see LICENSE)
MaintainerBrent Yorgey <byorgey@gmail.com>
Safe HaskellSafe-Inferred
LanguageHaskell2010

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.

standardTransforms :: [Transform] Source #

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

optionsXF :: Transform Source #

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

profileXF :: Transform Source #

Load options from a profile if one is specified.

highlightOptsXF :: Transform Source #

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

passwordXF :: Transform Source #

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

titleXF :: Transform Source #

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

rawtexifyXF :: Transform Source #

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

wptexifyXF :: Transform Source #

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

ghciXF :: Transform Source #

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

uploadImagesXF :: Transform Source #

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

highlightXF :: Transform Source #

Perform syntax highlighting on code blocks.

centerImagesXF :: Transform Source #

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

citationsXF :: Transform Source #

Format citations.

Link generation

specialLinksXF :: Transform Source #

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

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

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

luckyLink :: SpecialLink Source #

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

wikiLink :: SpecialLink Source #

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

postLink :: SpecialLink Source #

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 

Fields

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

    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 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.

pioTransform :: (BlogLiterately -> Pandoc -> PandocIO Pandoc) -> (BlogLiterately -> Bool) -> Transform Source #

Construct a transformation from a function in the PandocIO monad.

runTransform :: Transform -> StateT (BlogLiterately, Pandoc) PandocIO () Source #

Run a Transform (if its condition is met).

Transforming documents

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

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

Utilities

fixLineEndings :: String -> String Source #

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