Markdown fue creado por John Gruber en 2004 con un objetivo único y elegante: escribir texto plano que se lea naturalmente y luego convertirlo a HTML limpio. Dos décadas después está en todas partes — archivos README de GitHub, descripciones de pull requests, mensajes de Slack, documentos de Notion, entradas de blog, respuestas de chat de IA. Es una de esas herramientas que usarás cada día por el resto de tu carrera, te des cuenta conscientemente o no.

Qué es realmente Markdown

Markdown es texto plano con una sintaxis ligera y legible superpuesta. Un # al inicio de una línea se convierte en un <h1>. Envolver una palabra en **dobles asteriscos** la pone en negrita. Los backticks producen código en línea. La filosofía de diseño central es que la fuente Markdown debe ser legible tal cual — incluso antes de renderizarse. Si alguna vez has escrito un correo electrónico con *asteriscos alrededor del énfasis* o usado guiones para una lista con viñetas, ya estabas escribiendo algo muy similar a Markdown.

Aquí hay un antes y después rápido. El Markdown de la izquierda produce el HTML de la derecha:

markdown
## Getting Started

Install the package with **npm**:

`npm install my-library`

Then import it in your project — see the [docs](https://example.com) for details.
html
<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>

Tú escribes la mitad superior; un procesador Markdown produce la mitad inferior. Ese paso de traducción es invisible una vez que está en tu editor o pipeline de CI.

Sintaxis básica — La parte que comparte cada variante

Cualquier variante de Markdown que estés usando, estos bloques de construcción funcionan en todas partes:

  • Encabezados — # H1, ## H2, ### H3 (hasta seis niveles)
  • Negrita e itálica — **negrita**, *itálica*, ***ambas***
  • Enlaces — [texto del enlace](https://url.com)
  • Imágenes — ![texto alternativo](imagen.png)
  • Código en línea — `backtick` envuelve un fragmento; los triples backticks abren un bloque de código delimitado
  • Citas en bloque — comienza una línea con >
  • Listas desordenadas — líneas que comienzan con - o *
  • Listas ordenadas — líneas que comienzan con 1., 2., etc.
  • Regla horizontal — tres o más guiones: ---

Aquí hay un fragmento realista de README que usa todo lo anterior juntos:

markdown
# json-transform

> A zero-dependency library for transforming JSON structures.

## Installation

```bash
npm install json-transform
```

## Usage

```js
import { transform } from 'json-transform';

const result = transform(input, schema);
```

## Features

- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies

See the [full documentation](https://json-transform.dev/docs) for advanced options.

---

MIT License
Consejo: puedes usar nuestra herramienta Vista Previa de Markdown para pegar cualquier Markdown y verlo renderizado instantáneamente — útil para verificar la sintaxis antes de enviar a GitHub.

El problema de las variantes — CommonMark, GFM y otros

Aquí está el problema: "Markdown" no es una sola cosa. La especificación original de Gruber de 2004 fue intencionalmente laxa, lo que llevó a años de implementaciones incompatibles. Diferentes analizadores manejaban los casos límite — listas anidadas, líneas en blanco dentro de citas, precedencia entre énfasis y enlaces — de diferentes maneras. El mismo archivo fuente se renderizaría de manera diferente en diferentes herramientas.

CommonMark (lanzado en 2014) arregló esto. Un grupo de desarrolladores — incluidas personas de GitHub, Stack Overflow y Reddit — escribió una especificación rigurosa e inequívoca que cubría cada caso límite con una suite de pruebas de 652 ejemplos. La mayoría de las herramientas modernas ahora usan CommonMark como base.

GitHub luego extendió CommonMark con sus propias adiciones y publicó GitHub Flavored Markdown (GFM). GFM es lo que escribes en los READMEs, issues y pull requests de GitHub. Muchas otras herramientas también han adoptado las extensiones de GFM, pero no todas — por lo que lo que se renderiza en GitHub puede no renderizarse de la misma manera en tu generador de sitios estáticos o aplicación de toma de notas. Saber qué variante soporta tu herramienta ahorra mucho rascarse la cabeza.

Extensiones de GitHub Flavored Markdown

GFM agrega cinco características sobre CommonMark que usarás constantemente en GitHub y cualquier herramienta que soporte el superconjunto GFM:

Tablas — columnas delimitadas por pipes con una fila separadora de guiones:

markdown
| Method  | Returns       | Mutates? |
|---------|---------------|----------|
| map()   | new array     | No       |
| filter()| new array     | No       |
| sort()  | same array    | Yes      |

Listas de tareas — casillas de verificación en issues y pull requests:

markdown
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release

Tachado — envuelve el texto en tildes dobles:

markdown
~~deprecated API~~ — use `newMethod()` instead

Bloques de código delimitados con sugerencias de lenguaje — el identificador de lenguaje después de los backticks de apertura activa el resaltado de sintaxis:

markdown
```python
def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

Autoenlaces — las URLs simples como https://example.com se hacen automáticamente clicables sin necesitar la sintaxis [texto](url). Esto es conveniente en comentarios de issues pero puede ser sorprendente si pegas una URL que no quieres enlazar.

Usa nuestra herramienta Formateador Markdown para limpiar el espaciado inconsistente, normalizar la indentación de listas y estandarizar los delimitadores de bloques de código — útil antes de hacer commit de docs a un repositorio.

Dónde usarás Markdown en la práctica

Markdown aparece en más lugares de los que la mayoría de los desarrolladores esperan cuando lo encuentran por primera vez:

  • GitHub y GitLab — archivos README, issues, descripciones de pull requests, wikis e incluso cuerpos de mensajes de commit. Cada repositorio que toques tendrá al menos un README.md.
  • Generadores de sitios estáticos — Jekyll, Hugo, Eleventy, Astro y Next.js todos aceptan archivos de contenido Markdown. Escribes entradas en archivos .md y el generador los convierte a páginas HTML en el momento de la compilación.
  • Herramientas de documentación — MkDocs, Docusaurus y GitBook están completamente construidos alrededor de fuentes Markdown. Las bibliotecas de código abierto usan casi universalmente una de estas.
  • Aplicaciones de toma de notas — Obsidian, Notion, Bear y Typora usan todos Markdown como formato nativo (con extensiones variables). Tus notas son archivos de texto plano portátiles, no una base de datos propietaria.
  • Plataformas CMS — Ghost usa Markdown de forma nativa. Contentful y Strapi soportan ambos campos Markdown. Las configuraciones CMS headless típicamente almacenan contenido de formato largo como cadenas Markdown.
  • Herramientas de IA — ChatGPT y Claude ambos producen Markdown por defecto. Los fragmentos de código, términos en negrita y listas con viñetas en las respuestas de IA son Markdown — la interfaz de chat los renderiza, pero el texto subyacente es **negrita** y ```python.

Markdown vs HTML — Cuándo usar cuál

Markdown se convierte a HTML, pero no puede expresar todo lo que HTML puede. No hay equivalente para <div class="card">, atributos data-*, o atributos aria-*. Para contenido de prosa simple — documentación, READMEs, entradas de blog, registros de cambios — Markdown es más rápido de escribir y mucho más legible en su forma cruda. Para componentes de interfaz de usuario complejos, diseños personalizados o anotaciones de accesibilidad que requieren atributos específicos, necesitas HTML.

La buena noticia: la mayoría de los procesadores Markdown permiten HTML crudo en línea. Puedes mezclar los dos. Si necesitas un <figure> con un <figcaption>, o un widget de divulgación <details>, simplemente escribe el HTML directamente en tu archivo .md. El procesador lo pasa sin modificaciones. Usa esta vía de escape con moderación — si más de un tercio de tu archivo es HTML crudo, quizás sea mejor escribir HTML directamente y usar nuestro Formateador HTML para mantenerlo limpio.

  • Usa Markdown para: documentación, READMEs, registros de cambios, entradas de blog, artículos de base de conocimiento, campos de descripción de API
  • Usa HTML para: diseño preciso, componentes personalizados, formularios, elementos que requieren atributos específicos
  • Mezcla ambos cuando: principalmente contenido de prosa con algunas excepciones estructurales (una tabla responsive, una inserción de video)

Conclusión

Markdown es engañosamente simple — parece solo un puñado de reglas de puntuación, pero impulsa la documentación de prácticamente todos los grandes proyectos de código abierto. Entender la sintaxis básica toma unos diez minutos. Entender las diferencias de variantes (CommonMark vs GFM vs lo que usa tu SSG) es lo que separa a los desarrolladores que ocasionalmente luchan con sus herramientas de documentación de los que no.

Las referencias autorizadas: CommonMark para la especificación estandarizada, GitHub Flavored Markdown para las extensiones de GitHub, y Markdown Guide para una referencia práctica de hoja de trucos. Para la escritura diaria, nuestra Vista Previa de Markdown te permite ver la salida renderizada instantáneamente, y el Formateador Markdown mantiene tus archivos fuente consistentes.

← All Markdown articles Browse all categories →