alphagov/govspeak — pull request #25 by kalleth (2014-06-13 14:03:30+00:00)
Title: Create a new $LegislativeList markdown tag.

([Trello ticket](https://trello.com/c/lgFFfydK/59-manuals-alignment-for-manuals-disable-normal-list-markdown-3))

To allow editors to use their own numbering for ordered lists, we need to allow them to create a nested "ordered list" with a special class that can be used to turn off ordinary numbering and change intent levels
etc.

Kramdown by default munges our desired input format into an unholy terror of nested UL and OL tags, which isn't ideal.

Therefore, we had two options; either create our own list markdown parser from scratch avoiding kramdown altogether, or disable Kramdown's handling of ordered lists, treat it as an unordered nested list, and then replace the tag parts.

Given that writing a list markdown parser is somewhat complex (see https://github.com/gettalong/kramdown/blob/master/lib/kramdown/parser/kramdown/list.rb), We (me and @evilstreak) chose the latter approach.

However, there are two (known) downsides:

1. A dependency has been added on the internal workings of the kramdown gem, which may complicate upgrades.
2. This approach may not be thread safe.