Previsualizador gratuito de Markdown en línea

Chuleta de Markdown

Sobre Markdown

Markdown fue creado por John Gruber, el escritor detrás del blog Daring Fireball, con un retorno de diseño sustancial de Aaron Swartz. La primera versión pública, 1.0, fue anunciada en el sitio de Gruber el 9 de marzo de 2004; la versión 1.0.1, la versión de referencia canónica, siguió el 17 de diciembre de 2004 y sigue siendo la versión enlazada desde daringfireball.net/projects/markdown. Markdown es dos cosas a la vez: una sintaxis de formato en texto plano y el script Perl original que convierte esa sintaxis en HTML. El objetivo declarado de Gruber era que el texto fuente fuera legible tal cual, un documento Markdown abierto en un editor de texto plano debería parecerse a un correo cuidadosamente formateado, no a una sopa de etiquetas. Esa restricción de legibilidad es la línea filosófica que separa Markdown de los formatos basados en XML y de marcados más pesados como LaTeX, y es la razón por la que cada extensión posterior ha tenido que justificarse en términos de cuán mal interrumpe la fuente.

Gruber acredita extensamente a Swartz en los agradecimientos de Markdown: «Aaron Swartz merece una enorme cantidad de crédito por sus comentarios sobre el diseño de la sintaxis de formato de Markdown.» Swartz había escrito antes un marcado ligero relacionado llamado atx (2002), que contribuyó el ahora familiar estilo de encabezado # y ##: a veces todavía llamado «atx-style headings» en las specs de parsers. La participación de Swartz es una pieza de su legado más amplio: co-construyó RSS 1.0 siendo adolescente, fue copropietario de Reddit hasta 2007, y siguió influyendo en los estándares del web abierto hasta su muerte en 2013. Una curiosidad que vale la pena entender bien: la extensión de archivo .md es ahora casi universal, pero la herramienta original de Gruber usaba .text: la migración a .md fue una convención comunitaria que se afianzó una vez que Markdown salió del nicho del blogging.

Por qué Markdown ganó la web

Un lenguaje de marcado gana al ser adoptado por las plataformas que publican la mayor parte del texto del mundo. En una ventana ajustada de cinco años, Markdown fue adoptado por las plataformas que llegaron a dominar la discusión larga, la colaboración de código y la documentación para desarrolladores. Stack Overflow se lanzó el 15 de septiembre de 2008 con Markdown como sintaxis de formato para preguntas, respuestas y comentarios, usando un editor llamado WMD (Wysiwym Markdown) por John Fraser de AttackLab; el equipo de Stack Overflow lo reescribió después como el editor open-source PageDown mantenido en github.com/StackExchange/pagedown. Reddit, fundado por Steve Huffman y Alexis Ohanian en 2005 con Aaron Swartz uniéndose poco después, llevó Markdown a los comentarios poco después del lanzamiento y trasladó la sintaxis a un público mucho más amplio, no desarrollador. GitHub se lanzó en 2008 y en menos de un año estaba renderizando Markdown en README.md y comentarios de issues; en 2009 comenzó a documentar y enviar su propio dialecto, GitHub Flavored Markdown. Discord, lanzado en mayo de 2015, adoptó una sintaxis de chat con sabor Markdown para negrita, cursiva, tachado, código inline, fences de código y blockquotes, lo que la mayoría de no-desarrolladores menores de 25 años ahora consideran «poner asteriscos alrededor de algo». La habilidad se acumula: un escritor que aprende Markdown una vez puede escribir publicaciones de blog en Jekyll/Hugo/Eleventy, documentación en MkDocs/Docusaurus/Read the Docs, presentaciones en Marp y Reveal.js, notas en Obsidian/Bear/Logseq/Notion, chat en Slack y Discord, y documentación de código fuente en esencialmente todo proyecto open-source moderno.

CommonMark, arreglar la sub-especificación

La descripción original de la sintaxis de Gruber de 2004 fue famosamente informal, un documento en prosa con ejemplos, no una gramática. Dejó docenas de casos límite sin especificar («¿cómo interactúa el énfasis con los guiones bajos en medio de una palabra?»; «¿una lista dentro de un blockquote cierra el blockquote?»; «¿qué cuenta como lista apretada vs lista suelta?»), y Gruber nunca publicó un parser de referencia más allá de su script Perl, cuyo comportamiento era idiosincrásico de maneras que otros implementadores tenían que copiar o anular. El resultado a principios de la década de 2010 fue que GitHub, Reddit, Stack Overflow, Pandoc y el parser C Discount renderizaban la misma fuente Markdown ligeramente diferente, y la misma entrada podía romperse entre plataformas.

En 2012, el cofundador de Stack Overflow Jeff Atwood (para entonces dirigiendo Discourse) y el autor de Pandoc John MacFarlane comenzaron un esfuerzo para escribir una especificación real, testeable. Se les unieron David Greenspan (Meteor), Vicent Marti (GitHub), Neil Williams (Reddit) y Benjamin Dumke-von der Ehe (Stack Exchange). El proyecto se lanzó públicamente en septiembre de 2014 como «Standard Markdown»; en pocos días Gruber objetó al nombre en correo privado, Atwood escribió una publicación pública explicando el cambio, y el proyecto fue renombrado «CommonMark». La primera release numerada llegó el 25 de octubre de 2014. La versión actualmente publicada es CommonMark 0.31.2, lanzada el 28 de enero de 2024, se prometió una «1.0» para 2019 y no ha llegado porque un pequeño número de casos límite patológicos (notablemente alrededor del parsing de énfasis e incrustación HTML) no han producido resoluciones unánimes. En la práctica 0.31.2 se trata como estable para producción. La spec CommonMark es inusual en que ella misma es un documento CommonMark, con más de 600 casos de prueba ejecutables en línea; un parser reclama conformidad pasando esas pruebas.

GitHub Flavored Markdown, cinco extensiones encima

La especificación formal GFM, publicada en 2017 y más recientemente versionada como 0.29-gfm el 6 de abril de 2019, define cinco extensiones encima de CommonMark: tablas (bloques delimitados por barras verticales con una fila de delimitador usando guiones y : para alineamiento por columna); elementos de lista de tareas (entradas de lista que comienzan con [ ] para no marcadas o [x] para marcadas, renderizadas como casillas HTML deshabilitadas, GitHub adicionalmente permite a usuarios autenticados alternarlas haciendo clic, lo cual es una capa UX encima de la spec, no parte de la spec en sí); tachado (envolver texto en ~~ produce <del>: CommonMark en sí no lo especifica); extensión autolinks (las URL desnudas y direcciones de email en texto corriente se auto-enlazan, donde CommonMark solo lo hace para autolinks explícitos con corchetes angulares); y HTML crudo prohibido (una restricción de seguridad que elimina <script>, <iframe>, <style>, <title>, <plaintext>, <textarea>, <xmp>, <noembed>, <noframes> y un puñado de otras etiquetas peligrosas). Una sexta característica comúnmente atribuida a GFM pero que vale la pena tratar con cuidado son los bloques de código con fences con identificadores de lenguaje: los bloques de código con fences son parte del propio CommonMark; la pista de lenguaje después del fence de apertura también es CommonMark; el resaltado de sintaxis que GitHub aplica entonces basado en esa pista es comportamiento de renderizado de GitHub, no la spec. El renderizador de GitHub también ejecuta post-procesamiento adicional, sanitización HTML vía su gem interno html-pipeline, expansión de shortcodes emoji (:smile:), autolinking @user y #issue: ninguno de los cuales está en GFM en sí.

Los parsers principales

marked.js fue creado por Christopher Jeffrey, con el copyright original fechado en 2011, y ha sido mantenido por la organización GitHub markedjs desde 2018. Es un diseño de una sola pasada, lexer-luego-parser, que prioriza la velocidad bruta; los docs lo posicionan explícitamente como un «low-level compiler for parsing markdown without caching or blocking». Es el parser que este previewer usa actualmente para el render en vivo. Marked es pequeño, rápido, extensible mediante hooks de tokens, y uno de los proyectos markdown más estrellados en GitHub (~36k estrellas).

markdown-it fue lanzado en 2014 por Vitaly Puzrin y Alex Kocharin. Los dos habían contribuido antes casi todo el código a un parser llamado Remarkable; cuando disputas de liderazgo bloquearon el progreso, reorganizaron la misma autoría en torno a markdown-it. El proyecto anuncia 100% conformidad CommonMark con interruptores GFM opcionales para tablas y tachado, más un ecosistema de plugins agresivo (markdown-it-footnote, markdown-it-emoji, markdown-it-attrs, markdown-it-anchor, markdown-it-task-lists y varios cientos más). Es el parser usado por la preview Markdown integrada de VS Code, la UI web de GitLab, y una larga lista de generadores de sitios estáticos incluyendo Eleventy.

remark / unified.js no es un parser único sino un framework de transformación de árboles. El colectivo unified, comenzado alrededor de 2014, define una spec de árbol sintáctico abstracto llamada mdast (Markdown Abstract Syntax Tree); remark parsea Markdown a mdast, los plugins manipulan el árbol, y remark-rehype convierte mdast a hast (el AST HTML) para emisión. El modelo es más lento que marked pero vastamente más componible. Usuarios notables incluyen Prettier (que formatea Markdown con remark), Gatsby, MDN, el pipeline de documentación de Node.js, y el linter de lenguaje inclusivo alex. El colectivo unified lista 312 proyectos y aproximadamente 6.300 millones de descargas npm mensuales en todos sus paquetes.

MDX, primero comprometido a finales de 2017 por John Otander y otros conectados a la compañía de herramientas de diseño Compositor, fue anunciado públicamente en ZEIT Day 2018 y envió 1.0 el 11 de abril de 2019. MDX combina contenido Markdown con componentes JSX, así que un escritor puede dejar un <Chart /> o un <Tweet id="123" /> directamente en la prosa. Alimenta los docs de Next.js, Docusaurus y la mayoría de sitios de documentación basados en React. MDX tiene su propio parser distinto de CommonMark; v1 estaba basada en remark, v2+ usa una gramática MDX dedicada para manejar expresiones JSX correctamente dentro del contexto de párrafo.

Pandoc, el conversor universal

Pandoc fue lanzado por John MacFarlane, entonces profesor de filosofía en la Universidad de California, Berkeley, el 10 de agosto de 2006. Está escrito en Haskell, y su diseño se centra en parsear cualquiera de unos 30 formatos de entrada (Markdown, reStructuredText, HTML, LaTeX, DocBook, Textile, marcado MediaWiki y DokuWiki, Org-mode, Microsoft Word .docx, OpenDocument, EPUB, JATS XML, Jupyter .ipynb y otros) en un modelo de documento abstracto compartido, y luego renderizar ese modelo en alrededor de 40 formatos de salida (HTML, PDF vía LaTeX o wkhtmltopdf, .docx, .odt, ePub2/3, formatos de diapositivas incluyendo Beamer y reveal.js, y muchos más). Es ubicuo en publicación académica y técnica porque lleva citas a través de CSL JSON / BibTeX y las resuelve en referencias formateadas para cualquiera de los principales estilos de citación. El dialecto Markdown que Pandoc parsea por defecto («Pandoc Markdown») es en sí un superconjunto de CommonMark con extensiones para notas al pie, listas de definiciones, divs con fence, matemáticas (estilo LaTeX $...$ y $$...$$) y leyendas de tablas. Pandoc está bajo licencia GPL v2-or-later y es lo que la mayoría de departamentos académicos usan para compilar manuscritos Markdown en documentos Word listos para revistas.

MultiMarkdown, Markdown Extra y SmartyPants

Dos dialectos de extensión anteriores preceden a CommonMark e influenciaron tanto a GFM como a Pandoc. MultiMarkdown fue creado por Fletcher T. Penney con un release inicial en mayo de 2007 (el trabajo del proyecto comenzó en 2005-2006), motivado por la escritura académica, Penney quería un Markdown capaz de producir un manuscrito publicable con notas al pie, citas, matemáticas, listas de definiciones y metadatos de documento estilo YAML. MultiMarkdown introdujo o popularizó las tablas de carácter pipe, los marcadores de notas al pie [^id], la notación matemática, los bloques de metadatos a nivel de documento al inicio de los archivos, y leyendas de imágenes y tablas. Markdown Extra fue creado por Michel Fortin (autor de PHP Markdown) en 2005-2006 y añadió tablas de pipe, bloques de código con fence con ~~~ (más tarde también ```), notas al pie, listas de definiciones, abreviaturas y la sintaxis de atributo {#id .class} para encabezados. Su contribución más distintiva fue la relajación de las reglas de Markdown-dentro-de-HTML, el atributo markdown="1" que permite anidar Markdown dentro de un bloque HTML. Varias decisiones de diseño de CommonMark y GFM alrededor del código con fence y las tablas se remontan a Markdown Extra. Por separado, SmartyPants: el compañero tipográfico del propio Gruber de 2002, realiza sustituciones tipográficas: comillas ASCII rectas se convierten en comillas curvas, los guiones dobles y triples se convierten en guiones de cuadratín y eme, tres puntos se convierten en una elipsis verdadera. Markdown maneja la estructura; SmartyPants maneja el pulido; muchos parsers agrupan comportamiento estilo SmartyPants como paso de post-procesamiento (markdown-it-smartypants, remark-smartypants), y Pandoc lo tiene incorporado detrás de un flag --smart.

Trampas comunes, diez cosas que muerden a escritores nuevos

Un previewer en vivo hace la mayoría de sorpresas de parsing obvias inmediatamente, pero entender por qué ocurren ayuda a un escritor a obtener la fuente correcta a la primera.

1. Conversión de comillas inteligentes que rompe muestras de código. Los filtros estilo SmartyPants convierten alegremente comillas dentro de lo que parece prosa (incluyendo, a veces, dentro de spans de código inline o valores de atributo HTML) dejándote con marcado roto. La mayoría de parsers modernos excluyen los spans de código de la sustitución tipográfica, pero las plataformas de blog con pipelines personalizados a menudo no lo hacen.
2. La detección de marcadores de lista es sensible a espacios. Mezclar -, * y + dentro de la misma lista, indentar párrafos de continuación de lista por menos de lo que el marcador requiere, o poner una línea en blanco entre items de lista puede voltear una lista apretada en lista suelta (cada item envuelto en etiquetas <p>), una diferencia invisible en la fuente pero dramática en la salida.
3. Sobre-celo de autolink. El autolinking estilo GFM convierte cualquier URL desnuda en un enlace, lo cual usualmente es lo que quieres, pero también puede mutilar URLs dentro de lo que debería haber sido un span de código, o URLs con paréntesis (URLs de Wikipedia especialmente). La regla para «¿dónde termina esta URL?» varía entre parsers.
4. Pistas de lenguaje en fences de código. El texto después del triple backtick de apertura, ```js vs ```javascript vs ```ts vs ```typescript: es una pista, no una spec. Diferentes resaltadores de sintaxis reconocen diferentes alias; Highlight.js, Prism, Shiki y el renderizador de GitHub cada uno tienen sus propios diccionarios de lenguajes.
5. Tablas que necesitan escape. Los caracteres pipe dentro de celdas de tabla deben ser escapados como \|, de lo contrario son leídos como separadores de columna. Atrapa a cualquiera que intente poner un ejemplo de código de una línea dentro de una celda de tabla.
6. Saltos de línea duros. Dentro de un párrafo, una sola nueva línea se trata como espacio en blanco y las líneas se unen; tienes que poner dos espacios finales al final de la línea, o usar una barra invertida, dependiendo del parser. CommonMark permite ambos. Algunos parsers más antiguos requieren un <br> explícito.
7. Markdown y HTML mezclados. Markdown fue diseñado para pasar HTML arbitrario a través, así que dejar un <div class="callout"> en un archivo Markdown funciona. Pero en el momento en que pones sintaxis Markdown dentro de un bloque HTML, los parsers divergen: CommonMark trata la mayoría de bloques HTML como opacos; Markdown Extra introdujo markdown="1" para optar al parsing anidado.
8. Entidades HTML y escapes de caracteres. Un ampersand & en una URL no necesita escape dentro de un enlace Markdown, pero el mismo & fuera de un enlace se pasará al HTML y puede necesitar ser & para conformidad estricta HTML5. La mayoría de renderizadores manejan esto automáticamente; algunos no.
9. IDs de encabezado. GitHub auto-genera IDs de fragmento de URL desde el texto del encabezado usando una regla de slugify; muchos parsers lo hacen también, pero los algoritmos de slugify difieren. Mismo encabezado, anclaje diferente entre plataformas, una causa perenne de enlaces intra-documento rotos cuando el contenido se mueve entre sistemas.
10. Espacios finales y configuración del editor. Los editores que eliminan espacios finales al guardar borrarán silenciosamente la sintaxis de salto de línea de dos espacios finales de Markdown. Los editores que convierten tabulaciones a espacios (o lo contrario) romperán bloques de código que dependen de indentación.

Markdown y seguridad, XSS y sanitización

Markdown es peligroso de una forma específica: cada parser convencional pasa el HTML crudo a través sin cambios. Eso es por diseño (es lo que hace a Markdown útil para callouts y embeds codificados a mano) pero también significa que un previewer Markdown que inyecta la salida del parser directamente al DOM es, por defecto, un vector XSS. Pegar <img src=x onerror="alert(1)"> en un editor Markdown y renderizar la salida sin sanitización ejecutará la alerta. Dos capas de defensa son estándar. Primero, configuración a nivel de parser: marked.js, markdown-it y remark todos exponen opciones para deshabilitar HTML crudo o escaparlo en la salida (markdown-it tiene html: false por defecto; remark/rehype tiene rehype-sanitize). GFM adicionalmente especifica la extensión «HTML crudo prohibido» que elimina una lista codificada de elementos peligrosos. Segundo y más robusto, sanitización HTML después del parsing: DOMPurify, escrito por la firma de seguridad berlinesa Cure53 a partir de febrero de 2014, es el sanitizer JavaScript de facto. Toma una cadena HTML, la parsea en un DOM, recorre el árbol permitiendo solo un subconjunto seguro y configurable de elementos y atributos, y serializa el resultado. DOMPurify elimina <script>, bloquea handlers de eventos inline, retira URLs javascript:, y maneja cien bypasses XSS sutiles (abusos de SVG <use>, polyglots de atributos MathML) que un sanitizer regex ingenuo perdería. El pipeline recomendado para cualquier previewer basado en navegador que acepta HTML crudo es: markdownString → parser → htmlString → DOMPurify.sanitize() → innerHTML. CommonMark también requiere explícitamente que los parsers rechacen URIs javascript: en autolinks; la mayoría de parsers extienden ese rechazo a todas las formas de enlace.

Markdown vs reStructuredText vs AsciiDoc

Markdown es el lenguaje de marcado ligero dominante pero no el único. reStructuredText (reST) fue lanzado por primera vez en junio de 2001 por David Goodger como parte del Python Doc-SIG, evolucionando de un formato Zope anterior llamado StructuredText. Se convirtió en el formato de documentación oficial de Python en 2002 y es el lenguaje de entrada para Sphinx, el generador de documentación detrás de casi todos los docs de proyectos Python (los docs oficiales del lenguaje Python, NumPy, SciPy, Django, Flask, scikit-learn, pandas, la documentación del kernel Linux desde 2016, CMake, LLVM). La filosofía de diseño de RST es esencialmente lo opuesto a la de Markdown: acepta más ruido visual en la fuente a cambio de más precisión semántica en la salida. RST tiene un mecanismo de extensión integrado vía «directivas» (.. note::, .. code-block:: python) y «roles» (:func:, :ref:) que permite a un proyecto definir marcado específico de dominio sin abandonar el formato. AsciiDoc fue creado en 2002 por Stuart Rackham como una herramienta Python que deliberadamente apunta a la semántica DocBook XML (cada documento AsciiDoc mapea limpiamente a DocBook) haciéndolo el marcado de elección para proyectos que necesitan libros de calidad de publicación, especificaciones técnicas y manuales. AsciiDoc es en lo que está escrita la documentación del proyecto Git, lo que O’Reilly Media usa para muchos de sus libros, lo que Red Hat y Mozilla usan para varios conjuntos de documentación de producto, y lo que GitHub y GitLab soportan nativamente como alternativa a README.adoc. La implementación Python original ha sido reemplazada por Asciidoctor, una implementación Ruby lanzada en 2013. Guía práctica: elige Markdown para publicaciones de blog, READMEs, chat, notas y la mayor parte de la documentación; reStructuredText para documentación Python procesada por Sphinx; AsciiDoc para libros largos o especificaciones que necesitan renderizar a DocBook, PDF y EPUB simultáneamente con fidelidad semántica completa.

Preguntas frecuentes

¿Qué funciones de Markdown son compatibles?

Este previsualizador admite encabezados, negrita, cursiva, enlaces, imágenes, listas, citas en bloque, bloques de código, tablas, reglas horizontales y tachados. Cubre la especificación CommonMark más extensiones comunes.

¿Puedo exportar el HTML renderizado?

Puedes copiar la salida renderizada desde el panel de vista previa. Para el HTML sin procesar, haz clic derecho en la vista previa y usa la función "Inspeccionar" o "Ver código fuente" de tu navegador para copiar el marcado generado.

¿Se guarda mi texto?

No. Todo se ejecuta en tu navegador y nada se almacena ni se envía a un servidor. Cierra la pestaña y tu texto desaparece. Copia tu Markdown antes de salir si deseas guardarlo.

¿Mi texto se guarda o envía a algún sitio?

No. El parser Markdown corre enteramente en tu navegador vía JavaScript. Nada se sube, ninguna API se llama, no se escriben logs. Cierra la pestaña y el texto se va. Si quieres conservar lo que escribiste, cópialo antes de salir de la página. También puedes usar la página offline una vez que ha cargado, el caching por service-worker significa que el parser permanece disponible sin conexión a internet.

¿El previewer sanitiza HTML crudo?

El parser pasa el HTML crudo a través, lo cual es el comportamiento CommonMark estándar, útil para incrustar el ocasional <div> o <details>. Como la entrada viene de tu propia sesión de navegador y la salida solo se renderiza en tu propia pestaña, esto es seguro para el caso de uso de preview de una persona para el que está construido. Si estás publicando la salida en un sistema multi-usuario (un CMS, un foro, un sitio de documentación que acepta envíos de usuarios) deberías siempre pasar el HTML renderizado por un sanitizer como DOMPurify antes de inyectarlo en una página pública, Markdown más HTML crudo es un vector XSS en cualquier sistema donde el escritor y el lector son personas diferentes.

¿Hay límites en el tamaño del archivo?

Sin límite duro. El parser maneja decenas de miles de líneas de Markdown sin problema en un laptop típico. El re-render en vivo corre en cada pulsación de tecla, así que documentos muy grandes (un libro completo en un solo archivo) empezarán a sentirse lentos en dispositivos más lentos. Dividir en capítulos, o pegar el contenido para renderizar una vez y luego editar offline, es la solución. La página no congelará tu navegador, marked.js es uno de los parsers Markdown más rápidos disponibles.

Herramientas relacionadas