pandoc-sidenote VS djot

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

I know this doesn't solve your problem directly, but I recommend people to try out Djot[0], a markup language from the author of CommonMark.

Djot has a single well-defined spec, and most of the basic formatting has the same syntax as (a) Markdown, so switching is pretty painless. It has as a main goal to be legible and visually aesthetic as-is, just like Markdown.

What Djot adds is its _predictability_. Nested formatting, precedence order, line breaks behavior, nested blocks, mixed inline and block formatting, custom attributes are all laid out precisely in the spec in a thought-out manner. Till this day I still can't remember how to put line break within a list item in Markdown (and I'm sure there're more than one way).

[0]: https://djot.net/

Worth noting that the author has also created a markup language, djot.

https://github.com/jgm/djot

Every time I see people doing something with Markdown, I wish they just replace it with support for Djot[0] instead. It is a Markdown alternative by the creator of Pandoc and CommonMark that fixes all of the most egregious mistakes, while being legible and visually pleasant as-is. It is also syntactically similar to Markdown, which should ease adoption.

[0] https://github.com/jgm/djot

Are you using markdown? It might make sense to look at 'djot' as well: https://djot.net/; it's a new 'light' markup language conceived as a successor to commonmark; development is led by none other than John McFarlane (author of pandoc, & also led commonmark standardization) Djot makes it really easy to attach arbitrary attributes to block elements as well as inline elements; and the parser records source positions in the output -- all of which makes it really convenient keeping track of elements changing position or value.

I have a simple script that sends a djot buffer (https://github.com/jgm/djot) to the parser, if there's a change, on the CursorHold event.

Since you mentioned you were considering moving to CommonMark, have you had time to look into Djot (also by jpm)? Djot is meant to be easier to parse, and I'm planning to write a tree-sitter grammar for it.

Another recent development here is https://djot.net/ (by the pandoc author). It indeed thoroughly solves both: