News for hackers. Stuff that matters.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by vedranm on Friday November 04, 2022 @03:31PM (#33472476)
I work in an academic setting and I can second the sentiment. For a while, we used reStructuredText for writing the teaching materials. Every so often I would have the students that would get inspired to contribute something to the teaching materials, but would subsequently get demotivated by having to learn the rST syntax and tooling.

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/

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...