Djot[1] is a light markup syntax, it's designed by John MacFarlane who is also a main contributor to Commonmark.
By explaining why Djot is good, John shows us the challenges and problems behind the widely used markdown syntax. I learn quite a lot from these discussions[2][3]. In my humble opinion, Djot is great but not perfect for the following reasons:
Let's me illustrate them one by one.
Before delving into heading and sublist syntax, we'd better understand the friendly hard-wrapping goal of Djot which leads to many syntax decisions. The goal is:
The syntax should be friendly to hard-wrapping: hard-wrapping a paragraph should not lead to different interpretations
So the following is the same for Djot, line break element, namely </br>
will not be insert at the end of the line.
Apple and orange are fruits
Apple and
orange
are fruits
In Markdown heading is a line start with #, that's all. While in Djot,
by contrast, headline still starts with #, it can span multiple lines, thus a
blank line is required to close a headline.
For example
previous paragraph
## a level two heading
occupies two lines
a paragraph
will be parsed to
<p>previous paragraph</p>
<h2>a level two heading
occupy two lines
</h2>
<p>a paragraph</p>
This is very different from Markdown Syntax and counter-intuitive for me at the first glance, although it meets fridenly hard-warping goals of Djot: hard-warpping is even possible for a heading.
According to friendly hard-warping goal, the following is still merely a paragraph, not a paragraph followed by a list, a quote block and a heading
My favorite number is probably the number
1. It's the smallest natural number that is
> 0. With pencils, though, I prefer a
# 2.
This implies block-level elements can't interrupt paragraphs. It's just Djot's decision and seems reasonable at the first place, but when combined with the uniformity principle, things gets really confused.
In order to get a sublist, instead of
- Fruits
- apple
- orange
you must write
- Fruits
- apple
- orange
Djot specifies that a sublist must always be preceded by a blank line
Why is that? Because all block level elements are treated as a container and they can contain each other as child.
When it comes to the previous nested list example, child list item is a paragraph
Fruits
- apple
- orange
It's obvious that it doesn't include any list, just a multiple lines paragraph. That's uniformity principle all about: the contents of a list item should have the same meaning they would have outside of the list item.
In the other words, if this does not contain a list in an ordinary paragraph
Fruits
- apple
- orange
It's also does not contain a list in a list item.
Once again, the good friendly hard-wrapping goal and uniformity goal lead to conter-intitive syntax.
Both Heading and sublist syntax make me confused, but the reasons are different.
My confusion about the heading syntax mostly comes from the fact that i'm so used to Markdown heading syntax. It's basically the same thing when I learned a blank line is required before a code block for the first time in Markdown. We are dependent on our experiences. On the other hand, a blank line make things clear for writers and readers, I'd love to accept that.
However it's not the case for the sublist syntax. It's just weird and not
natural even after I'm familiar with it. I think the root cause is the
special characters(*, >, # etc.) at the begining of a line.
Djot's decision have resulted in troubles, so we can try another choice: leave the special characters as it should be, escape the characters explicitly when you want.
Under this assumption, the previous paragraph should be written as:
My favorite number is probably the number
\1. It's the smallest natural number that is
\> 0. With pencils, though, I prefer a
\# 2.
You may find the escape character \ is very annoying, but remember the chance
you need it is extremely low, so i think it's ok for most people.
[1] Djot website [2] Beyond Markdown [3] Djot's design goals and explanation of design decisions [4] Djot syntax reference
Written by Songziyu @China Aug. 2023