{"canonical_url":"https://engineer.company/es/glossary/markdown/","content_markdown":"# Markdown\n\n## Qué es\n\nMarkdown permite escribir un documento como un archivo de texto corriente donde\nunas pocas convenciones indican al conversor qué HTML producir: asteriscos\nalrededor de una palabra para darle énfasis, una almohadilla ante un título, un\nguion ante cada elemento de una lista y corchetes seguidos de paréntesis para un\nenlace. El nombre abarca tanto la sintaxis como el programa con el que se\npublicó inicialmente. Los archivos suelen terminar en `.md` o `.markdown`, y\ntambién se llaman Markdown los dialectos que surgieron de él, como CommonMark y\nGitHub Flavored Markdown (GFM).\n\nJohn Gruber lo desarrolló en 2004 en colaboración con Aaron Swartz y escribió el\nprimer conversor en Perl; su última versión, Markdown 1.0.1, está fechada el 17\nde diciembre de 2004. Declaró que la prioridad era la legibilidad: un documento\nMarkdown debía poder publicarse tal cual, como texto sin formato, sin parecer\nmarcado con etiquetas o instrucciones de formato. Según escribió, la mayor influencia en la sintaxis fue la forma en que la gente ya daba\nformato a los correos de texto sin formato. Lo que la sintaxis no cubre se escribe como HTML entre el\ntexto, sin cambios de modo ni delimitadores: en su planteamiento, Markdown es un\nformato de escritura y HTML, el de publicación.\n\nUnas pocas líneas muestran casi todo:\n\n```markdown\nEl traslado llevó **una velada**, en tres pasos:\n\n- detener las escrituras\n- copiar los datos con `pg_dump`\n- dirigir la [aplicación](https://example.com/app/) al nuevo servidor\n```\n\nUn conversor lo transforma en un párrafo con un elemento `strong`, una lista de\ntres elementos, un fragmento de código en línea y un enlace; el original sigue\npareciendo una nota que alguien escribió.\n\n## Por qué importa\n\nEl archivo fuente es el documento, y el texto sin formato sobrevive a todas las\nherramientas que lo rodean. Un archivo Markdown se abre en cualquier editor, se\ncompara línea por línea en el control de versiones y se revisa con claridad en\nuna solicitud de cambios. Ningún proveedor puede retirar el formato; trasladar\nun conjunto de escritos entre sistemas consiste en copiar archivos.\n\nEl precio es la ambigüedad. El proyecto CommonMark lo expresa sin rodeos: la\ndescripción de Gruber no especifica la sintaxis de manera inequívoca, su script\ntenía errores y se actualizó por última vez en diciembre de 2004. En 2014 ya\nhabía decenas de implementaciones, cada una resolviendo las lagunas a su manera.\nSu ejemplo es un documento que se representa de una forma en una wiki de GitHub\ny de otra al convertirlo a DocBook con Pandoc. Como Markdown no rechaza ninguna\nentrada por error de sintaxis, la divergencia solo aparece cuando alguien mira\nel resultado. El proyecto remite a Babelmark 3, que ejecuta la misma entrada en\nmás de veinte implementaciones para comprobar si coinciden.\n\nCommonMark, iniciado en 2014, responde con una especificación escrita por John\nMacFarlane que vincula cada regla a ejemplos de entrada y al HTML exacto que\ndeben producir: 652 en la versión 0.31.2, fechada el 28 de enero de 2024. GitHub\ndefine su dialecto, GFM, como un superconjunto estricto de CommonMark: añade\ntablas, elementos de listas de tareas, tachado, enlaces automáticos ampliados y\nun filtro que neutraliza una lista breve de etiquetas HTML sin procesar.\nGoldmark, el conversor Markdown de Hugo, se ajusta a la especificación\nCommonMark y es compatible con GFM.\n\nMarkdown también tiene nombre en el protocolo. Desde marzo de 2016, RFC 7763\nregistra `text/markdown` para toda la familia de sintaxis, con un parámetro\n`charset` obligatorio y otro `variant` opcional que indica el dialecto del\narchivo.\n\n## Cómo se aplica en la práctica\n\nLas páginas escritas a mano de este sitio son Markdown, con la presentación\ndefinida mediante plantillas Go. La\n[página de créditos enumera ambas herramientas](/es/credits/) junto a Hugo, el\ngenerador de sitios estáticos. La misma página incluye markdownlint entre los\nanalizadores que mantienen correcto el código fuente, dentro de un control de\ncalidad obligatorio donde todo diagnóstico es un error.\n\nLa [página sobre cómo hacer un sitio legible para agentes de IA](/es/ai-ready/)\nutiliza el formato en el otro sentido: cada página de este sitio tiene una\nversión Markdown en la misma dirección, accesible añadiendo `index.md` o\nsolicitando `text/markdown`. La compilación lee todas esas versiones en busca de\nrestos de marcado y rechaza la publicación si alguna es incorrecta. Basta una\nsolicitud para obtener la versión de esa página:\n\n```sh\ncurl -sL https://engineer.company/ai-ready/index.md\n```\n\n[Unas 50.000 palabras de documentación de software](/es/portfolio/wrote-50000-words-of-software-documentation/)\nse escribieron en Markdown en GitHub, Craft y Confluence, muchas de ellas a\nmano. Cubrían la arquitectura, los procesos y los procedimientos que la gente\npreguntaba una y otra vez; se mantuvieron bajo control de versiones y fáciles de\nencontrar, y ayudaron a las nuevas incorporaciones a ponerse al día más deprisa.\n\n## Dónde surgen los problemas\n\n**La negrita se muestra como asteriscos.** El lector ve dos asteriscos a cada\nlado de una palabra que debía estar en negrita, y todas las comprobaciones\nsiguen aprobadas porque el HTML es válido y los enlaces funcionan. CommonMark\nsolo abre el énfasis con una secuencia de asteriscos que cumpla las condiciones\nde apertura por la izquierda; si va seguida de puntuación, como el corchete de\nun enlace, solo cuenta si delante hay un espacio en blanco o un signo de\npuntuación. Una letra delante mantiene los asteriscos como texto literal; ocurre\nlo mismo con lo que añada un motor de plantillas antes de analizar Markdown:\nHugo sustituye un shortcode por un marcador de letras y números. La plantilla de\nlas versiones Markdown de este sitio documenta que quitar el espacio entre un\nshortcode y la negrita contigua rompió la negrita en 60 viñetas de tres idiomas.\nConserve el espacio y compruebe la página representada, en lugar del original;\nel control de calidad obligatorio de este sitio lee el HTML compilado para\ndetectar Markdown que llegue al lector como signos de puntuación.\n\n**El mismo archivo se representa de dos maneras.** Una lista anidada se aplana\nen un sistema y se mantiene anidada en otro, o una almohadilla al principio de\nuna línea crea un título en un conversor y queda como texto en el siguiente.\nNada lo notifica porque Markdown no tiene errores de sintaxis que notificar. La\ncausa es una diferencia de dialecto: dos conversores resuelven de forma distinta\nuna de las lagunas originales. Indique el dialecto del proyecto, normalmente\nCommonMark o GFM, use un analizador que lo exija y pruebe las entradas dudosas\nen más de una implementación antes de depender de ellas.\n\n**La copia Markdown de una página contiene HTML.** El lector de la versión de\ntexto encuentra elementos `svg` sin procesar o un teléfono que comienza con una\nreferencia numérica de carácter donde debería estar el signo más. Un componente\nque produce HTML para la página web produce el mismo HTML en los demás formatos\nsi no se le indica lo contrario: Hugo busca la plantilla de un shortcode por\nformato de salida y, si no existe, recurre a la de HTML. Las plantillas de\nshortcodes de este sitio documentan ambos casos: 49 elementos `svg` sin procesar\nen la copia Markdown de créditos y el teléfono de contacto escapado para HTML.\nAhora todo shortcode que escriba marcado dispone de su propia plantilla para la\nsalida Markdown. El control de calidad obligatorio también comprueba que esas\nversiones no contengan HTML sin procesar ni entidades HTML, excluyendo el código\nde la comprobación.\n\n**El HTML sin procesar desaparece de la página.** Un bloque HTML escrito en\nMarkdown falta en la página compilada, aunque el original parece correcto. La\nsintaxis de Gruber permite HTML en cualquier parte del texto, pero un conversor\npuede rechazarlo: el ajuste `unsafe` de Goldmark en Hugo está desactivado de\nforma predeterminada, por lo que no se representa el HTML mezclado con Markdown. GFM escapa\nuna lista breve de etiquetas, como `script` e `iframe`, para que se impriman\ncomo texto. Use lo que ofrezca el generador, como un shortcode o un hook de\nrepresentación de Hugo, o active el ajuste deliberadamente y acepte lo que deja\npasar.\n\n**El analizador aprueba lo que se le indicó ignorar.** Un archivo Markdown con\nuna estructura rota supera la revisión porque markdownlint no informa de nada.\nLas reglas que lo habrían detectado estaban desactivadas en su configuración,\nsin explicación. Las reglas de desarrollo de este sitio documentan que\nmarkdownlint estuvo configurado en un archivo JSON con seis reglas desactivadas\ny sin comentarios; al evaluar esas seis, dos estaban ocultando defectos reales.\nEscriba la razón junto a cada regla desactivada, en un formato que admita\ncomentarios, para que la siguiente persona pueda cuestionarla.\n\n## Lecturas adicionales\n\n- [Especificación CommonMark](https://spec.commonmark.org/) — cada regla vinculada\n  a ejemplos de entrada y al HTML que debe producir.\n- [CommonMark](https://commonmark.org/) — por qué hizo falta una especificación,\n  cómo divergieron las implementaciones y quién la mantiene.\n- [Markdown, de John Gruber](https://daringfireball.net/projects/markdown/) — la\n  descripción original, el objetivo de diseño y el script Perl.\n- [Markdown: sintaxis](https://daringfireball.net/projects/markdown/syntax) — la\n  explicación de la sintaxis del propio Gruber, incluida la regla del HTML en\n  línea.\n- [Especificación GitHub Flavored Markdown](https://github.github.com/gfm/) — el\n  dialecto de GitHub como superconjunto de CommonMark, con cada extensión\n  identificada.\n- [RFC 7763: el tipo de medio text/markdown](https://www.rfc-editor.org/rfc/rfc7763)\n  — el tipo de medio, su `charset` obligatorio y su parámetro `variant`.\n\n\u003chttps://engineer.company/es/glossary/markdown/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Markdown permite escribir documentos como texto legible. Sus dialectos, la conversión a HTML y las plantillas explican diferencias y fallos de formato.","formats":{"gemtext":"https://engineer.company/es/glossary/markdown/index.gmi","gopher":"https://engineer.company/es/glossary/markdown/gophermap","html":"https://engineer.company/es/glossary/markdown/","json":"https://engineer.company/es/glossary/markdown/index.json","markdown":"https://engineer.company/es/glossary/markdown/index.md","pdf":"https://engineer.company/es/glossary/markdown/index.pdf"},"kind":"page","language":"es","title":"¿Qué es Markdown?","url":"https://engineer.company/es/glossary/markdown/","version":1}