Differences Between Actuarius And Standard Markdown

chenkelmann edited this page Feb 6, 2012 · 1 revision

I tried very hard to have Actuarius behave the same way as the original Markdown, there is however one way in which I diverted from the original behavior, specifically the way Actuarius starts new block elements like paragraphs, code blocks, block quotes and lists.

For the original Markdown any consecutive number of lines is a paragraph unless the block starts like a quote (> foo), a list (* foo or 1. foo) or a header (#foo). Once a paragraph is started, it will only end until it encounters an empty line, the start of a blockquote or a heading. So blockquotes and headings “stop” paragraphs:

this is a 
> but it ends here

this paragraph
#is stopped by this heading

Lists and code blocks however, do not stop a paragraph in original Markdown:

this is a 
* and it does not stop here
2. or here
    //or here

Frankly, when trying Markdown for the first time i found this very confusing, so i decided to change it. Starting a line like a list item or a code example will trigger the start of a list or verbatim code block respectively and end the current paragraph. The best way to get a feel for the difference is to try the above example in the Web Dingus of the original Markdown and my JVM Multi Dingus.

The original Markdown also allows “shortcut rules” to continue quotes or items. So a block quote does for example not need a “> ” before every line (but they can have them). The same goes for list items, consecutive lines do not need to be indented (but can be):

> this starts a block quote
this is still a block quote
# this is a header in a block quote
* this list item however is *not* in a block quote

* this list item
is continued here
# and here
> but not here

This gets very confusing if you feed the original Markdown this innocent looking block:

* foo
> bar

The original Markdown’s output is the following



Which is anything but well formed. To summarize, by trial and error I discovered the following rules how the original Markdown starts and ends blocks (all blocks are ended by empty lines however):

  • Block quotes are ended by: lists but not by paragraphs, headers and code blocks
  • Lists are ended by: block quotes but not by paragraphs, headers and code blocks
  • Paragraphs are ended by: block quotes and headers but not by lists and code blocks
  • Code Blocks are ended by: every other block

I definitely do not like violating established standards (I do not want Actuarius to turn into the Internet Explorer of Markdown parsers), but I found this behaviour too confusing when writing my own Blog articles, so I decided to change the rules here. So here is how Actuarius does things:

Every block ends every other block. There are only three exceptions:

  • Paragraphs continue a block quote (to enable the shortcut rule that you can quote a whole paragraph by prepending a >)

      > blockquote
      still blockquote
          //but this is a code block that
          //is not nested in the quote  
  • Paragraphs continue a list (so you don't have to indent every line in a list item).

      * list item
      still list item
      > but here starts a quote
  • Lines starting with four spaces like code blocks also continue a list item to allow nesting of content in a list:

      * list item
          > quote in a list item
              //code in a list item
          * list item in list item

I hope you like these changes, for me they just save a lot of frustration when I write using Markdown, I just think the following is a paragraph followed by a list:

This is a paragraph
* and this should be
* a list
* don’t you think?