Things Markdown got wrong
reStructuredText on these, for anyone that’s curious or thinking about it:<p>1. If you use “5.”, it’ll give you a five. If you want auto-numbering, use “#.” as your prefix. (While I’m thinking of it: I hate that using actual Unicode bullets like “•” doesn’t work in Markdown, and that in <a href="https:&#x2F;&#x2F;talk.commonmark.org&#x2F;t&#x2F;unicode-character-bullet-u-2022&#x2F;397" rel="nofollow">https:&#x2F;&#x2F;talk.commonmark.org&#x2F;t&#x2F;unicode-character-bullet-u-202...</a> it’s been actively rejected for CommonMark.)<p>2. Code blocks are by indentation only, no fencing, but avoids confusion about indentation levels by defining all of that stuff <i>properly</i> and having it match visual usage, rather than Markdown’s crazy “four spaces, but in certain situations we’ll let you get by with 3, 2, 1 or even 0—but if you then seek to nest, remember to bump it up to eight rather than just N+4”. Code blocks are indicated by `::` at the end of or as the entire previous paragraph, which is esoteric, but also fits in very well with its directive syntax, which is how you can attach extra metadata to code blocks. It’s definitely not as simple as the newer Markdown fencing approach, though it fits into the rest of reStructuredText in a sane and principled way so that it’s not at all hard. Still, I think that a new version of reStructuredText would quite possibly include fencing in some form—or maybe directives would be resyntaxed to be able to be fenced rather than indented, though achieving that while still allowing nesting would take care.<p>3. Markdown in HTML in Markdown? That Markdown extends HTML is the real problem here, and is both its greatest strength and help in adoption, and its <i>catastrophic</i> weakness. reStructuredText is a language of its own that doesn’t extend anything, so that style of HTML output is typically done by defining new directives, which can then contain reStructuredText. It’s strictly less powerful, but it composes <i>way</i> better. As a workaround, the `raw` directive lets you put in arbitrary HTML (or LaTeX, &amp;c.).<p>4. By deliberately not being HTML, reStructuredText handles this sort of thing much better. Each node in the document can have classes (which will end up as class=&quot;…&quot; in HTML, something else in LaTeX, &amp;c.). You can do things like `.. class:: …` to apply a class to the next block (heading, paragraph, list, &amp;c.). Most directives support a :class: option. You can define new roles so that :classname:`…` will do what you desire. And none of this is then tied to HTML.<p>5. reStructuredText lets you define anchors at any place in the document (which can also be used for index entries when writing books or things like that). `.. _anchor-name:` above the heading will do it thus. This protects you against the anchor changing (and thus breaking links) if you change the text of the heading. Any form of automatic heading ID generation is left to the software to decide, e.g. Sphinx generates IDs by default.<p>6. Field lists. A field list at the start of the document is treated as document bibliographic data, and you can put anything in there you like.<p>I myself prefer reStructuredText in almost all regards, but I scarcely use it any more other than for a couple of types of personal documents, because of the ubiquity of Markdown. It was similar with Mercurial and Git.