Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by wbamberg on Friday November 04, 2022 @07:12PM
(#33475376)
Thanks @vedranm! I especially like your side-by-side comparison of the process of contributing using Markdown versus reST. It really encapsulates the difference that reasonably seamless tool support makes. I need to look more into MkDocs...
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-...
by vedranm on Sunday November 06, 2022 @07:56AM
(#33492069)
You are welcome. I have no connection to its development aside from some minor translation updates and bug reports, but I can only recommend it.
What I like is how easy it is to host MkDocs on GitHub Pages via built-in support, but you can even make it behave like Jekyll with GitHub Actions. Shameless self-plug of another blog post: https://gaseri.org/en/blog/2022-11-01-publishing-material-fo...
After a few years, I gave up and switched from rST and Sphinx to Markdown and MkDocs [2]. We addressed the limitations of Markdown with PyMdown Extensions [3]. Still haven't looked back; for our specific use case of writing (computer science) teaching materials, Markdown is a better choice than rST.
[1] https://gaseri.org/en/blog/2017-07-29-why-we-use-restructure...
[2] https://gaseri.org/en/blog/2021-08-16-markdown-vs-restructur...
[3] https://facelessuser.github.io/pymdown-extensions/