On Thu, Jul 02, 2026 at 08:05:33AM -0400, Neal Gompa wrote: [...]
> Markdown isn't really designed for documentation. It's an ill-defined > typesetting format meant for humans to comprehend plain text emails. It began that way, yes. But many open source projects use Markdown just fine. A quick example[1]. And as Daniel said, for 95% of the use-cases Markdown is just fine. But please, let's not get our knickers in a twist about the format itself. Markdown, rST, AsciiDoc, or whatever, as long we settle on _one_ open and decent enogh format that suits our needs. > CommonMark tries to fix some of it, but it's still not great in this > regard. This is somewhat true. For deeply technical stuff, CommonMark falls short, but it is good enough for 90% of the use-cases. > That said, even across our services, we don't use pure > CommonMark. Discourse, Element, Bodhi, Forgejo, and Pagure all use > different flavors of it with different features. So even if we > "consolidate" on Markdown, it's still going to be challenging to > transpose without loss unless we extend all services to support the > same Markdown features. If I could wave a magic wand and make it happen, I'd switch to reStructuredText (rST) + Sphinx and move on. It is techically a superior choice (despite some minor annoyances with syntax, but one can live with it). Many large upstream projects use it[2], including the Linux kernel itself. [1] https://github.com/reactjs/react.dev/tree/main/src/content/reference/react [2] https://lists.fedoraproject.org/archives/list/[email protected]/message/FQS6V5LG4LYILL73OOMM26QBTAF5ELDN/ -- Kashyap Chamarthy / Red Hat / RISC-V and Fedora -- _______________________________________________ devel mailing list -- [email protected] To unsubscribe send an email to [email protected] Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/[email protected] Do not reply to spam, report it: https://forge.fedoraproject.org/infra/tickets/issues/new
