For people considering adding Markdown support to web browsers or other publishing tools, please consider adopting Djot instead: https://github.com/jgm/djot
It's very similar to the Markdown syntax we all know and love/hate, but fixes many inconsistencies in the spec, and also makes it possible to parse a document in linear time, with no backtracking. It is also much fuller-featured than commonmark, with support for definition lists, footnotes, tables, several new kinds of inline formatting (insert, delete, highlight, superscript, subscript), math, smart punctuation, attributes that can be applied to any element, and generic containers for block-level, inline-level, and raw content.
Looks like it simply makes Markdown easier for both computers and humans! I love this and can’t believe I haven’t seen it before.
> Requiring quirky behavior and blank lines that hurt reading
Really? The linked spec says, referring to a blank link in indented lists:
> reStructuredText makes the same design decision.
And as a design goal:
> your document [must be] readable just as it is, without conversion to HTML and without special editor modes that soft-wrap long lines. Remember that source readability was one of the prime goals of Markdown and Commonmark…
Or this, which made me celebrate:
> anything that is indented beyond the start of the list marker belongs in the list item.
In Markdown it’s really hard (aka impossible) to get sections to respect the indentation level they belong to. What a simple rule here: inside a list, items belong to their list item. Beautiful!
Other great quotes:
> we don't need two different styles of headings or code blocks.
> avoid using doubled characters for strong emphasis. Instead… use _ for emphasis and * for strong emphasis
> code span parsing does not backtrack. So if you open a code span and don't close it, it extends to the end of the paragraph
Sanity. Sanity introduced to an ambiguous spec. It’s wonderful.
This bit made me a little unsure:
> although we want to provide the flexibility to include raw content in any output format, there is no reason to privilege HTML. For similar reasons we do not interpret HTML entities, as commonmark does
While Markdown was meant to transform to HTML, I wish it was a spec renderable without a HTML or web browser layer. So I like this. Equally though one use case I personally have is Markdown to static HTML and it’s useful having HTML tags present and handled. So my understanding of this part of the spec is confused (what does “interpret” mean?) but if it means no support for inline HTML that is indeed a pity.
> reStructuredText makes the same design decision.
"This other product that doesn't understand the appeal of Markdown and also thought this was a technical problem rather than a user barrier to entry problem made the same mistake" is not exactly a strong defense.
> Sanity. Sanity introduced to an ambiguous spec. It’s wonderful.
Users don't care how hard or easy something is to parse. You write a parser once; you write Markdown millions of times.
> Looks like it simply makes Markdown easier for both computers and humans! I love this and can’t believe I haven’t seen it before.
Unfortunately it does not. This is less readable and more annoying to write:
>Markdown:
>- Fruits
> - apple
> - orange
>
>djot:
>- Fruits
>
> - apple
> - orange
These are fundamentally different products. If you want something easy to parse and human readable, use YAML. If you want something easy to write, use Markdown.
I don’t mind pressing Enter twice instead of once.
I know that’s a glib answer. And I agree an extra line break should, to a human which reads indents, be unnecessary. But given the ambiguities of Markdown, something that is both human-readable and computer-readable is a huge advantage.
Also,
> Users don't care how hard or easy something is to parse
I don’t read it as about parsing. I read it as about writing. You can write one way and know exactly how it will be interpreted.
> So my understanding of this part of the spec is confused (what does “interpret” mean?) but if it means no support for inline HTML that is indeed a pity.
All its saying is that that djot doesn't have special rules for HTML so it spits out the same thing it receives, apparently with escaping relevant to the selected output mode. Note right above the part you quoted it shows an example of using HTML ("we simply do not allow raw HTML, except in explicitly marked contexts").
It's very similar to the Markdown syntax we all know and love/hate, but fixes many inconsistencies in the spec, and also makes it possible to parse a document in linear time, with no backtracking. It is also much fuller-featured than commonmark, with support for definition lists, footnotes, tables, several new kinds of inline formatting (insert, delete, highlight, superscript, subscript), math, smart punctuation, attributes that can be applied to any element, and generic containers for block-level, inline-level, and raw content.
Some examples, showing how Djot would be rendered into HTML: https://htmlpreview.github.io/?https://github.com/jgm/djot/b...