Markdown Is A Necessary Evil

Markdown, no matter what the specification is, is a deceptively simple markup language to understand and write documentation with. I've written my entire personal wiki using markdown because that's what mkdocs uses. However, it's apparently a shitty markup language for anyone who wants to parse it or develop a parser for it. A blog post by Eric Holscher and a blog post on undeadly provide more details on why markdown is a shitty language for a developer. Here's another forum discussion about possible ideas to reduce ambiguities in CommonMark. Perhaps this is why the treesitter parser for markdown slows down neovim to a crawl to the point where writing documentation is no longer fun. Oh, and this parser was merged after another markdown parser kept crashing neovim.

mkdocs static site generator

don't use markdown for technical docs

a blog post by Peter Hansteen about Markdown being abominable

Beyond Markdown by John McFarlene

a tree-sitter parser for CommonMark

a tree-sitter parser crashing neovim

Alternatives? Unfortunately, I don't think there are any decent alternatives. A blog post by Karl Voit convinced me about Org Mode being a reasonable markup language but, as expected, there's no ecosystem for Org Mode outside Emacs. Maybe I can write articles in Org Mode but convert them into markdown before using them? Maybe neorg or orgmode.nvim can work?

a blog post by Karl Voit about using orgmode as a markup language

neorg

orgmode.nvim

---

Created: 2022-04-21

MicroGemlog

Home