Probar sintaxis

Referencia de sintaxis

¿Qué es la sintaxis de Markdown?

Markdown es un lenguaje de formato de texto plano ligero creado por John Gruber en 2004. Utiliza símbolos y caracteres simples para marcar texto, facilitando la escritura de contenido que se convierte a HTML sin verse desordenado en su forma sin procesar. Markdown se ha convertido en el estándar para documentación, archivos README, blogs y cualquier contenido que necesite un formato simple y legible. A diferencia de HTML, que requiere etiquetas de apertura y cierre, Markdown utiliza marcadores intuitivos como asteriscos para énfasis y guiones para listas, haciéndolo accesible para cualquiera que pueda escribir texto plano.

CommonMark es la especificación de Markdown más ampliamente aceptada, definiendo cómo los analizadores deben interpretar la sintaxis. Surgió de esfuerzos comunitarios para estandarizar el comportamiento de Markdown en diferentes plataformas, ya que la sintaxis original dejó muchos casos límite sin definir. Al aprender sintaxis compatible con CommonMark, tu contenido se renderizará consistentemente en GitHub, GitLab, Discord, Slack, Reddit, Stack Overflow y docenas de otras plataformas. La especificación original de Markdown de John Gruber sigue siendo fundamental, aunque extensiones como GitHub Flavored Markdown añaden características como listas de tareas, texto tachado y tablas.

Markdown moderno viene en varios sabores adaptados a plataformas específicas. GitHub Flavored Markdown (GFM) añade tablas, casillas de verificación y autoenlaces. Markdown de GitLab soporta extensiones similares más diagramas. Aprender sintaxis central de CommonMark te da una base portátil que funciona en todas partes, mientras que extensiones específicas de plataforma te permiten aprovechar características específicas de herramientas cuando sea necesario.

Cómo usar la guía de sintaxis de Markdown

Sigue estos pasos para aprender y probar la sintaxis de Markdown. Cada paso utiliza los paneles reales en esta página.

Pegar, subir o cargar ejemplo

Pega Markdown en el panel izquierdo Probar sintaxis, o haz clic en Subir para cargar un archivo .md. Haz clic en Ejemplo para ver documentación de API de suscriptor de ejemplo. El panel derecho Referencia de sintaxis muestra patrones de CommonMark y GFM.

Practicar y referenciar

Usa la referencia para encabezados, énfasis, listas, enlaces, tablas, bloques de código. Copia ejemplos en el panel izquierdo para probarlos. Cubre CommonMark más extensiones GitHub Flavored Markdown.

Copiar o descargar

Haz clic en Copiar o Descargar para guardar la referencia. Usa Limpiar para empezar de nuevo. Todo el procesamiento se ejecuta en tu navegador.

Cuándo realmente lo usarías

Escribir documentación

La documentación técnica, guías de referencia de API y documentación de software están casi universalmente escritas en Markdown. Documentos de Python, guías de Node.js y la mayoría de proyectos de código abierto usan Markdown para sus sitios de documentación. Una referencia de sintaxis te mantiene productivo cuando escribes documentación compleja con múltiples niveles de encabezado, ejemplos de código y referencias cruzadas.

Archivos README y de proyecto

Cada proyecto de GitHub tiene un archivo README.md que describe el proyecto, uso, instalación y directrices de contribución. Estos archivos están escritos completamente en Markdown y son a menudo lo primero que ven los usuarios. Las tablas para comparaciones de características, bloques de código para ejemplos y listas formateadas son estándar en archivos README.

Creación y publicación de contenido

Las plataformas de blog como Jekyll, Hugo y Ghost aceptan Markdown para contenido. Las plataformas de estilo Medium, plataformas fantasma y generadores de sitios estáticos usan Markdown como su formato de entrada principal. Conocer la sintaxis te ayuda a escribir más rápido y mantener un formato consistente en todo tu contenido publicado.

Comunicación colaborativa

Slack, Discord, problemas de GitHub, comentarios de pull request y publicaciones en foros todos soportan formato de Markdown. Cuando estés revisando código, reportando errores o colaborando en chat, Markdown te permite formatear tu mensaje claramente sin interrumpir el flujo de conversación. El conocimiento rápido de sintaxis te ahorra tiempo en estos flujos de trabajo diarios.

Preguntas frecuentes

¿Puedo usar HTML dentro de Markdown?

Sí, Markdown te permite mezclar HTML sin procesar. Si Markdown no admite algo que necesites, puedes escribir HTML directamente y pasará a la salida. Sin embargo, esto reduce la portabilidad y legibilidad de tu fuente. Según la especificación de CommonMark, los bloques HTML e HTML en línea se reconocen y pasan sin cambios. Usa esto con moderación—generalmente, la sintaxis de Markdown es suficiente.

¿Cuál es la diferencia entre asteriscos y guiones bajos para énfasis?

Funcionalmente, son idénticos en CommonMark—*texto* y _texto_ producen ambos cursiva, **texto** y __texto__ producen ambos negrita. La elección es estilística. Muchos equipos prefieren asteriscos para consistencia y porque son más fáciles de escribir en la mayoría de teclados. Los guiones bajos pueden causar problemas en palabras con patrones similares a énfasis (por ejemplo, "nombre_archivo_aquí"), razón por la cual los asteriscos a menudo se recomiendan.

¿Cómo funcionan los saltos de línea en Markdown?

Esta es una fuente común de confusión. Un salto de línea único en tu fuente se trata como un espacio—la línea se fusiona con la siguiente. Para crear un salto de línea real (a <br> en HTML), agrega dos espacios al final de la línea antes de presionar Enter, o usa una barra invertida antes del salto de línea. Para saltos de párrafo, usa una línea en blanco (dos saltos de línea consecutivos). La especificación de CommonMark explica esto en detalle con ejemplos.

¿Las tablas se admiten en todas partes en Markdown?

No. Las tablas son parte de GitHub Flavored Markdown y otras extensiones, pero no están en la especificación de CommonMark. La mayoría de las plataformas modernas (GitHub, GitLab, Discord) las soportan, pero algunos analizadores ignorarán la sintaxis de tubería. Si necesitas tablas que funcionen en todas partes, verifica que tu plataforma de destino soporte GFM o considera usar un enfoque diferente.

¿Cómo escopo caracteres especiales?

Usa una barra invertida () antes de caracteres que tengan significado especial en Markdown: la barra invertida en sí (), backtick (`), asterisco (*), guion bajo (_), llaves ({}), corchetes cuadrados ([]), paréntesis (()), almohadilla (#), signo más (+), signo menos (-), punto (.) y signo de exclamación (!). Por ejemplo, *no cursiva* renderiza los asteriscos literalmente en lugar de crear cursiva. Según los escapes de barra invertida de CommonMark, solo estos caracteres específicos necesitan escaping.

¿Cuál es la mejor manera de formatear código en Markdown?

Para código en línea, usa backticks únicos: `código aquí`. Para bloques de código, usa triple backticks con una etiqueta de lenguaje opcional (```javascript) para resaltado de sintaxis. Evita sangrar código como un bloque de código—los bloques de código cerrados son más claros y portátiles. Si necesitas mostrar código que contiene backticks, usa más backticks para delimitar: ` ``backticks`` `. Ve intervalos de código y bloques de código cerrados en la especificación de CommonMark.

Guía de sintaxis de Markdown