Consider using MyST

[probonopd]

Currently we are using reStructuredText for docs.appimage.org but some users (including myself) strongly prefer Markdown.

reStructuredText offers more powerful features but also has an entirely unfamiliar (at least to me) syntax, resulting in me avoiding to touch the documentation altogether.

MyST could be the solution:

The MyST-parser is a Sphinx parser for the MyST markdown language. When you use it, Sphinx will know how to parse content files that contain MyST markdown (by default, Sphinx will assume any files ending in .md are written in MyST markdown).

It allows one to use directives in Markdown.

It is even possible to use both MyST and reStructuredText.

https://myst-parser.readthedocs.io/en/latest/using/intro.html#intro-writing

[probonopd]

While we are at it, we might also want to check out Jupyter Book which can be used to generate books/documentation websites that embed executable code: https://www.heise.de/news/Projekt-Ausfuehrbares-Buch-Jupyter-Book-erstellt-Tech-Buecher-mit-Markdown-4870752.html

[TheAssassin]

So your response to "I would have to learn something new" is to suggest "everyone else but me has to learn something entirely new"? This MyST stuff is a lot more cumbersome than reST, syntax wise, as it hacks additional markup into existing Markdown structures, making it a lot harder to understand and read. reST provides proper extension points by default (like blocks etc.), and is designed to be augmented with additional features.

Just look at refs. That's not easier than reST's refs, it's actually more complicated than reST:

# reST
:ref:`My displayed text <my-ref>`

# MyST
{ref}`My displayed text <my-ref>`

Their blocks are hacked into Markdown's code syntax:

# reST
.. contents::
   :local:
   :depth: 1

...

# MyST

```{contents} Contents
:local:
:depth: 1

...

I can understand that reST might look awkward at first glance, but it's easy to understand, provides a very consistent approach syntax wise (most elements are noted similarly, with different names only), is not just months but decades old, well tested and used in the best tech docs in the world. Many people know the syntax, it's not as unpopular as most people think.

MyST indeed looks, however, like someone tries to merge reST and Markdown. However, I'm clearly not a fan of the result. It's not like it makes anything easier to add additional parsers; we've had tried that, and the result was a mix of languages, with the reST part being written using the features it provides and providing a better overall result, the rest being mostly ported from the wiki, which had no consistent style, lacked proper cross references and structure (hierarchy), and overwhelming the user with information they didn't need immediately.

Have you ever tried to write reST? It's not hard at all. There's editors like ReText (request for AppImage here) which make writing Sphinx docs very easy.

P.S.: It's not a matter of preference. I also write LaTeX not because it's necessarily easy but because the result is significantly better than what any "simple alternative" could provide (well, there's nothing really comparable). I don't claim reST was the best markup language, but it's easy to learn and use IMO.

[probonopd]

Have you ever tried to write reST?

Yes. For me it is cryptic, counter-intuitive and not fun. Unlike Markdown which I find straightforward, easy, and fun.

It's not a matter of preference.

Let's say it's "compatibility to how my brain works". ;-) Plus brain muscles that have been trained to do Markdown.