💾 Archived View for ayushnix.com › microgemlog › 2022-04-21-markdown-necessary-evil.gmi captured on 2024-05-26 at 14:43:36. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2024-03-21)
-=-=-=-=-=-=-
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.
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
---
Created: 2022-04-21