Home

The philosophy

The Markdown philosophy is quite simple: be readable as plain text.

Being readable as plain-text, does not mean to look like the plain text version.

And so, began our journey into the Markdown parsing hell.

Line break

Line break are rendered as a space. So 2 lines of markdown may become 1 line of output. And pasting the rendered output back into the markdown source won't match the original.

To add a new line, you need to end it with an invisible double-space token.

That's the first "trick" you learn and need to explain to newcomers.

Lazy continuation

Because of this line-break convention, a newline may still be part of the previous block.

Christmas Wishlist:
- longer vacation
- new books
Thank you !

block nesting

This lazy continuation can have weird effect on listing

List can start at any number:

0. zero

Also without empty line
1. one
2. two

But only for the 1. case: 
0. too bad for you, zero

See: https://github.github.com/gfm/#example-284

Also list and blockquote both support nesting, and also depend on indent level ;)

Here is some examples with only 1 nesting, good luck guessing the output:

  * I'm followed by a ...
    > 4 spaces code ? quote ? continuation ?

> *  I'm followed by a ...
>    new quote ? new p ? same line ?

 > * I'm followed by a ...
   * item in current list or a new one ?

 * > I'm followed by a ...
   > current quote or a new one ?

>  *  what if it's indented
>     part of quote or list

inline nesting

Unless you know all inline rules precedence, the same kind of hardly predictable output also occur on inline elements.

- *e[m*] : emphasis
- *e[m*](url) : link take precedence over emphasis
- `e[m`](url) : code take precedence over link
- `e[m`](url) : code take precedence over link
- *`*`[*](url) : now it's your turn to guess

Solutions

The following flavors exists, but none of them tries to solves this inherent markdown complexity.

The cleanest solution would be to create a subset flavor of markdown with the following features. This subset seems to exist : https://github.com/jgm/djot

Be line-based

All text viewers and editors can do line-wrapping. So don't break your long lines. This issue alone would solve

• solve the ambiguous lazy-continuation
• remove the need for an invisible linebreak hack
• make the whole format line-based, parser-friendly

Features usage

Using READMEs from top 1000 stared github repo we get a set of 839 files with the following feature usage

feature	syntax	matched files
tilde code block	~~~	2
1-2 char settext	\n(=|-){1,2}\n	2
) numbering	^\d+\)	6
space mixed hr	^([-*])\s+\1\s+\1	10
non-spaced quote	^\s*>[^ >]	16
splitted link	[name][id] ... [id]: url	19
double backtick	``text``	20
multiline quote	^\s*> .*\n\s*>	60
chevrons link	<https://example.com>	74
link title		170
settext header	\n(=|-){3,}\n	265
list usage	^\s*\+	-:490,*:415,+:37

Don't rely on HTML as fallback

Markdown was written with web publishing in mind. But allowing HTML element as backup prevent any other field like PDF/PS authoring, native application usage...