Why Djot Is Not Perfect

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.

1 Friendly Hard-wrapping Goal

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 
are fruits

2 Heading Syntax

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

<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.

3 Sublist Syntax

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

 - 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

 - 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.

4 My Thoughts

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.

5 Reference

[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