4 ms·

The really nice thing about ReST is that it has provided generic syntax for extensions, one for inline text: :foo:`hello world` and for blocks: .. extension::

by egh 13y ago

The really nice thing about ReST is that it has provided generic syntax for extensions, one for inline text: :foo:`hello world` and for blocks: .. extension:: hello world In markdown, on the other hand, you have multiple, incompatible versions which have entirely different syntax because there is no generic extension mechanism. ReST feels more well thought-out, generally. That said, I've pretty much given up advocating it, because markdown seems to have won and has so much more tool support.

BruceM 13y ago
I like ReST as well. With Sphinx, it is great for producing documentation. A project that I work with has converted hundreds of pages of books of technical documentation over to Sphinx and a custom Sphinx extension.
- fprintf 13y ago
  I like ReST as well. It's more powerful and looks much cleaner // e.g. how do you write footnotes in markdown? And how do you do this in markdown? +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
  - biscarch 13y ago
    in pandoc-markdown a footnote[^1] would be written like this. [^1]: My footnote here Here's a link to pandoc's markdown flavor, which includes tables: http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markd...
  - mercurial 13y ago
    Since basic Markdown is so basic, multiple incompatible flavours of Markdown have cropped up, including Pandoc-Markdown, which can do footnotes.
masklinn 13y ago
> ReST feels more well thought-out, generally. It's certainly set up for extensibility, although some areas are a pain (e.g. blank lines may be ignored entirely, change vertical spacing or change semantics, that can be annoying). The toolchain is also fairly complex and very badly documented (Sphinx itself is better documented than docutils, but either way you end up wading through piles of code to understand what happens, why, and what's available in the applicative context of your extension)

by egh 13y ago

BruceM 13y ago

I like ReST as well. With Sphinx, it is great for producing documentation. A project that I work with has converted hundreds of pages of books of technical documentation over to Sphinx and a custom Sphinx extension.

fprintf 13y ago
I like ReST as well. It's more powerful and looks much cleaner // e.g. how do you write footnotes in markdown? And how do you do this in markdown? +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
- biscarch 13y ago
  in pandoc-markdown a footnote[^1] would be written like this. [^1]: My footnote here Here's a link to pandoc's markdown flavor, which includes tables: http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markd...
- mercurial 13y ago
  Since basic Markdown is so basic, multiple incompatible flavours of Markdown have cropped up, including Pandoc-Markdown, which can do footnotes.

masklinn 13y ago

> ReST feels more well thought-out, generally. It's certainly set up for extensibility, although some areas are a pain (e.g. blank lines may be ignored entirely, change vertical spacing or change semantics, that can be annoying). The toolchain is also fairly complex and very badly documented (Sphinx itself is better documented than docutils, but either way you end up wading through piles of code to understand what happens, why, and what's available in the applicative context of your extension)