The Blogdown package

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

Warnings:

A library and executable that implement a modified, extended version of Markdown designed for writing blog posts.


[Skip to ReadMe]

Properties

Versions0.1.0, 0.1.1, 0.2.0, 0.2.1, 0.2.2
Change logChangeLog.md
Dependenciesbase (==4.9.*), containers (==0.5.*), MissingH (==1.4.*), parsec (==3.1.*) [details]
LicenseAGPL-3
Copyright(c) 2017 Alex Becker
AuthorAlex Becker
Maintaineracbecker@uchicago.edu
CategoryWeb
Home pagehttps://blogdown.io
Source repositoryhead: git clone https://github.com/alexbecker/blogdown
ExecutablesBlogdown
UploadedMon Apr 10 07:06:43 UTC 2017 by alexbecker

Modules

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for Blogdown-0.1.1

Note: If you are viewing this Readme on GitHub, its Blogdown-specific features will not render correctly. The Blogdown-formatted output is in test/goldens/Readme.html.

Blogdown

Blogdown is a markup language based on Markdown, designed for writing blog posts. Blogdown's goals are:

Because there is no Markdown standard and existing Markdown implementations disagree wildly even on simple cases, Blogdown cannot be 100% compatible with even a majority of Markdown implementations. While there have been attemps to create a common Markdown standard--most notably CommonMark--they are necessarily quite complex. The primary cause of this complexity is that Markdown insists on rendering something for every input, no matter how malformed. Blogdown is considerably simpler, and hopefully easier for authors to debug, because it fails on malformed inputs. With full compatability out of the window, I have chosen to make some other small improvements on Markdown syntax.

Installation

With Cabal or Stack

The recommended way to install any Haskell project is using Cabal or Stack. With these tools, you can simply run cabal install or stack build respectively.

Without Haskell Tooling

Because configuring Cabal and Stack can be tricky for Haskell beginners, Blogdown supports installation without any Haskell tooling.

First, install GHC, Parsec and MissingH, all of which are available through common Linux package managers. Then run ghc -isrc -o Blogdown src/Blogdown.hs in the repository's base directory.

Usage

The Blogdown binary reads from stdin and writes to stdout. Typical usage looks like:

cat blogpost.md | ./Blogdown > blogpost.html

Optional Styling and Scripts

It is recommended to include footnotes.css and footnotes.js on any pages which make use of Blogdown-generated footnotes, which improve the appearance of footnotes and allow them to be shown inline. These can be inlined using the --inline-css and --inline-js flags respectively^[inline].

Optional Flags

Blogdown accepts the following long-style flags:

Note: The inline-* options require additional files (located in assets) to function. These will be installed at a known location if built with Cabal or Stack, but if the binary is run on a different machine (e.g. a webserver) then the binary is built on, the machine must also have the assets directory, and the directory containing assets should be supplied via the environment variable blogdown_datadir_override.

Syntax

Differences from Markdown

Most of the syntax of Blogdown should be familiar to Markdown users, but some new syntax has been added, and some existing syntax has changed.

New Features

Blogdown adds footnote support to Markdown. Footnotes can be referenced inline with ^[footnote-name], which will render as a superscript link to a footnote-definition at the end of the document, which is defined by ~[footnote-name] followed by the footnote contents.

Markdown Incompatibilities

Blogdown does not support the Markdown syntax of underlining text with = or - characters to define a header, as this comes at a large cost in the parser implementation^[underline-parser-complexity]. The # syntax for headers is supported instead.

It also does not support using multiple trailing spaces to force a breakpoint at the end of a line. The <br/> tag is supported instead.

The \~ and \^ characters are now special, and must be escaped to be used in text. Additionally, while most Markdown implementations do not require escaping many special characters when their special meaning would not be valid, Blogdown always requires they be escaped.

Formal Description

The body of a Blogdown document consists of a sequence of block nodes, which in turn consist of inline nodes.

Block Nodes

Block nodes can contain any sequence of inline nodes, with the exception of code and HTML blocks, whose contents are rendered verbatim. Block nodes can span multiple lines and are terminated by a blank line, the beginning of another type of block, or the end of the document.

The following block node types are supported:

Inline Nodes

Inline nodes can generally contain a sequence of other inline nodes, but cannot contain nodes of the same type. Despite the name, inline nodes can span multiple lines, e.g. to accomodate line length limits.

The following inline node types are supported:

Footer

A Blogdown document may optionally include a footer after the body. The footer consists of a sequence of footnote definitions, each of which begins on a new line with ~[footnote-name] and consists of an arbitrary sequence of blocks. A footnote definition is only terminated by another footnote definition or the end of the document.

Escaping

Any character (special or not) can be escaped with \\. For a literal backslash, use \\\\. A backslash before a newline acts as a continuation character.

Planned improvements


~[inline] Inlining CSS and JS is not recommended if you will be rendering multiple Blogdown documents on a single page, e.g. multiple blog posts on a blog. Doing so will degrade network and browser performance slightly.

~[underline-parser-complexity] Supporting underlines for headers requires the parser to look-ahead arbitrarily far, resulting in quadratic time complexity.

~[footnote-numbering] Footnotes are auto-numbered in order of appearance, starting from 0 by default (this can be changed by passing the --footnote-index-from flag).