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

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.
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.
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.
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.

Nota

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 (#).

Jerarquía de encabezados en Markdown y sus etiquetas HTML correspondientes Збільшити

Jerarquía de encabezados en Markdown y sus etiquetas HTML correspondientes

Nivel de encabezado	Sintaxis Markdown	Salida HTML	Uso principal
Nivel 1	`# Encabezado`	`<h1>`	Título del documento (estrictamente UNO por página)
Nivel 2	`## Encabezado`	`<h2>`	Secciones temáticas principales y módulos del sistema
Nivel 3	`### Encabezado`	`<h3>`	Subsecciones, pasos operativos y desglose de herramientas
Nivel 4	`#### Encabezado`	`<h4>`	Subpuntos técnicos, especificaciones y notas secundarias
Nivel 5	`##### Encabezado`	`<h5>`	Anotaciones breves o notas a pie
Nivel 6	`###### Encabezado`	`<h6>`	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.

Comparación de sintaxis de encabezados válida e inválida con espacio obligatorio Збільшити

Comparación de sintaxis de encabezados válida e inválida con espacio obligatorio

Atención

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 <h1>; 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.

Sintaxis para dar formato de cursiva al texto en Markdown Збільшити

Sintaxis para dar formato de cursiva al texto en Markdown

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

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 ```bash npm run build

terminal

``` > [!NOTE] > Compruebe que las credenciales del archivo `.env` estén cargadas correctamente antes de compilar.

2. Verificar los archivos generados en la carpeta dist/.

terminal

--- ## 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:** `<https://github.com>` o `<seguridad@ejemplo.com>` - **Imagen incrustada:** `![Descripción accesible](/images/arquitectura.webp "Texto al pasar el cursor")` - **Imagen con enlace clickeable:** `[![Insignia](/images/badge.webp)](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: ![Codificación percent-encoding correcta para espacios y paréntesis en enlaces Markdown](/api/guides-media/automation/markdown-format-guide-for-ai/images/markdown-format-guide-for-ai-extra-03.webp) ```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})`; }

Importante

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 (\).

Caracteres especiales de Markdown que se pueden escapar con barra invertida Збільшити

Caracteres especiales de Markdown que se pueden escapar con 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 (<div>, <table>) 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.