reStructuredText vs Markdown: Referencia rápida
Referencia sintáctica comparativa para ambos lenguajes de marcado.
Nota
Los elementos marcados como [igual] usan una sintaxis idéntica o casi idéntica en ambos lenguajes. Los elementos marcados como [diferente] tienen una sintaxis significativamente distinta. Las notas sobre Markdown se aplican principalmente a CommonMark / GitHub Flavored Markdown (GFM) salvo que se indique lo contrario.
Formato en línea
Cursiva [igual]
| reStructuredText | Markdown |
|---|---|
| *italic* | *italic* or _italic_ |
Negrita [igual]
| reStructuredText | Markdown |
|---|---|
| **bold** | **bold** or __bold__ |
Negrita cursiva
| reStructuredText | Markdown |
|---|---|
| No soportado nativamente | ***bold italic*** |
Código en línea [similar]
| reStructuredText | Markdown |
|---|---|
| ``code`` | `` code `` |
| Comillas invertidas dobles | Comilla invertida simple |
Tachado
| reStructuredText | Markdown |
|---|---|
| No nativo; usar un rol | ~~text~~ |
| o HTML sin procesar | (GFM / extendido) |
Encabezados
H1
| reStructuredText | Markdown |
|---|---|
Title
|
# Title |
=====
|
|
Subrayado con = (la longitud debe coincidir)
|
H2
| reStructuredText | Markdown |
|---|---|
Section
|
## Section |
-------
|
|
Subrayado con - (o cualquier signo
|
|
de puntuación, usado de forma consistente)
|
H3
| reStructuredText | Markdown |
|---|---|
Subsection
|
### Subsection |
~~~~~~~~~~
|
|
Tilde o cualquier carácter de puntuación nuevo
|
Variante con sobrelineado
| reStructuredText | Markdown |
|---|---|
==========
|
No soportado |
Title
|
|
==========
|
|
Sobrelineado + subrayado para el nivel superior
|
Listas
Lista desordenada [similar]
| reStructuredText | Markdown |
|---|---|
| - item | - item |
| - item | - item |
| - item | - item |
| También * o + | También * o + |
Lista ordenada [similar]
| reStructuredText | Markdown |
|---|---|
| 1. first | 1. first |
| 2. second | 2. second |
| 3. third | 3. third |
| También #. para | |
| numeración automática |
Lista anidada
reStructuredText:
- item - nested - item Se requiere línea en blanco + sangría de 2 espacios.
Markdown:
- item - nested - item Sangrar con 2 a 4 espacios.
Lista de definiciones
| reStructuredText | Markdown |
|---|---|
term
|
No estándar; usar HTML |
`` Definition text here.``
|
o una extensión |
La definición sangrada sigue al término
|
] Enlaces e imágenes ==================
Enlace en línea [diferente]
| reStructuredText | Markdown |
|---|---|
| `` Link text `` | [Link text](URL) |
| Comilla invertida, texto, URL entre | |
| corchetes angulares, guion bajo final |
Enlace por referencia
reStructuredText:
`Link text`_ .. _Link text: URL
Markdown:
[Link text][id] [id]: URL
URL desnuda
| reStructuredText | Markdown |
|---|---|
| https://example.com | <https://example.com> |
| Enlace automático | Los corchetes angulares fuerzan el enlace |
Imagen
reStructuredText:
.. image:: path/img.png :alt: Alt text :width: 400px
Markdown:
Ancla interna
reStructuredText:
.. _my-label: :ref:`my-label`
Markdown:
[text](#heading-id) Solo slugs de encabezados (GFM).
Bloques de código
Bloque de código básico
reStructuredText:
:: code here ``::`` al final del párrafo, sangría de 3+ espacios.
Markdown:
``` code here ``` Delimitado con triples comillas invertidas.
Bloque de código con lenguaje
reStructuredText:
.. code-block:: python import sys
Markdown:
```python import sys ```
Incluir archivo externo
reStructuredText:
.. literalinclude:: file.py :language: python
Markdown: No soportado nativamente.
Elementos de bloque
Cita en bloque
| reStructuredText | Markdown |
|---|---|
| Sangrar con espacios :: | > Quoted text here. > Continues here. |
| El texto sangrado se convierte | |
| en una cita en bloque. |
Línea horizontal
| reStructuredText | Markdown |
|---|---|
| ---- | --- or *** |
| Cuatro o más guiones | Tres o más -/*/_ en su propia línea |
Salto de línea
reStructuredText:
| line one | line two Bloques de línea usando el prefijo ``|``.
Markdown:
line one line two Dos espacios al final de la línea antes del salto.
Nota / Advertencia
reStructuredText:
.. note:: Content of the note. También: ``warning::``, ``tip::``, ``caution::``
Markdown: Sin sintaxis estándar; usar HTML sin procesar o una extensión específica de la herramienta.
Tablas
Tabla simple
reStructuredText:
=== === A B === === 1 2 === === Delimitadores ``===``.
Markdown (tabla GFM con tuberías):
| A | B | |---|---| | 1 | 2 |
Tabla en cuadrícula (completa)
reStructuredText:
+---+---+ | A | B | +===+===+ | 1 | 2 | +---+---+ Soporta fusión de celdas y celdas de varias líneas.
Markdown: No soportado.
Alineación de columnas
reStructuredText:
.. list-table:: :widths: 25 75 :header-rows: 1
Markdown:
| L | C | R | |:---|:---:|---:| La posición de los dos puntos en la fila separadora controla la alineación.
Avanzado / Especial
Comentario
| reStructuredText | Markdown |
|---|---|
| .. This is a comment | Sin sintaxis de comentario estándar |
| .. sin nombre de directiva |
Nota al pie
reStructuredText:
text [1]_ .. [1] Footnote text.
Markdown (GFM / Pandoc):
text [^1] [^1]: Footnote text.
Tabla de contenido
reStructuredText:
.. contents:: TOC Title :depth: 2
Markdown: Depende de la herramienta (Pandoc, MkDocs, etc.).
HTML sin procesar
reStructuredText:
.. raw:: html <div>...</div>
Markdown:
<div>HTML inline</div> La mayoría de los motores de renderizado permiten HTML sin procesar directamente.
Matemáticas
reStructuredText:
.. math:: E = mc^2
Markdown (extendido / KaTeX / Pandoc):
$$E = mc^2$$
Directiva (genérica)
reStructuredText:
.. directive-name:: arg :option: value Content block.
Markdown: Sin equivalente; usar extensiones o shortcodes específicos de la herramienta.
Resumen de diferencias clave
Donde RST es más potente
- Encabezados: caracteres de puntuación flexibles en lugar de niveles #.
- Tablas: tablas en cuadrícula completas con fusión de celdas y celdas de varias líneas.
- Advertencias: .. note::, .. warning::, .. tip:: etc. incorporados.
- Directivas: mecanismo de extensión general para cualquier elemento a nivel de bloque.
- Sustituciones / macros: fragmentos de texto reutilizables.
- Estandarización: RST a través de Docutils/Sphinx es mucho más uniforme que Markdown.
Donde Markdown es más simple o tiene mayor soporte
- Bloques de código delimitados: las triples comillas invertidas son más legibles que :: + sangría.
- HTML sin procesar: permitido en línea sin directiva en la mayoría de los motores de renderizado.
- Tachado y notas al pie: ampliamente disponibles en GFM.
- Popularidad: GitHub, Stack Overflow, Reddit y la mayoría de los wikis usan Markdown por defecto.
La advertencia sobre la fragmentación de Markdown
No existe un estándar único de Markdown. CommonMark es lo más cercano a una especificación, pero GitHub Flavored Markdown (GFM), Pandoc, MkDocs y Obsidian añaden cada uno sus propias extensiones. RST a través de Docutils/Sphinx es sustancialmente más uniforme entre las distintas herramientas.