Comment by gravypod
3 years ago
(Opinions are my own)
I like the ideas behind this but I do not think this will take off as much as CommonMark has. My main reasons for thinking this:
1. Users don't really care about edge cases. CommonMark (cmark-gfm really) is "good enough". If something looks odd people go "oh, strange" and make a 3 second edit and forget about it.
2. There's already multiple parsers for every language for markdown. Here there is a single Lua implementation.
3. GitHub is the king.
If it cannot render in GitHub it's not real. If it's harder for me to write in the 99% case then it's not worth it. If it's harder for me to implement within my application then I'm too lazy to switch.
Nice things in here:
1. Less ambiguous parsing. For the parser infrastructure I support at $JOB this makes supporting questions from users a HUGE pain in the ass.
2. AST-first design. Seems like everything appears in the AST (even references!) which is a huge win over cmark-gfm. There's also source positions included which is a MASSIVE win for tooling.
3. Custom Attributes implementation. This is really nice for extensibility. It is less readable but having it as an option is nice.
I can’t imagine the intended audience being so wide as to include a goal of “replacing Markdown as the default on GitHub.”
Instead, this project appeals to me as someone who’s already “bought in” to the pandoc ecosystem. Pandoc makes it really easy to write filters[1] and to take the same source file to generate web pages[2], Reveal.js presentations, Beamer presentations, and long-form PDFs[3]. As someone who writes most things in Markdown compiled via pandoc, I see the cracks in the edges all too often, but I’m too stubborn to give up markdown or any of the tools I’ve built up around pandoc and pandoc markdown. I could absolutely see there come a day where I find some last straw where I can’t get done with pandoc Markdown what I need to get done, and djot seems like it would at least be a contender. I’m sure there are many pundits here would chime in and say “just use Asciidoc,” but every time I look at a syntax quick reference, I get about halfway down the page before thinking “nah, this looks too foreign, I don’t want something that diverges this far from Markdown.”
Djot deviates in annoying ways from Markdown, but not as many and so it’d be an easier pill to swallow for the narrow audience of people like me who want something mostly similar to Markdown that works well with pandoc and avoids the most common syntactic oddities of Markdown.
[1] https://github.com/jez/pandoc-sidenote
[2] https://github.com/jez/pandoc-markdown-css-theme
[3] https://github.com/jez/pandoc-starter
> Djot deviates in annoying ways from Markdown
I'm curious which of the deviations you find annoying. Djot seems to be pretty sensible to me.
“Sublists must have surrounding blank lines” and “HTML has to be wrapped” is enough to be annoying IMO. Again, not insurmountable but just the sort of thing that I’d find weird looking every time I authored a djot doc.
Especially the blank lines around lists restriction. The syntax goes to explain how “tight” lists do not have their elements wrapped in paragraphs, while “loose” lists do. This admits that lists in the rendered output will want to use whitespace to achieve a particular layout. But for the case of a Markdown list like this, which will be rendered with no whitespace between items:
In djot this must become:
which has way more whitespace in source form than the rendered output will have. This makes it harder to judge the visual weight of a piece of text by simply glancing at the source, and would require spending more time looking at the rendered output while drafting.
And to go further, a loose list would require even more whitespace:
If there were a way to relax this constraint about new lines for list sub elements, I might even consider switching to this for some documents today, but absent that it’ll have to be once I bang into a few more markdown ambiguity problems.
2) The design is still incomplete. Eventually more parsers could be made. Bonus, they will evidently be simple to write
3) Github has renderers for multiple formats if this language ever took off, not unreasonable for them to add one to the pile.
Yes, you can write READMEs in ReST or Org, but you cannot write issues, pull request descriptions, comments, or discussion posts in anything other than GFM.
On the other hand, they already migrated GFM once (to CommonMark), so it's not wildly unimaginable they might do it again. There is precedent. (Of course, it would have to take off first. Adoption is problem #1.)
I am someone who has decided to go all-in on djot for my software.
Personally, I care about the edge cases. I also don't care about multiple parsers because I want to write my own. (I currently depend on Sphinx, Breathe, and MyST, which are heavy dependencies.) And I don't store my code on GitHub because of Copilot and because of [1].
I decided to go all-in on djot for several reasons:
* I can write my own parser.
* djot can target any format, which means I can use the same docs to generate manpages, a docs website like [2], and perhaps PDF's if my docs include something like the Rust Book.
* djot's extension story [3] is the best of any format, and I need extensions that don't exist in any format for things like EBNF in a specification.
That said, I think you are correct that this will not take off as much as CommonMark has. I guess I was just sharing that I don't care and why.
[1]: https://gavinhoward.com/2020/04/i-am-moving-away-from-github...
[2]: https://docs.yzena.com/
[3]: https://github.com/jgm/djot/discussions/77
> There's already multiple parsers for every language for markdown. Here there is a single Lua implementation.
Markdown started with a single implementation AFAIK. Or was there a galaxy-wide coordinated software release for Markdown parsers and I missed it?
> GitHub is the king. f it cannot render in GitHub it's not real.
This can't be more farther than truth for me. I don't care if it's rendering in GitHub or not. If I can use it in my docs, write it fast, put on a webpage in a nice manner, I'm done.
Markdown is not popular because it's embraced by GitHub. It's the exact opposite. If it can capture some mind share, tools and websites rendering this will proliferate.
> 3. GitHub is the king.
While I also like GitHub, I make very little use of its web interface. I mostly use gh to interact with the service. But I use markdown to generate document fragments on a daily basis. Claiming a technology is going to fail because the one big player in town has not adopted it yet is... not very open, to say the least.
Plenty of use cases for markup languages that never touch Github, luckily.
> If it cannot render in GitHub it's not real. If it's harder for me to write in the 99% case then it's not worth it. If it's harder for me to implement within my application then I'm too lazy to switch.
There's also on-prem Bitbucket, which supports an even more limited form of Markdown. One could always use CI to render the documentation into Confluence (because it's a safe bet someone who uses Bitbucket uses Confluence as well) using Pandoc, but it's still a downgrade in usability: you can't just review the changes to the documentation done in branch A in rendered form.
But yes, GitHub is king. I don't like mermaid.js, but when I do, I do my diagrams in mermaid.js because GH renders them.
I'm a fan of Asciidoc, and I think djot is a nice "next" markdown, but:
> If it cannot render in GitHub it's not real.
This is 100% accurate. If I limit myself to CommonMark, with maybe a few extras tossed in gently, I can be pretty sure that my meaning will be correctly rendered.
Anything else, no matter how nice the syntax is, or how powerful the expressions are, won't render for the people I want it to renfer for.
>"CommonMark (cmark-gfm really) is "good enough"."
I would agree if it had tables
It has tables
> (cmark-gfm really)