blog.bernatchez.net

Italic [same]

Bold [same]

Bold Italic

Inline Code [similar]

Strikethrough

H1

H2

H3

Overline Variant

Unordered List [similar]

Ordered List [similar]

Nested List

reStructuredText:

- item

  - nested

- item

Blank line + 2-space indent required.

Markdown:

- item
  - nested
- item

Indent with 2–4 spaces.

Definition List

Inline Link [different]

Reference Link

reStructuredText:

`Link text`_

.. _Link text: URL

Markdown:

[Link text][id]

[id]: URL

Bare URL

Image

reStructuredText:

.. image:: path/img.png
   :alt: Alt text
   :width: 400px

Markdown:

![Alt text](path/img.png)

Internal Anchor

reStructuredText:

.. _my-label:

:ref:`my-label`

Markdown:

[text](#heading-id)

Heading slugs only (GFM).

Basic Code Block

reStructuredText:

::

   code here

``::`` at end of paragraph, indent 3+ spaces.

Markdown:

```
code here
```

Fenced with triple backticks.

Code Block with Language

reStructuredText:

.. code-block:: python

   import sys

Markdown:

```python
import sys
```

Include External File

reStructuredText:

.. literalinclude:: file.py
   :language: python

Markdown: Not supported natively.

Blockquote

Horizontal Rule

Line Break

reStructuredText:

| line one
| line two

Line blocks using ``|`` prefix.

Markdown:

line one
line two

Two trailing spaces before the newline.

Note / Admonition

reStructuredText:

.. note::

   Content of the note.

Also: ``warning::``, ``tip::``, ``caution::``

Markdown: No standard syntax; use raw HTML or a tooling-specific extension.

Simple Table

reStructuredText:

===  ===
A    B
===  ===
1    2
===  ===

``===`` delimiters.

Markdown (GFM pipe table):

| A | B |
|---|---|
| 1 | 2 |

Grid Table (full)

reStructuredText:

+---+---+
| A | B |
+===+===+
| 1 | 2 |
+---+---+

Supports cell spans and multi-line cells.

Markdown: Not supported.

Column Alignment

reStructuredText:

.. list-table::
   :widths: 25 75
   :header-rows: 1

Markdown:

| L  |  C  |  R |
|:---|:---:|---:|

Colon placement in the separator row controls alignment.

Comment

Footnote

reStructuredText:

text [1]_

.. [1] Footnote text.

Markdown (GFM / Pandoc):

text [^1]

[^1]: Footnote text.

Table of Contents

reStructuredText:

.. contents:: TOC Title
   :depth: 2

Markdown: Tooling-dependent (Pandoc, MkDocs, etc.).

Substitution / Macro

reStructuredText:

|release|

.. |release| replace:: 5.0

Markdown: Not supported.

Raw HTML

reStructuredText:

.. raw:: html

   <div>...</div>

Markdown:

<div>HTML inline</div>

Most renderers allow raw HTML directly.

Math

reStructuredText:

.. math::

   E = mc^2

Markdown (extended / KaTeX / Pandoc):

$$E = mc^2$$

Directive (Generic)

reStructuredText:

.. directive-name:: arg
   :option: value

   Content block.

Markdown: No equivalent; use extensions or tooling-specific shortcodes.

Where RST is more powerful

• Headings: flexible punctuation characters rather than # levels.
• Tables: full grid tables with cell spans and multi-line cells.
• Admonitions: .. note::, .. warning::, .. tip:: etc. built in.
• Directives: a general extension mechanism for any block-level construct.
• Substitutions / macros: reusable text snippets.
• Standardisation: RST via Docutils/Sphinx is much more uniform than Markdown.

Where Markdown is simpler or has wider support

• Fenced code blocks: triple backticks are more readable than :: + indentation.
• Raw HTML: allowed inline without a directive in most renderers.
• Strikethrough and footnotes: widely available in GFM.
• Popularity: GitHub, Stack Overflow, Reddit, and most wikis default to Markdown.

The Markdown fragmentation caveat

There is no single Markdown standard. CommonMark is the closest thing to a specification, but GitHub Flavored Markdown (GFM), Pandoc, MkDocs, and Obsidian each add their own extensions. RST via Docutils/Sphinx is substantially more uniform across toolchains.