Primeros pasos
Encabezados y párrafos
Usa # para los encabezados (1-6 niveles). La sintaxis alternativa usa === para H1 y --- para H2. Los párrafos necesitan una línea en blanco entre ellos. Markdown está diseñado para ser legible como texto plano.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
Alternative Heading 1
=====================
Alternative Heading 2
---------------------
This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.Saltos de línea
Dos espacios finales o una barra invertida al final de una línea crean un salto de línea duro (<br>). Sin ellos, un salto de línea simple es un ajuste suave que se une en un párrafo. Deja siempre una línea en blanco para separar párrafos.
First line
Second line (two trailing spaces above)
Or use a backslash at end of line\
to force a line break.
Soft wrap without break:
just continue on the next line
and it joins into one.Comentarios
Markdown no tiene sintaxis oficial de comentarios, pero los comentarios HTML (<!-- -->) funcionan en la mayoría de renderizadores y se ocultan en la salida. El truco [//]: # usa una referencia de enlace vacía para añadir notas. Los comentarios siguen visibles en el código fuente crudo.
<!-- HTML comments work in most Markdown -->
[//]: # (This is a comment)
[//]: # "Another comment style"
<!--
Multi-line comment
not rendered in output
-->Espacios en blanco y sangría
Cuatro espacios iniciales convierten el texto en un bloque de código — cuidado con la sangría accidental. La sangría importa para las listas anidadas (2-4 espacios por nivel). Las tabulaciones suelen tratarse como 4 espacios. Usa espacios de forma consistente para evitar problemas de renderizado entre parsers.
Paragraph one.
This is an indented code block
because of 4 spaces.
> Quoted text needs > prefix.
Three spaces is just text
(less than 4).Reglas horizontales
Tres o más guiones, asteriscos o guiones bajos crean una regla horizontal (<hr>). Los guiones son los más comunes. Se permiten espacios entre los caracteres. Por claridad, deja líneas en blanco alrededor de las reglas horizontales. Evita confundir --- (regla) con # (encabezado).
---
***
___
* * *
Text above
---
Text belowFormato de texto
Negrita y strong
Los asteriscos o guiones bajos dobles producen negrita (<strong>). Los asteriscos son preferidos porque los guiones bajos no funcionan a mitad de palabra (snake_case). Puedes anidar otros énfasis dentro de la negrita. Las etiquetas HTML <strong> funcionan como respaldo.
**bold text**
__also bold__
**bold with *italic* inside**
<strong>HTML bold also works</strong>
**bold**Cursiva y énfasis
Los asteriscos o guiones bajos simples crean cursiva (<em>). Los asteriscos funcionan a mitad de palabra; los guiones bajos tratan los guiones internos de palabra como literales (así no_italic_here no queda en cursiva). Usa <em> como respaldo. La cursiva es para énfasis, no solo estilo.
*italic text*
_also italic_
*italic*
<em>HTML italic</em>
normal *italic* normalNegrita + cursiva combinadas
Los asteriscos/guiones bajos triples producen negrita y cursiva a la vez. También puedes anidarlas: negrita conteniendo cursiva o viceversa. El orden no importa para el renderizado, pero debería ser consistente por legibilidad.
***bold and italic***
___also both___
**_bold and italic_**
*__bold and italic__*
combine **bold** and *italic*Tachado
Las dobles tildes (~~) crean tachado, parte de GitHub Flavored Markdown y ahora ampliamente soportado. Las etiquetas HTML <del> y <s> son respaldos equivalentes. El Markdown estándar (original) no incluye tachado.
~~strikethrough~~
~~crossed out text~~
<del>HTML delete</del>
<s>HTML strikethrough</s>
~~done~~ and ~~pending~~Marcar / resaltar
Los dobles iguales (==) para resaltar son una extensión soportada por algunos parsers (no en el núcleo de GFM). La etiqueta HTML <mark> funciona universalmente. Usa el resaltado con moderación para llamar la atención sobre términos clave — el abuso reduce su efecto.
==highlighted text==
<mark>HTML mark</mark>
This is ==important== text.
Compare **bold**, *italic*, ==mark==.Subíndice y superíndice
La sintaxis de tilde (subíndice) y circunflejo (superíndice) (~ ~ y ^ ^) son extensiones que no están en el Markdown estándar ni en GFM — soportadas por Pandoc, R Markdown y algunos más. Para soporte universal, usa HTML <sub> y <sup> o caracteres Unicode.
H~2~O is water
E = mc^2^
x^2^ + y^2^ = r^2^
1st^st^ January
CO~2~ emissionsListas
Listas sin orden
Usa -, * o + para los ítems de listas sin orden — elige uno y sé consistente (- es el más común). Indenta 2-4 espacios para ítems anidados. Mezclar marcadores en la misma lista puede causar problemas en algunos parsers. Un ítem por línea.
- item one
- item two
- item three
* asterisk works too
+ plus sign also works
- sub-item (indent 2 spaces)
- another sub-itemListas ordenadas
Las listas ordenadas usan números seguidos de puntos. Los números reales no necesitan ser secuenciales — Markdown los renumera. Para empezar en un número concreto, usa ese número primero (10. empieza en 10). Usa 1. en cada ítem para numerar automáticamente.
1. first
2. second
3. third
1. auto-numbered
1. still increments
1. third item
10. starts at 10
11. nextListas anidadas
Indenta los ítems de listas anidadas con 2-4 espacios (4 es lo más seguro para tipos mezclados). Puedes mezclar listas ordenadas y sin orden en distintos niveles. El anidamiento profundo (3+ niveles) perjudica la legibilidad — considera reestructurar. Mantén la sangría consistente.
1. top level
- nested unordered
- second nested
2. back to top
1. nested ordered
2. another
3. third top
- fruits
- apple
- granny smith
- bananaListas de tareas
La sintaxis de listas de tareas (- [x] y - [ ]) es una extensión de GitHub Flavored Markdown. El checkbox se renderiza como interactivo en GitHub/GitLab. Funciona con listas ordenadas y sin orden. Genial para READMEs, seguimiento de issues y progreso.
- [x] completed task
- [ ] incomplete task
- [ ] another todo
1. [x] done
2. [ ] not done
- [x] Write the docs
- [ ] Review PR
- [ ] DeployListas holgadas vs ajustadas
Si los ítems de la lista están separados por líneas en blanco, la lista es 'holgada' (cada ítem envuelto en <p>). Sin líneas en blanco, es 'ajustada' (sin envoltorios <p>). Esto afecta al espaciado en la salida HTML. Añade líneas en blanco deliberadamente para controlar el envoltorio de párrafos.
- tight item
- tight item
- tight item
- loose item
- loose item
- loose itemLista con varios párrafos
Para incluir varios párrafos o elementos de bloque en un ítem de lista, indenta la continuación con 4 espacios (o alinéala con el contenido del marcador de lista). Las líneas en blanco separan los subbloques. Es esencial para estructuras de lista complejas pero fácil de hacer mal.
- First item
Second paragraph of first item.
- Second item
> A blockquote inside a list item.
>
> Must be indented to align.
- Third itemEnlaces
Enlaces en línea
Los enlaces en línea usan [texto](url). Un título opcional entre comillas aparece como tooltip al pasar el ratón. Los enlaces relativos funcionan para la navegación interna del sitio. Los enlaces de ancla (#id) saltan a elementos con id coincidente. La URL no debe contener espacios — usa %20 para los espacios.
[link text](https://example.com)
[link with title](https://example.com "Title here")
[relative link](/about)
[anchor](#section-id)Enlaces por referencia
Los enlaces por referencia mantienen el texto legible separando la URL. Define las referencias en cualquier parte del documento ([ref]: url). Las definiciones de referencia no se renderizan. La forma implícita [texto][] usa el propio texto como id de referencia. Las referencias pueden reutilizarse.
[link text][ref]
[ref]: https://example.com "Optional title"
[link text][1]
[1]: https://example.com
[link text]
[link text]: https://example.comAutolinks y URLs
Las URLs sueltas se autoenlazan en GitHub Flavored Markdown. Por cumplimiento de estándares, envuelve las URLs en ángulos (<url>). La forma con ángulos funciona en cualquier sabor de Markdown. El autoenlazado puede desactivarse en algunos parsers.
https://example.com
<https://example.com>
<http://www.google.com>
Auto-linking bare URLs is supported
in GFM: visit https://example.com now.Autolinks de correo
Las direcciones de correo en ángulos se vuelven enlaces mailto: clicables. La especificación original de Markdown soportaba la forma <texto@dominio>. Algunos renderizadores ofuscan las direcciones de correo para reducir la cosecha de spam. Usa un formulario de contacto para mejor protección anti-spam en sitios públicos.
<[email protected]>
Contact: <[email protected]>
<John Doe <[email protected]>>
Mailto links work in most renderers.Títulos de enlaces
Los títulos de enlaces aparecen como tooltips al pasar el ratón. Usa comillas dobles o simples alrededor del título. Los títulos son opcionales y puramente para pistas de UX/SEO. No reemplazan al texto del enlace — los lectores de pantalla pueden ignorarlos. Mantén los títulos concisos.
[hover for title](https://example.com "Example Site")
[reference with title][a]
[a]: https://example.com "Example Site"
[title with single quotes](https://example.com 'Single')Enlaces internos y de ancla
Las anclas de encabezado se generan automáticamente a partir del texto del encabezado (en minúsculas, espacios a guiones, puntuación eliminada) en la mayoría de parsers. Para IDs personalizados, usa HTML <a id="..."> o la extensión de atributo {#id} (Pandoc/marked). Los enlaces de ancla son esenciales para los índices de contenido.
## Section Heading
[jump to Section](#section-heading)
[back to top](#top)
<a id="custom-id"></a>
[custom anchor](#custom-id)
## Heading {#explicit-id}Imágenes
Imagen básica
La sintaxis de imagen es como la de enlaces pero precedida de !. El texto alt es obligatorio por accesibilidad — describe la imagen para los lectores de pantalla y se muestra si la imagen no carga. La ruta puede ser relativa, absoluta o una URL. El título es opcional.


Imagen con texto alt
El texto alt debería ser significativo y conciso — describe el propósito de la imagen, no solo 'imagen'. Para imágenes decorativas, un alt vacío (alt='') es aceptable para decir a los lectores de pantalla que la salten. Nunca uses 'imagen de' o 'foto de' — los lectores de pantalla ya lo anuncian.


Imágenes enlazadas
Envuelve una imagen en un enlace anidando la sintaxis de imagen dentro de la de enlace: [](url). Común para miniaturas que enlazan a versiones a tamaño completo, badges que enlazan al estado de CI y logos que enlazan al inicio. Mantén el texto alt describiendo el destino, no solo la imagen.
[](https://example.com/full)
[](/)
[](https://ci.example.com)Imágenes por referencia
Las imágenes por referencia usan el mismo estilo de referencia que los enlaces, precedido de !. Define la referencia de imagen una vez y reutilízala. Útil cuando la misma imagen aparece varias veces o para mantener legibles los párrafos con muchas imágenes.
![alt text][img-ref]
[img-ref]: https://example.com/image.png "Title"
![alt][logo]
[logo]: /assets/logo.pngDimensiones de imagen y figure
El Markdown estándar no tiene sintaxis de tamaño de imagen — usa HTML <img> con atributos width/height. Los anchos en porcentaje habilitan el tamaño responsivo. La combinación <figure> + <figcaption> proporciona leyendas semánticas (HTML5). Algunos Markdown extendidos (Pandoc) soportan {width=300}.
<img src="image.png" width="300" height="200" alt="sized image">
<img src="banner.png" width="100%" alt="responsive">
<figure>
<img src="diagram.png" alt="flowchart">
<figcaption>Figure 1: System flow</figcaption>
</figure>Código en línea y escapado
Código en línea
Envuelve el código en línea en backticks simples. Para mostrar backticks dentro del código, usa backticks dobles como delimitador (o más). El código en línea se renderiza en monoespaciada y no se parsea como Markdown. Genial para nombres de archivo, comandos e identificadores de código.
Use the `printf()` function.
Inline code: `const x = 42;`
Code with backticks: ``use `code` here``
A `<div>` element.Escapar backticks en spans de código
Para incluir un backtick dentro de un span de código, usa más backticks como delimitador de los que aparecen dentro: backticks dobles alrededor de un backtick simple. Fuera de los spans de código, escapa un backtick con una barra invertida. La valla de cierre debe coincidir con la longitud de la de apertura.
To show a backtick inside code,
use more backticks as delimiters:
`` ` `` one backtick
`` a`b `` backtick inside text
Use \ to escape outside code:
A literal backtick: \`Spans de código y espacios
Los spans de código conservan los espacios internos exactamente. Un truco común: envolver el contenido con un espacio inicial/final único para mostrar espacios al inicio o al final que de otro modo se recortarían. Un espacio a cada lado se elimina automáticamente.
` spaced ` (spaces preserved)
` code ` with one space pad
`function f() { return; }`
` multi word code `Escapes con barra invertida
La barra invertida escapa los caracteres especiales de Markdown: backtick, asterisco, guion bajo, llaves, corchetes, paréntesis, almohadilla, más, menos, punto, exclamación y la propia barra invertida. Escapar renderiza el carácter literalmente. Escapa solo los caracteres que de otro modo se interpretarían como formato.
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an imageCaracteres a escapar
Estos son los caracteres escapables de Markdown. No hace falta escaparlos en todas partes — # solo importa al inicio de línea, - en contexto de lista, y así. Ante la duda, escapa. Las llaves y los paréntesis normalmente solo necesitan escaparse en contextos concretos (enlaces, cadenas de plantilla).
\\ backslash
\` backtick
\* asterisk
\_ underscore
\{ \} curly braces
\[ \] square brackets
\( \) parentheses
\# hash
\+ plus
\- minus
\. dot
\! exclamationBloques de código
Bloques de código por sangría
Indentar con 4 espacios (o una tabulación) crea un bloque de código. Los bloques por sangría carecen de resaltado de sintaxis y de etiqueta de lenguaje. No pueden usarse dentro de ítems de lista (se tratan como continuación). Prefiere los bloques de código con valla para contenido nuevo — los bloques por sangría son herencia.
Normal paragraph.
// indented code (4 spaces)
function hello() {
console.log("hi");
}
Back to normal text.Bloques de código con valla
Los backticks o tildes triples crean bloques de código con valla. Las vallas son preferidas sobre los bloques por sangría — son inequívocas y soportan pistas de lenguaje. Las tildes (~~~) son útiles cuando el código en sí contiene backticks triples. Cierra siempre la valla con el mismo número de caracteres.
```
plain code block
multiple lines
```
~~~
also a fenced block
using tildes
~~~Resaltado de sintaxis
Añade un identificador de lenguaje justo después de la valla de apertura para el resaltado de sintaxis (por ejemplo, js, python). La mayoría de renderizadores usan highlight.js o Prism. Alias comunes: js, ts, py, rb, sh, json, html, css. Si el lenguaje es desconocido, omítelo para monoespaciado plano.
```javascript
const greet = (name) => {
console.log(`Hello, ${name}!`);
};
```
```python
def greet(name):
print(f"Hello, {name}!")
```
```bash
echo "Hello, $USER"
```Vallas de código anidadas
Para mostrar backticks dentro de un bloque de código, usa una valla distinta (tildes para contenido con backticks, o más backticks de los que aparecen dentro). Cuatro backticks enmarcan contenido que contiene backticks triples. La valla de cierre debe coincidir con la longitud de la de apertura.
Use four backticks to wrap triple backticks:
````
```js
console.log("inside");
```
````
Or use tildes to wrap backtick content:
~~~
```js
code with backticks
```
~~~Código en listas
Los bloques de código con valla dentro de ítems de lista deben indentarse para alinearse con el texto de la lista (típicamente 3 espacios para listas con -, 4 para listas con 1.). Los bloques por sangría dentro de listas necesitan 8 espacios (4 para la lista + 4 para el código). Ajustar la alineación bien es una de las tareas más delicadas de Markdown.
1. Item with code:
```
code block indented to align
```
2. Next item with inline `code`.
- Or indent code 4 spaces beyond
the list marker (8 total).Citas en bloque
Cita en bloque básica
El carácter > inicia una cita en bloque. Puedes prefijar cada línea o solo la primera — la mayoría de parsers unen las líneas consecutivas. Las citas se renderizan como citas indentadas y estilizadas (<blockquote>). Úsalas para citas, avisos y resaltar fragmentos.
> This is a blockquote.
> It can span multiple lines.
> Or just prefix the first line
and continuation lines without >
will still be part of the quote.Cita en bloque multilínea
Usa líneas > en blanco para separar párrafos dentro de una cita (de lo contrario se fusionan). El > en una línea en blanco mantiene la cita abierta. Sin líneas en blanco entre párrafos, el texto fluye como un solo párrafo. Cierra siempre con una línea normal.
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.
End of quote.Citas anidadas
Varios caracteres > crean citas anidadas (>> para dos niveles, >>> para tres). Añade espacios por legibilidad. El anidamiento profundo (3+ niveles) se vuelve difícil de leer y estilizar — prefiere aplanar. Cada nivel añade sangría en la salida HTML.
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer
> Outer
>> Deeper
>>> Deepest levelCitas con otros elementos
Las citas pueden contener la mayoría de elementos de Markdown: encabezados, listas, código, énfasis, incluso tablas. Prefija cada línea con > (y un espacio) para mantenerlas dentro de la cita. Esto hace las citas potentes para avisos, pero el contenido complejo exige un alineado cuidadoso de >.
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```Cita con atribución
Markdown no tiene sintaxis formal de atribución. Convenciones comunes: prefijar al autor con una raya en una línea nueva, o usar HTML <blockquote> con <footer> y <cite> para atribuciones semánticas. Para citas académicas, considera una nota al pie con la fuente.
> Be the change you wish to see
> in the world.
> — Mahatma Gandhi
> "Simplicity is the soul of efficiency."
> — Austin Freeman
<blockquote>
<p>Quote text.</p>
<footer>— <cite>Author</cite></footer>
</blockquote>Tablas
Tabla básica
Las tablas usan pipes (|) para separar columnas y guiones para separar el encabezado. La fila de encabezado es obligatoria. Los pipes en los bordes de línea son opcionales pero mejoran la legibilidad. Los anchos de columna no importan — las celdas se redimensionan. Las tablas son una extensión de GitHub Flavored Markdown.
| Name | Age | City |
|-------|-----|----------|
| Alice | 30 | NYC |
| Bob | 25 | London |
| Carol | 35 | Paris |Alineación de celdas
Los dos puntos en la fila separadora controlan la alineación: :--- izquierda, :---: centro, ---: derecha. Sin dos puntos, por defecto a la izquierda. La alineación se aplica a toda la columna y fija el text-align de CSS en la salida HTML. Útil para columnas numéricas (a la derecha) y encabezados (centrados).
| Left | Center | Right |
|:-------|:------:|-------:|
| left | center | right |
| L | C | R |
| Default | alignment |
|---------|-----------|
| no mark | left |Tabla con formato
Las celdas pueden contener Markdown en línea: negrita, cursiva, código, enlaces, tachado, emoji. Los elementos de bloque (encabezados, listas, bloques de código) no funcionan dentro de las celdas — usa HTML si hace falta. Mantén el contenido de las celdas corto por legibilidad. Escapa los pipes con una barra invertida para mostrar pipes literales.
| Feature | Status | Notes |
|------------|:------:|--------------------|
| **Bold** | done | *finished* |
| `code` | wip | [docs](docs.md) |
| ~~old~~ | removed| gone in v2 |
| [link][1] | done | see [ref][1] |Tabla compleja
Las tablas escalan a muchas filas y columnas pero se mantienen simples por celda. Para spans de código con comas, envuélvelos en backticks. Escapa los pipes literales con una barra invertida y pipe. Los datos complejos (celdas multilínea, tablas anidadas) exigen HTML <table>. Considera una lista si la tabla se hace demasiado ancha.
| Name | Role | Skills | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead | `js`, `ts`, `go` | yes |
| Bob | Junior | `py`, `sql` | no |
| Carol | Senior | `rust`, `c++` | yes |
Escaped pipe: \| literalConsejos y límites de las tablas
Las tablas de Markdown están limitadas: sin fusión de celdas, sin contenido multilínea, sin elementos de bloque, sin tablas anidadas. Para esto, usa HTML crudo. Mantén las tablas pequeñas y escaneables. Si una tabla necesita notas al pie o texto largo, divídela. Herramientas como TablesGenerator.com ayudan a construirlas rápido.
| A | B |
|---|---|
| 1 | 2 |
Tip: Use \| to escape pipes.
Limitation: no multi-line cells,
no blockquotes, no lists in cells.
For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>Notas al pie
Notas al pie básicas
Las notas al pie usan marcadores [^id] en el texto y [^id]: definición en otra parte. El id puede ser un número o una palabra. Los renderizadores crean números en superíndice clicables y una sección de notas al pie al final. Soportado por GFM, Pandoc y la mayoría de parsers modernos.
Here is a sentence with a footnote.[^1]
[^1]: This is the footnote text.
Another sentence.[^note]
[^note]: Footnotes can use named labels.Referencias múltiples
Una nota al pie puede referenciarse varias veces — cada [^id] enlaza a la misma definición. Las líneas de continuación de la definición van indentadas. La primera referencia normalmente recibe el número en superíndice; las siguientes enlazan a la misma nota.
Use the term[^term] twice[^term] in the text.
[^term]: A single definition referenced
multiple times.
First[^1] and second[^1] reference.
[^1]: One definition, two links back.Notas al pie en línea
Las notas al pie en línea (^[texto]) incrustan el contenido de la nota directamente en la referencia, soportadas por Pandoc y algunas extensiones (no en el núcleo de GFM). Mantienen el contenido en un único lugar pero pueden interrumpir el flujo de lectura. Úsalas para notas cortas; las largas son mejores como referencias.
Here is an inline footnote^[The note text
right here in the body.] in a sentence.
Pandoc also supports: ^[inline notes].
And another[^1].
[^1]: Traditional reference style.Posicionamiento de notas al pie
Las definiciones de notas al pie pueden colocarse en cualquier parte del documento — los renderizadores las recogen y las muestran al final. Indenta las líneas de continuación (4 espacios). Las notas al pie funcionan dentro de citas e ítems de lista. La posición en el código fuente no afecta a la posición de salida.
Body text with a note.[^1]
More paragraphs here.
[^1]: Definitions can appear anywhere.
They float to the bottom in output.
> Even inside blockquotes.[^2]
[^2]: The renderer collects all notes
and renders them at the end.Notas al pie con código y formato
Las definiciones de notas al pie soportan Markdown en línea (negrita, cursiva, código) y contenido multipárrafo (indenta las líneas de continuación con 4 espacios). Los bloques de código por sangría dentro de las notas necesitan 8 espacios. Mantén las notas concisas — el contenido técnico largo es mejor en el texto principal o un apéndice.
See the API[^api] for details.
[^api]: Use `fetch('/api/data')` to call.
Supports **bold** and *italic*.
Multi-paragraph: indent each line.
Code blocks need indentation:
indented code inside footnoteListas de definición
Lista de definición básica
Las listas de definición usan un término en una línea y luego dos puntos (:) seguidos de la definición. Soportadas por PHP Markdown Extra, Pandoc y algunas extensiones (no en el núcleo de GFM). Se renderizan como <dl><dt><dd>. Útiles para glosarios y pares término-definición.
Term
: Definition of the term.
Markdown
: A lightweight markup language.
HTML
: HyperText Markup Language.Varios términos
Varios términos consecutivos (sin dos puntos) pueden compartir una única definición. Cada término se convierte en un <dt> y la definición en un <dd>. Útil cuando el mismo concepto tiene varios nombres o alias. Mantén los términos en líneas separadas.
CSS
Cascading Style Sheets
: A style sheet language.
JS
JavaScript
: A programming language.
Both terms
: Share one definition.Varias descripciones
Varias definiciones consecutivas (cada una empezando con dos puntos) para un término crean varios elementos <dd>. Útil para listar varios significados o aspectos distintos de un término. Cada línea con dos puntos es una entrada de definición aparte.
Markdown
: A markup language.
: A tool for writing for the web.
Apple
: A fruit.
: A technology company.Listas de definición anidadas
Las listas de definición anidadas exigen indentar la lista interior (2-4 espacios) dentro de la definición exterior. El soporte de los parsers varía — algunos renderizadores no manejan el anidamiento. Para estructuras jerárquicas de términos complejas, considera HTML <dl> por fiabilidad. Pruébalo en tu renderizador objetivo.
Term
: Definition one.
Nested term
: Nested definition.
: Definition two for top term.Listas de definición con elementos de bloque
Las entradas de las listas de definición pueden contener varios párrafos, citas y bloques de código — indenta el contenido de continuación con 4 espacios (más allá de los dos puntos). Los bloques de código dentro necesitan 8 espacios en total. Es potente pero frágil; el contenido complejo es más seguro en HTML <dl>.
Markdown
: A markup language.
With multiple paragraphs in the
definition (indent 4 spaces).
> Blockquote inside definition.
: Second definition with code:
indented code (8 spaces)Índice de contenido
Índice automático
La mayoría de parsers no generan índices automáticamente por defecto. Algunos (marked con el plugin toc, MDX) soportan marcadores [TOC] o {:toc}. Herramientas como Doctoc y markdown-toc los generan a partir de los encabezados. Para sitios estáticos, los componentes de índice leen las anclas de los encabezados en build o en runtime.
## Table of Contents
1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)
Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.Índice manual
Un índice manual es una lista anidada de enlaces a las anclas de los encabezados. Los ids de ancla se derivan del texto del encabezado (minúsculas, guiones para los espacios, puntuación eliminada). Indenta para reflejar la jerarquía de encabezados. Actualízalo a mano cuando cambien los encabezados, o usa un generador.
# My Document
## Contents
- [Intro](#intro)
- [Setup](#setup)
- [Prerequisites](#prerequisites)
- [Install](#install)
- [Usage](#usage)
## Intro
...Reglas de generación de anclas
La generación de anclas varía según el parser. Reglas comunes: minúsculas, espacios a guiones, quitar puntuación, conservar alfanuméricos. GitHub conserva los emojis y algo de unicode. Los números y puntos a menudo se eliminan. Ante la duda, inspecciona el HTML renderizado para hallar el id real.
## Hello World -> #hello-world
## Hello, World! -> #hello-world
## C++ & Rust -> #c--rust
## Uber Heading -> #uber-heading
## 1. Getting Started -> #1-getting-started
## API v2.0 -> #api-v20IDs de ancla personalizados
Para anclas fiables, añade IDs explícitos. La sintaxis de atributo {#id} funciona en Pandoc, marked y algunas extensiones. El truco HTML <a id="..."> funciona en todas partes — colócalo antes o dentro del encabezado. Los IDs personalizados sobreviven a los cambios de texto del encabezado.
## Heading {#custom-id}
<a id="my-anchor"></a>
## Heading
## Heading<a id="also"></a>
[link to custom](#custom-id)Navegación del índice y enlaces de retorno
Los enlaces de volver arriba mejoran la navegación en documentos largos. El HTML <details>/<summary> crea un índice colapsable — genial para sidebars o READMEs largos. Combínalo con enlaces de ancla para una navegación suave. Añade scroll-margin-top en CSS para compensar los encabezados fijos.
## Section
Content here.
[Back to top](#table-of-contents)
---
<details>
<summary>Table of Contents</summary>
- [Section 1](#section-1)
- [Section 2](#section-2)
</details>Emoji y caracteres especiales
Shortcodes de emoji
Los shortcodes de emoji (:nombre:) están soportados por GitHub/GitLab (usando el conjunto EmojiOne/Twemoji). Hay miles de emoji con nombre. Los shortcodes son cómodos pero no portables — pueden renderizarse literalmente en parsers no GFM. Usa emoji Unicode crudos para máxima compatibilidad.
:smile: :heart: :thumbsup: :rocket:
GFM supports shortcodes:
:sparkles: new feature :tada:
:checkered_flag: launch!
:bug: fixed issue #42Emoji comunes
La mayoría de editores y renderizadores modernos manejan directamente el emoji Unicode crudo — simplemente pégalos. Los shortcodes son específicos de GitHub. El emoji puede transmitir tono y estado (check/cross para resultados, bug para bugs). Úsalo con moderación en documentos formales; es genial en READMEs y changelogs.
:smile: smile :heart: heart :thumbsup: thumbsup
:rocket: rocket :star: star :warning: warning
:check: check :x: cross :bulb: bulb
:fire: fire :tada: tada :bug: bug
:book: book :wrench: wrench :zap: zapEntidades HTML
Las entidades HTML funcionan en Markdown ya que pasa a HTML. Usa & para el ampersand literal (especialmente en URLs/atributos), < > para los ángulos, © ® ™ para símbolos. Las formas numéricas (©) y hexadecimales (©) cubren cualquier carácter Unicode.
& < > " '
© ® ™
— – …
© ©
Use & to show a literal &.Caracteres especiales
Markdown no convierte la puntuación plana en caracteres tipográficos (comillas inteligentes) por defecto — usa entidades HTML o pega Unicode. Las rayas y las comillas tipográficas mejoran la tipografía. Muchos editores las autocorrigen. Para flechas y símbolos, las entidades son lo más claro.
-- em dash (or —)
-- en dash (or –)
... ellipsis (or …)
' ' curly quotes (‘ ’)
" " curly quotes (“ ”)
-> arrow (or →)
(tm) (r) (c)Combinar emoji y Markdown
El emoji se combina con cualquier elemento de Markdown: encabezados, listas, negrita, enlaces, citas. Añade señales visuales a changelogs, READMEs y plantillas de issues. Mantén el uso de emoji consistente (por ejemplo, una convención de changelog). Evita el emoji en la escritura formal/acad émica.
## New Features
- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs
**Status:** :white_check_mark: Ready
> :warning: **Warning:** Deprecated!
[:book: Read the docs](/docs)Diagramas Mermaid
Diagrama de flujo Mermaid
Mermaid es un lenguaje de diagramación basado en texto renderizado por GitHub, GitLab y muchos generadores de sitios estáticos. Envuelve el código Mermaid en un bloque con valla mermaid. flowchart TD (de arriba abajo) o LR (de izquierda a derecha) define la dirección. Los nodos usan [], {}, () para formas distintas.
```mermaid
flowchart TD
A[Start] --> B{Is it?}
B -->|Yes| C[Do it]
B -->|No| D[Do not]
C --> E[End]
D --> E
```Diagrama de secuencia Mermaid
Los diagramas de secuencia muestran interacciones entre participantes a lo largo del tiempo. ->> es una flecha sólida (petición), -->> una discontinua (respuesta). participant declara actores. Útil para documentar flujos de API, protocolos y paso de mensajes. Auto-renderizado en GitHub.
```mermaid
sequenceDiagram
participant A as Alice
participant B as Bob
A->>B: Hello Bob!
B-->>A: Hi Alice!
A->>B: How are you?
B-->>A: Good, thanks!
```Diagrama de clases Mermaid
Los diagramas de clases modelan estructuras orientadas a objetos. + significa público, - privado, # protegido. <|-- denota herencia. Mermaid soporta asociaciones, composiciones e interfaces. Genial para documentar la arquitectura del código directamente en Markdown.
```mermaid
classDiagram
class Animal {
+String name
+int age
+makeSound() void
}
class Dog {
+fetch() void
}
Animal <|-- Dog
```Diagrama de estados Mermaid
Los diagramas de estados muestran transiciones de estado. [*] marca los estados de inicio/fin. Las flechas etiquetan transiciones con eventos (estado --> estado: evento). Útil para documentar protocolos, estados de UI y el ciclo de vida de objetos. stateDiagram-v2 es la sintaxis moderna.
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Processing: start
Processing --> Done: complete
Processing --> Error: fail
Done --> [*]
Error --> [*]
```Diagrama de Gantt Mermaid
Los diagramas de Gantt visualizan calendarios de proyecto. dateFormat fija el parseo de fechas. Las tareas usan id, inicio, duración (por ejemplo, 7d). 'after a1' encadena tareas. Las secciones agrupan tareas relacionadas. Útil para READMEs y planes de proyecto — auto-renderizado en GitHub sin herramientas externas.
```mermaid
gantt
title Project Schedule
dateFormat YYYY-MM-DD
section Design
Spec :a1, 2024-01-01, 7d
Mockups :after a1, 5d
section Build
Develop :2024-01-13, 14d
Test :7d
```Gráfico de pastel Mermaid
Los gráficos de pastel muestran proporciones como porcentajes (los valores son relativos). El título es opcional. Etiquetas entre comillas, valores tras los dos puntos. Mermaid también soporta grafos git, diagramas ER, mapas de viaje y mapas mentales — renderizables en Markdown en plataformas soportadas.
```mermaid
pie title Browser Market Share
"Chrome" : 65
"Safari" : 18
"Edge" : 5
"Firefox" : 3
"Other" : 9
```GitHub Flavored Markdown
Listas de tareas (GFM)
Las listas de tareas de GitHub Flavored Markdown (GFM) renderizan checkboxes interactivos en GitHub. [x] marcado, [ ] sin marcar. Funcionan en issues, PRs, comentarios y READMEs. Las barras de progreso aparecen en las listas de issues. La sintaxis ya está ampliamente soportada más allá de GitHub.
- [x] Done task
- [ ] Todo task
- [ ] Another todo
## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] DeployTachado (GFM)
GFM añade tachado (~~texto~~) al Markdown estándar. Funciona a través de líneas y se combina con otro formato. Se renderiza como <del>. Originalmente una extensión de GFM, ahora en las adiciones de la especificación CommonMark. Útil para mostrar ediciones y deprecaciones.
~~deleted text~~
old ~~price~~ new
~~this line is wrong~~
Combine: **bold ~~struck~~ text**
~~multi-line
strikethrough~~Tablas (GFM)
Las tablas son una característica de GFM (no del Markdown original). La sintaxis de pipes con fila de encabezado y separadora es obligatoria. Las tablas GFM soportan alineación, formato en línea y pipes escapados. Para tablas complejas (fusión, anidamiento), recurre a HTML.
| Feature | Status |
|------------|:------:|
| Tables | yes |
| Tasks | yes |
| Auto-links | yes |
Tables are core to GFM, not in
the original Markdown spec.Alertas de GitHub
Las GitHub Alerts (2023+) usan un marcador [!TIPO] en la primera línea de una cita: NOTE, TIP, IMPORTANT, WARNING, CAUTION. Se renderizan con colores e iconos distintivos en GitHub. Geniales para avisos en READMEs y documentación. La sintaxis es específica de GitHub.
> [!NOTE]
> Useful information that users
> should know.
> [!WARNING]
> Urgent info about risks.
> [!IMPORTANT]
> Key information.
> [!TIP]
> Helpful advice.HTML crudo no permitido
GFM filtra el HTML crudo por seguridad — <script>, <style>, <title>, a veces <iframe> y los manejadores de eventos se eliminan. Esto previene XSS en contenido generado por usuarios. El HTML seguro como <details>, <kbd>, <sup> pasa. Conoce la lista permitida de tu renderizador al mezclar HTML.
GFM sanitizes some HTML tags:
<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>
These are stripped for security.Autolinks (GFM)
GFM autoenlaza las URLs sueltas (https://...) y los dominios www. sin ángulos. Por portabilidad, los ángulos (<url>) funcionan en cualquier sabor. El autoenlazado puede sorprender — usa ángulos cuando quieras mostrar una URL literal con otro texto adyacente.
Visit https://example.com now.
www.google.com auto-links too.
<https://example.com> always works.
In GFM, bare URLs and www. links
become clickable automatically.Sintaxis extendida
Resaltado
La sintaxis de resaltado ==texto== es una extensión (no en GFM ni CommonMark) — soportada por algunos parsers como markdown-it con un plugin. La etiqueta HTML <mark> está universalmente soportada. Usa el resaltado para enfatizar términos clave; el abuso reduce el impacto.
==highlighted text==
<mark>HTML highlight</mark>
Some parsers (not GFM core) support
==this syntax== for highlighting.
Use <mark> for universal support.Subíndice y superíndice
El subíndice (~texto~) y el superíndice (^texto^) son extensiones de Pandoc/markdown-it, no estándar. Para un renderizado universal, usa HTML <sub>/<sup> o Unicode. Útil en contenido científico y matemático escrito en Markdown.
H~2~O (subscript)
x^2^ (superscript)
E = mc^2^
H~2~SO~4~
Pandoc/R Markdown support ~ and ^.Sintaxis de atributos
La sintaxis de atributos {#id .class clave=val} (Pandoc, algunos plugins de markdown-it) adjunta atributos HTML a los elementos. Útil para ganchos de estilo, anclas personalizadas y objetivos de enlaces. No es portable — cae a texto literal en parsers sin soporte. Úsala con moderación.
## Heading {#id .class}
{width=50%}
[link](url){target=_blank}
> Quote {.callout}Contenedores personalizados
Los contenedores personalizados (:::tipo ... :::) están soportados por VuePress, Docusaurus, VitePress y herramientas de documentación similares. Se renderizan como cajas de aviso estilizadas. El tipo se mapea a una clase CSS. Genial para documentación temática pero no portable a renderizadores de Markdown plano.
:::note
This is a note container.
:::
:::warning
This is a warning.
:::
::: details Open me
Hidden content.
:::Matemáticas y LaTeX (KaTeX)
El soporte de matemáticas depende del renderizador: GitHub soporta $...$ en línea y $$...$$ en bloque (con MathJax/KaTeX). Algunos parsers de Markdown no soportan matemáticas. Para máxima compatibilidad, renderiza las matemáticas a imágenes o usa MathJax directamente. Útil para documentación científica y técnica.
Inline: $E = mc^2$ in a sentence.
Block:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
Some parsers support \( \) and
\[ \] delimiters too.Herramientas y editores
VS Code
VS Code tiene vista previa de Markdown integrada y un rico ecosistema de extensiones. Markdown All in One añade atajos (negrita, índice, vista previa). markdownlint impone estilo. Preview Enhanced soporta diagramas, matemáticas y exportaciones. Configura el ajuste de línea para una edición cómoda.
# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc
# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V
# Settings:
"[markdown]": {
"editor.wordWrap": "on",
"editor.quickSuggestions": true
}Typora
Typora es un editor de Markdown WYSIWYG popular — renderiza en línea mientras escribes, eliminando el flujo de trabajo de paneles divididos. Soporta GFM, tablas, vallas de código, matemáticas y Mermaid. Exporta a muchos formatos vía herramientas integradas. De pago pero pulido; genial para flujos centrados en la escritura.
Typora: a WYSIWYG Markdown editor.
- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS
Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italicObsidian
Obsidian guarda las notas como archivos Markdown locales con características potentes: wiki-links, backlinks, vista de grafo y tags. Extiende Markdown con callouts, incrustaciones y Dataview. Ideal para Zettelkasten y gestión de conocimiento personal. Gratis para uso personal.
Obsidian: a Markdown knowledge base.
- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title
[[note|alias]] for renamed links.Lint de Markdown
markdownlint impone un estilo consistente entre archivos Markdown. Configura las reglas en .markdownlint.json. Desactivaciones comunes: MD013 (longitud de línea) para prosa, MD033 (HTML en línea) cuando se necesita HTML. MD040 te recuerda etiquetar las vallas de código con un lenguaje. Se integra con CI y editores.
# .markdownlint.json (config)
{
"MD013": false,
"MD024": { "siblings_only": true },
"MD033": false,
"default": true
}
# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs languagePandoc
Pandoc es la 'navaja suiza' de la conversión de documentos — Markdown a/desde HTML, PDF, Word, LaTeX, EPUB, diapositivas. Soporta extensiones de Markdown (citas, matemáticas, listas de definición, atributos crudos). El flag -s crea documentos independientes. Imprescindible para flujos académicos y editoriales.
# Convert Markdown to many formats:
pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf
# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html
# With a table of contents:
pandoc input.md --toc -o output.html
# Support extensions:
pandoc -f markdown+smart input.mdEditores en línea
Los editores en línea son geniales para ediciones rápidas y compartir. StackEdit y Dillinger son editores individuales completos. HackMD/HedgeDoc añaden colaboración en tiempo real. El editor web de GitHub tiene una pestaña Preview. Cada uno soporta Markdown estándar; las características GFM funcionan mejor en el editor de GitHub.
Popular online Markdown editors:
- StackEdit (stackedit.io)
Full-featured, syncs to cloud.
- Dillinger (dillinger.io)
Clean, exports to many formats.
- HackMD / HedgeDoc
Real-time collaborative editing.
- GitHub web editor
Preview tab for .md files.
- Markdown Live Preview
Lightweight, instant preview.Buenas prácticas
Legibilidad primero
El principio central de Markdown es la legibilidad como texto plano. Prefiere la sintaxis más legible: # encabezados, - listas, **negrita**. Evita el anidamiento excesivo y el formato excesivo. Si el código fuente crudo es agradable de leer en un editor de texto, estás usando bien Markdown.
# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).
# Bad: hard to read raw
##Section or ***overkill***
Tip: Preview raw Markdown often.
If it reads well as text, it is good.Longitud de línea y ajuste
Dos enfoques válidos: el ajuste duro (una frase por línea) da diffs de git limpios y edición fácil; el ajuste suave (un párrafo por línea) evita el trabajo de reorganizar. Elige uno por proyecto y sé consistente. Configura el ancho de ajuste de tu editor (típicamente 80-120 caracteres) en consecuencia.
# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.
# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.
# Many projects prefer one sentence
# per line for clean git diffs.Consistencia
Markdown ofrece múltiples sintaxis para el mismo resultado (negrita ** vs __, listas - vs * vs +). Elige una convención por proyecto y hazla cumplir con markdownlint. La consistencia reduce la carga cognitiva para lectores y contribuidores, y facilita el procesamiento automatizado.
# Pick one style and stick to it:
- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)
Consistent style is more
maintainable and professional.Buena práctica de enlaces
Usa enlaces por referencia para URLs largas y mantener la prosa legible. Usa enlaces en línea para referencias cortas y locales. El texto de enlace descriptivo mejora la accesibilidad y el SEO — evita 'haz clic aquí'. Los títulos añaden contexto como tooltips. Agrupa las definiciones de referencia al final de la sección o documento.
# Reference links for long URLs:
See the [docs][docs] for details.
[docs]: https://example.com/very/long/url
# Inline for short links:
Edit [index.js](index.js).
# Title for context:
[API](api.md "REST API reference")
Keep link text descriptive,
not 'click here' or 'link'.Accesibilidad
La accesibilidad importa en Markdown: texto alt significativo para las imágenes (alt vacío para las decorativas), texto de enlace descriptivo (no 'haz clic aquí'), jerarquía de encabezados correcta (no te saltes niveles) y HTML semántico (kbd, abbr, cite) donde Markdown se queda corto. Los lectores de pantalla dependen de esto.
# Always add alt text to images:

# Empty alt for decorative images:

# Descriptive link text:
[Read the installation guide](install.md)
# Avoid: [click here](url)
# Use heading hierarchy in order.
# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>Errores comunes
Trampas comunes: faltar líneas en blanco alrededor de elementos de bloque (listas, citas, código), sangría inconsistente en listas anidadas, vallas de código sin cerrar y mezclar tabulaciones/espacios. Previsualiza siempre antes de publicar. Corre markdownlint para detectar problemas automáticamente. Prueba en tu renderizador objetivo.
# Missing blank line before lists:
Text
- item # may merge with text!
# Fix:
Text
- item
# Unclosed code fence:
```
code
# (missing closing fence)
# Inconsistent list indentation:
- a
- b (2 spaces)
- c (3 spaces — may break)Fragmentos de Markdown relacionados
Copy-paste ready code for common tasks.
Headings
Six levels of ATX and Setext headings.
Links and Images
Inline, reference, and auto links plus images.
Code Blocks
Fenced, indented, and inline code.
Tables
GFM tables with column alignment.
Lists
Ordered, unordered, and nested lists.
Blockquotes
Single, multi-line, and nested quotes.
Emphasis
Italic, bold, strikethrough, and escaping.
Task Lists
GFM checkboxes for to-do items.
Was this helpful?