# Formato Markdown: Guía completa para flujos de trabajo con IA y automatización
> Guía práctica y exhaustiva de sintaxis Markdown para desarrollo con IA: estándares CommonMark, jerarquía de encabezados, tablas GFM, escape de caracteres, system prompts y reglas para CLAUDE.md.
## 1. Qué es Markdown: filosofía, CommonMark y por qué es el lenguaje nativo de la IA
**Markdown** es un lenguaje de marcado ligero creado por John Gruber en 2004 con un objetivo claro: permitir escribir documentos estructurados legibles en su formato original de texto plano y fácilmente convertibles a HTML válido. Hoy en día, el estándar de la industria se rige por la especificación **CommonMark** y su extensión **GitHub Flavored Markdown (GFM)**.
En la interacción con modelos de lenguaje e inteligencia artificial (ChatGPT, Claude Code, Gemini, modelos locales en Ollama), Markdown se ha consolidado como el estándar indiscutible de intercambio de información.
```mermaid
flowchart LR
A["Texto Markdown plano
(Mínimo consumo de tokens, UTF-8 puro)"] --> B["LLM / Agente de IA
(Procesamiento semántico directo)"]
B --> C{"Interpretación y renderizado"}
C --> D["HTML / Interfaz Web
(Encabezados, listas, tablas)"]
C --> E["Documentos DOCX / PDF
(Conversión mediante Pandoc)"]
C --> F["Contexto de Sistema
(CLAUDE.md, .cursorrules)"]
```
### Por qué los modelos de lenguaje operan en Markdown
1. **Eficiencia extrema en el consumo de tokens:** A diferencia de XML o HTML, donde cada elemento requiere etiquetas de cierre explícitas (`Texto
`), Markdown utiliza caracteres individuales (`#`, `-`, `*`) o saltos de línea simples.
2. **Jerarquía semántica determinista:** Los símbolos estructurales facilitan a los modelos la comprensión inmediata de prioridades y relaciones sin sobrecargar la ventana de contexto.
3. **Optimización para streaming de respuestas:** La generación token por token sin necesidad de balancear etiquetas complejas permite a las interfaces web renderizar tipografía enriquecida en tiempo real.
4. **Control de versiones nativo en Git:** Al ser texto sin formato binario, el historial de documentación y los prompts se comparan línea por línea mediante `git diff`.
> [!NOTE]
> La sintaxis de Markdown se divide en dos categorías: **elementos de bloque** (encabezados, párrafos, listas, citas, bloques de código y tablas) y **elementos en línea** (negrita, cursiva, enlaces y código en línea). Los elementos de bloque deben separarse obligatoriamente mediante líneas en blanco.
---
## 2. Jerarquía de encabezados y estructura navegable de documentos
Los encabezados estructuran el contenido del documento y determinan la tabla de contenidos (TOC) generada de forma automática. En Markdown, los niveles de encabezado se definen anteponiendo entre uno y seis caracteres almohadilla (`#`).
| Nivel de encabezado | Sintaxis Markdown | Salida HTML | Uso principal |
| :--- | :--- | :--- | :--- |
| **Nivel 1** | `# Encabezado` | `` | Título del documento (estrictamente UNO por página) |
| **Nivel 2** | `## Encabezado` | `` | Secciones temáticas principales y módulos del sistema |
| **Nivel 3** | `### Encabezado` | `` | Subsecciones, pasos operativos y desglose de herramientas |
| **Nivel 4** | `#### Encabezado` | `` | Subpuntos técnicos, especificaciones y notas secundarias |
| **Nivel 5** | `##### Encabezado` | `` | Anotaciones breves o notas a pie |
| **Nivel 6** | `###### Encabezado` | `` | Micro-etiquetas de parámetros |
### El espacio obligatorio tras los símbolos de almohadilla
Según la especificación CommonMark, es **obligatorio** incluir un espacio en blanco entre los caracteres `#` y el texto del encabezado. Omitir este espacio provoca que el analizador interprete la línea como texto plano o como un hashtag de redes sociales.
> [!WARNING]
> Nunca utilice encabezados `#` de primer nivel dentro del cuerpo del texto si el encabezado de metadatos (frontmatter) ya define el título de la página. El motor de renderizado asigna automáticamente dicho título a la etiqueta ``; la presencia de múltiples etiquetas H1 perjudica el posicionamiento SEO y la accesibilidad.
---
## 3. Estilos de texto en línea: negrita, cursiva, tachado y reglas de énfasis
El marcado en línea permite dirigir la atención del lector y del modelo hacia conceptos esenciales, comandos o parámetros clave.
| Estilo visual | Sintaxis Markdown | Resultado renderizado |
| :--- | :--- | :--- |
| **Negrita** | `**término crítico**` o `__término__` | **término crítico** |
| **Cursiva** | `*énfasis*` o `_énfasis_` | *énfasis* |
| **Negrita y Cursiva** | `***directiva prioritaria***` | ***directiva prioritaria*** |
| **Tachado** | `~~parámetro obsoleto~~` | ~~parámetro obsoleto~~ |
| **Código en línea** | `` `apiKey` `` | `apiKey` |
### Pautas tipográficas esenciales
- **Énfasis dentro de una palabra:** Para aplicar estilo a fragmentos internos de una palabra, utilice siempre asteriscos (`des*bloque*o`). Los guiones bajos dentro de palabras suelen ser ignorados por los motores de renderizado para evitar alterar identificadores de código en `snake_case` (`user_auth_token`).
- **Salto de línea suave:** Para insertar un salto `
` sin iniciar un nuevo párrafo, agregue dos espacios al final de la línea o escriba directamente la etiqueta `
`.
- **Comentarios invisibles:** Para incluir notas de trabajo que no aparezcan en la vista final, emplee la sintaxis de comentarios HTML: ``.
---
## 4. Listas y jerarquías anidadas: numeradas, con viñetas y casillas de verificación
Las listas permiten estructurar instrucciones paso a paso, requisitos de software y listas de tareas interactivas.
### Listas ordenadas, desordenadas y casillas de verificación
:::tabs
@tab Listas desordenadas
```markdown
- Fase de análisis inicial
- Revisión de arquitectura
- Subtarea anidada (sangría de 2 o 4 espacios)
- Validación de requisitos
- Despliegue en producción
```
@tab Listas ordenadas
```markdown
1. Clonar el repositorio remoto
2. Instalar dependencias con npm
3. Iniciar el servidor de desarrollo local
```
@tab Casillas de verificación (Tasks)
```markdown
- [x] Desplegar base de datos gestionada
- [x] Configurar variables de entorno
- [ ] Ejecutar pruebas de integración de extremo a extremo
```
:::
### Anidamiento de bloques complejos dentro de listas
Para insertar párrafos, citas o bloques de código dentro de un elemento de lista sin reiniciar la numeración, aplique una sangría de exactamente 4 espacios a cada línea dependiente:
```markdown
1. Iniciar el proceso de compilación:
```bash
npm run build
```
> [!NOTE]
> Compruebe que las credenciales del archivo `.env` estén cargadas correctamente antes de compilar.
2. Verificar los archivos generados en la carpeta `dist/`.
```
---
## 5. Enlaces, imágenes y codificación percent-encoding en URLs
La sintaxis para hipervínculos y elementos multimedia sigue un patrón predecible de corchetes y paréntesis.
### Estructuras básicas de enlaces y elementos multimedia
- **Enlace en línea estándar:** `[Documentación de Anthropic](https://docs.anthropic.com)`
- **Enlace con texto emergente (Title):** `[Claude Code](https://claude.ai "Plataforma oficial")`
- **Enlaces automáticos:** `` o ``
- **Imagen incrustada:** ``
- **Imagen con enlace clickeable:** `[](https://ejemplo.com)`
### Codificación obligatoria percent-encoding en URLs
Cuando las direcciones URL contienen espacios en blanco, paréntesis o caracteres especiales, la cadena sin codificar puede interrumpir el análisis sintáctico del enlace. Utilice siempre codificación percent-encoding:
```markdown
[Referencia técnica](https://es.wikipedia.org/wiki/Computadora_%28desambiguaci%C3%B3n%29)
[Referencia técnica](https://es.wikipedia.org/wiki/Computadora_(desambiguación))
```
---
## 6. Código en línea, bloques de código cercados y resaltado de sintaxis
Los fragmentos de código y las instrucciones para consolas de comandos requieren tipografía monoespaciada y aislamiento de los motores de marcado.
### Código en línea frente a bloques cercados
- **Código en línea:** Delimitado por acentos graves simples: `Ejecute git status para inspeccionar el árbol de trabajo.`
- **Escape de acentos graves en línea:** Delimitado por dobles acentos graves: `` `npm test` ``.
- **Bloques cercados:** Triple acento grave con el identificador explícito del lenguaje para resaltado de sintaxis.
```typescript
interface PerfilUsuario {
id: string;
username: string;
isActive: boolean;
}
export function formatUser(usuario: PerfilUsuario): string {
return `@${usuario.username} (ID: ${usuario.id})`;
}
```
> [!IMPORTANT]
> **Aislamiento obligatorio de prompts:** Cualquier plantilla de prompt, archivo de reglas (`.cursorrules`, `CLAUDE.md`) o fragmento de configuración que contenga encabezados (`#`, `##`) **debe** estar encerrado en un bloque de código cercado con un identificador de lenguaje (como markdown o text). Dejar encabezados sin cercar provoca que los analizadores filtren títulos internos del prompt en la tabla de contenidos global del documento.
---
## 7. Citas, bloques de alerta de GitHub y divisores temáticos horizontales
Las citas comienzan con el carácter `>` y se utilizan para destacar ideas principales, referencias y directrices esenciales.
### Citas simples y anidadas
```markdown
> Observación conceptual de primer nivel.
>
> > Aclaración contextual anidada dentro de la cita principal.
```
### Bloques de alerta de GitHub (Callouts)
Las plataformas modernas de documentación permiten renderizar tarjetas visuales de alerta mediante etiquetas de metadatos estandarizadas:
```markdown
> [!NOTE]
> Información de referencia complementaria o contexto del sistema.
> [!TIP]
> Sugerencias prácticas de optimización y recomendaciones de flujo de trabajo.
> [!IMPORTANT]
> Requisitos arquitectónicos fundamentales que no deben pasarse por alto.
> [!WARNING]
> Avisos críticos sobre posibles riesgos de datos o funciones en desuso.
```
### Divisores horizontales
Para insertar una línea de separación temática, escriba tres o más guiones (`---`), asteriscos (`***`) o guiones bajos (`___`) en una línea independiente:
```markdown
Contenido previo de la sección actual.
---
Contenido posterior tras el cambio temático.
```
---
## 8. Escape de caracteres especiales y uso seguro de HTML en línea
Cuando necesite representar los símbolos reservados de Markdown como caracteres literales, anteponga una barra invertida (`\`).
### Tabla de escape para caracteres reservados
| Símbolo | Nombre del carácter | Sintaxis escapada | Carácter literal resultante |
| :--- | :--- | :--- | :--- |
| `\` | Barra invertida | `\\` | \ |
| `` ` `` | Acento grave | `` \` `` | ` |
| `*` | Asterisco | `\*sin cursiva\*` | \*sin cursiva\* |
| `_` | Guion bajo | `\_sin negrita\_` | \_sin negrita\_ |
| `#` | Almohadilla | `\# No es encabezado` | \# No es encabezado |
| `[` `]` | Corchetes | `\[No es enlace\]` | \[No es enlace\] |
| `!` | Signo de exclamación | `\!No es imagen` | \!No es imagen |
### Reglas para el uso seguro de HTML
Aunque los motores de Markdown admiten etiquetas HTML directas, mantenga presentes estas pautas:
- Emplee `
` para saltos de línea deliberados en celdas de tablas.
- Utilice `` para texto subrayado.
- Las etiquetas HTML de bloque (``, `
`) deben separarse con líneas en blanco; el procesamiento sintáctico de Markdown queda inactivo dentro de bloques HTML puros.
---
## 9. Tablas GitHub Flavored Markdown (GFM) y diagramas Mermaid
Las tablas permiten organizar matrices de datos y comparaciones técnicas con claridad.
### Sintaxis y alineación en tablas GFM
```markdown
| Parámetro | Descripción | Valor por defecto | Estado |
| :--- | :--- | :---: | ---: |
| `apiKey` | Clave de autenticación | `null` | Obligatorio |
| `timeout` | Tiempo de espera en ms | `5000` | Opcional |
| `retries` | Intentos de reintento | `3` | Recomendado |
```
- `:---` — Columna alineada a la izquierda.
- `:---:` — Columna centrada.
- `---:` — Columna alineada a la derecha (ideal para métricas numéricas o valores monetarios).
### Diagramas de arquitectura dinámicos con Mermaid
Sustituya capturas de pantalla pesadas por diagramas vectoriales interactivos mantenibles directamente en texto plano:
```mermaid
sequenceDiagram
autonumber
actor Usuario as Desarrollador
participant IA as Claude Code / GPT-4o
participant FS as Sistema de Archivos
Usuario->>IA: Solicitar documentación de arquitectura
IA->>IA: Estructurar AST en memoria (CommonMark)
IA->>FS: Generar archivo README.md validado
FS-->>Usuario: Documentación lista para producción
```
---
## 10. Markdown en agentes de IA: CLAUDE.md, System Prompts y lista de verificación
En los flujos de trabajo con agentes inteligentes (Claude Code, Cursor, Windsurf, Devin), Markdown funciona como el lenguaje de control del sistema.
### Archivos de reglas del proyecto (CLAUDE.md / .cursorrules)
Los agentes autónomos leen `CLAUDE.md` antes de ejecutar tareas. Estructurar este archivo con sintaxis Markdown limpia asegura que el modelo interprete las reglas sin desviaciones:
```markdown
Estándares de Arquitectura del Proyecto
======================================
1. Comandos de Compilación y Pruebas:
- Compilación: npm run build
- Pruebas unitarias: npm test
- Linter: npm run lint
2. Invariantes de Arquitectura:
- Utilizar Server Components por defecto en la carpeta app de Next.js.
- Guardar interfaces TypeScript compartidas en src/types/.
- Prohibido el uso del tipo "any" en código TypeScript de producción.
```
### Master Prompt para generar Markdown estructurado
```markdown
Actúa como redactor técnico principal y arquitecto de documentación. Genera documentación técnica integral conforme a las especificaciones CommonMark / GFM.
Tema: [Indique el tema, p. ej. Arquitectura de Microservicios de Autenticación]
Reglas de formato obligatorias:
1. Las secciones principales deben numerarse secuencialmente desde ## 1. hasta ## N. (Cero etiquetas # en el cuerpo).
2. Deje siempre un espacio en blanco después de cada almohadilla (ej. "## 1. Introducción").
3. Encierre todo el código en bloques de tres acentos graves con el identificador del lenguaje (typescript, bash, json, mermaid).
4. Presente tablas comparativas con formato GFM válido y alineación de columnas.
5. Destaque avisos operativos con bloques de alerta de GitHub (> [!NOTE], > [!WARNING]).
6. Codifique con percent-encoding cualquier URL con espacios o paréntesis (%20, %28, %29).
Genera directamente el documento Markdown sin saludos ni comentarios introductorios.
```
### Lista de verificación de calidad previa a la publicación
- [ ] El cuerpo del documento no contiene encabezados `#` (el H1 proviene del frontmatter).
- [ ] Las secciones de nivel 2 están numeradas secuencialmente (`## 1.`, `## 2.`).
- [ ] Todos los encabezados cuentan con un espacio tras los símbolos `#`.
- [ ] Los prompts y configuraciones están aislados en bloques de código cercados.
- [ ] Los enlaces con caracteres especiales usan codificación percent-encoding.
- [ ] Las tablas cumplen con el formato GFM sin delimitadores faltantes.
- [ ] Todas las imágenes incluyen texto descriptivo en su atributo alt.