Rebaja a HTML: ¿Qué sucede realmente cuando se renderiza su Léame?

He escrito Markdown todos los días laborables durante años: complementos README, registros de cambios, documentos para Toolz.dev, notas de lanzamiento para WP Adminify, la mitad de mis mensajes de compromiso. Y durante la mayor parte de ese tiempo traté el paso de renderizado como magia. Escribes asteriscos, GitHub muestra audaz. bien seguir adelante

Luego construí una sección de documentos que sacó a Markdown de la base de datos y la representé en una página de Next.js, y la magia se convirtió en una lista de decisiones muy específicas que tuve que tomar. ¿Una sola línea se convierte en una <br>¿? (Los comentarios de GitHub dicen que sí. La especificación de reducción dice que no.) tiene que hacer <div> en la fuente render como div o como texto literal? (Depende de quién le pregunta y si confías en el autor.) ¿Qué clase va en un bloque de código cercado para que el resaltador lo recoja? ¿Por qué un analizador gira **bold**text en negrita y otro lo deja solo?

Nada de eso es exótico. Es solo las cosas que nadie te dice, porque Markdown parece tan simple que la gente asume que no hay nada debajo. Hay bastante debajo de él. los Rebaja a HTML Converter on Toolz.dev expone esas decisiones como switches en lugar de ocultarlas, que es la versión de esta herramienta que quería cuando estaba depurando por qué mis saltos de línea seguían desapareciendo.

TL;Dr: Markdown es un formato de escritura; HTML es el formato de visualización. Algo tiene que compilar uno en el otro. Las reglas que hacen tropezar a las personas: líneas consecutivas se unen en un párrafo a menos que termines una línea con dos espacios (o actives una opción "breaks"), el HTML sin formato se pasa o se escapa dependiendo del analizador 's configuración de confianza, y el dialecto GitHub's (GFM) agrega tablas, listas de tareas, enlaces automáticos tachados y URL desnudos en la parte superior marcar con común línea base. El código vallado se compila en <pre><code class="language-js">, que es el prisma de gancho, Highlight.js y Shiki buscan. los Convertidor de reducción a HTML Hace todo esto en su navegador, con cada interruptor expuesto.

¿Qué es Markdown y por qué necesita la conversión?

Markdown es una sintaxis de texto sin formato que John Gruber publicó en 2004, con un objetivo de diseño declarado: un documento de Markdown debe poder publicarse tal cual, legirse como texto sin formato, sin que parezca que ha sido marcado con etiquetas. Es por eso que la sintaxis toma prestado de las convenciones que la gente ya usaba en el correo electrónico: asteriscos alrededor de una palabra para enfatizar, una línea de guiones bajo un título, a > por una cotización.

La consecuencia es que Markdown no es un formato de renderizado. Nada muestra la reducción. Los navegadores muestran HTML, y en todos los lugares que tengas visto Markdown renderizado (GitHub, un sitio estático, un portal de documentos, una aplicación de chat) ejecutó primero un analizador y puso HTML en la pantalla.

Así que la conversión tiene que suceder en alguna parte. Sus opciones son más o menos:

• en el tiempo de construcción, en un generador de sitios estáticos o un paquete. Bien cuando el contenido vive en su repositorio.
• A petición hora, en un servidor. Es necesario cuando el contenido proviene de una base de datos, costoso si lo hace en cada solicitud sin almacenar en caché.
• en el navegador, en el momento que lo necesites. Que es lo que desea cuando la respuesta a "Solo necesito el HTML para esta única cosa es una copia-pega, no una canalización de compilación.

Ese tercer caso es más común de lo que parece. Pegar notas de la versión en un campo CMS que solo toma HTML. Obtener un Léame en una plantilla de correo electrónico. Comprobar cómo se verá un documento antes de cometerlo. Convertir un borrador escrito en obsidiana en algo que puedas entregar a un diseñador. Ninguno de ellos justifica el cableado de un analizador a un proyecto.

¿cuál es la diferencia entre CommonMark y Rebaja con sabor a GitHub¿?

La especificación original de Gruber era una página de prosa y un guión de Perl, y dejó suficiente ambigüedad como para que todas las implementaciónes estuvieran en desacuerdo en los casos extremos. marcar con común es la respuesta a eso: una especificación estricta y comprobable con un conjunto de conformidad de cientos de ejemplos, de modo que dos analizadores conformes produzcan resultados idénticos para la misma entrada. Define la línea de base: encabezados, párrafos, énfasis, enlaces, imágenes, listas, comillas de bloques, bloques de código, pausas temáticas, escapes de barra invertida, bloques HTML.

Markdown con sabor a GitHub (GFM) es un superconjunto formal de Commonmark, especificado por GitHub, que agrega las cosas que la gente seguía pidiendo:

Si su Markdown proviene de un GitHub ReadMe, un wiki de Gitlab, una exportación de nociones o la mayoría de los editores modernos, es GFM. Encienda GFM en el convertidor o sus tablas se renderizarán como tuberías literales, que es el número uno "el convertidor está roto" pregunta de soporte que cualquier persona que envíe una de estas herramientas recibe.

¿Por qué desapareció mi salto de línea?

Porque Markdown, siguiendo las convenciones del correo electrónico de texto sin formato, trata las líneas consecutivas no en blanco como un solo párrafo. esto:

Line one
Line two

produce <p>Line one\nLine two</p>- un párrafo, y la nueva línea colapsa en un espacio cuando el navegador la representa. No es un error; es la especificación y existe para que puedas envolver tu prosa en 80 columnas en un editor de texto sin que ese ajuste se filtre en la salida.

Hay tres formas de obtener un descanso real:

1. Una línea en blanco inicia un nuevo párrafo. Esto es lo que quieres la mayor parte del tiempo.
2. Dos espacios de arrastre al final de una línea se produce un duro descanso - <br />. Este es el truco estándar, y es invisible en su editor, por lo que la gente lo encuentra enloquecedor.
3. una barra invertida Al final de la línea hace lo mismo en Commonmark, y es al menos visible.

Y luego está el Cuarto Camino, que es la fuente de la confusión: Muchas plataformas activan un modo "Breaks" donde cada nueva línea se convierte en un <br />. Los comentarios y problemas de GitHub hacen esto. La mayoría de las aplicaciones de chat hacen esto. Archivos de léame de GitHub no. Entonces, el mismo texto se representa de manera diferente en un problema de GitHub y en el mismo repositorio del mismo repositorio, que es una pieza de diseño genuinamente mala con la que todos estamos ahora.

El convertidor expone esto como un interruptor. Si su fuente fue escrita para un renderizador estilo chat, active la línea de salto. Si es un documento, déjelo apagado y use líneas en blanco como la especificación pretende.

¿Cómo se maneja el HTML sin procesar?

Markdown permite HTML en línea: la especificación original dice explícitamente que cualquier HTML que escriba pasa directamente. Esa es una característica cuando eres el autor (quieres tu <details> Bloque, tu <img> Con un atributo de ancho, su ancla con un rel), y es una responsabilidad cuando no lo eres.

Porque si renderizas un rebaja no confiable con HTML Pass-Through habilitado, tienes una vulnerabilidad XSS. <script>alert(document.cookie)</script> es válido la reducción. así es <img src=x onerror="...">. Así es un <a href="javascript:...">. Un cuadro de comentarios, una biografía del perfil de usuario, una wiki pública (en cualquier lugar donde extraños escriban Markdown que otras personas lean) deben escapar del HTML o desinfectar la salida con un desinfectante real (DOMPurify es la respuesta habitual y es un desinfectante real precisamente porque una expresión regular no es suficiente para una entrada hostil).

Este convertidor tiene como valor predeterminado que escapaba HTML crudo: <div> En su fuente aparece como el texto literal <div> En la salida, exactamente como si hubieras escrito <div>. Puede activar el paso a través de la fuente cuando la fuente sea suya. Y independientemente de esa configuración, la vista previa en vivo se despliega <script>, <style>, en línea on* manejadores de eventos y javascript: Las URL antes de que se representen son una medida de defensa en profundidad, por lo que pegar a otra persona 's README en el panel de vista previa no puede ejecutar su código. Esa es una medida de seguridad de vista previa, no un desinfectante de uso general: si está creando un producto que representa el Markdown del usuario, use un desinfectante dedicado del lado del servidor y no confíe en un expresiones regulares, incluido el mío.

Si necesitas escapar de un personaje de Marcar para que represente literalmente - un asterisco que debería seguir siendo un asterisco, un guión bajo en un nombre de archivo - una barra invertida lo hace: \*not emphasis\*. Y si está peleando entidades en la otra dirección, el Codificador de entidades HTML es la herramienta para ese trabajo.

¿Qué HTML debería emitir realmente un buen convertidor?

Html semántico, aburrido y sin clases, con una excepción.

• Los encabezados se convierten <h1>-<h6>. Con los ID de encabezado habilitados, cada uno también obtiene una slugificada id, deduplicado cuando dos encabezados comparten un título (#setup, #setup-1). eso es lo que hace #anchor Los enlaces profundos funcionan, y es de lo que cuelga un generador de tabla de contenido.
• Un bloque vallado con una cadena de información - ```js- se convierte <pre><code class="language-js">. *Esta es la excepción.* * El `lengua-` Clase es la convención Prism, Highlight.js y Shiki buscan, y es por eso que el convertidor emite una clase. El convertidor no colorea su código; el resaltador de su página sí, y necesita ese gancho.
• Las listas se convierten <ul>/<ol>, y aquí hay una sutileza que vale la pena conocer: una apretadamente List (sin líneas en blanco entre elementos) pone el texto directamente dentro <li>, mientras que un hacer sin cadenas La lista (líneas en blanco entre los elementos) envuelve el contenido de cada elemento en <p>. Ese es el comportamiento de Commonmark, no una peculiaridad, y es por eso que su lista aumenta repentinamente el espacio vertical cuando agrega una línea en blanco entre dos viñetas. El CSS no está roto; el HTML genuinamente cambió.
• Las tablas se vuelven reales <table>/<thead>/<tbody> margen, con style="text-align:center" En las celdas cuando la fila delimitador usa :---:.
• Las listas de tareas se convierten <input type="checkbox" disabled> dentro de la <li>, que es exactamente lo que emite GitHub.

Content-First, sin divs de contenedor, sin clases de utilidad. Lo peinas desde el exterior, con un .prose clase o sus propias reglas, y el marcado permanece portátil.

¿Cómo uso el convertidor?

Paso 1: Pega la rebaja

Ingrese un README, un registro de cambios, notas de la versión, un borrador. Actualizaciones de salida a medida que escribe: no hay ningún botón de conversión y no se carga nada.

Paso 2: Configurar los interruptores

Con sabor a GitHub En si la fuente tiene tablas, listas de tareas o tachado (probablemente sí). ID de rumbo En si quieres anclas. saltos de línea Activado solo si la fuente fue escrita para un renderizador de estilo de chat. Permitir HTML en bruto ON solo si la fuente es tuya. Documento completo Activado si desea una página HTML5 completa con doctype, charSet, viewport y un <title> Tomado de su primera <h1>- útil cuando desea abrir el resultado directamente en un navegador o colocarlo en un host estático.

Paso 3: Verifique la vista previa

Cambie a la pestaña de vista previa y confirme la estructura. La fila de estadísticas le indica palabras, encabezados, enlaces, imágenes, bloques de código y tiempo de lectura; útil para verificar una publicación es la duración que pensaba que tenía antes de publicarla. Para un recuento más completo, el Contador de palabras ¿Legibilidad y densidad de palabras clave en el mismo texto?

Paso 4: Toma la salida

Copie el HTML, descárguelo como .html archive o copie la tabla de contenido generada: una lista anidada de Markdown que enlaza con cada ancla de encabezado, lista para pegarla en la parte superior de su documento.

Si está pegando el resultado en una página donde los bytes importan, ejecútelo a través de la Minifiero HTML después. La salida del convertidor está sangrada para la legibilidad, no para el cable.

Casos de uso comunes

Obtener un Léame en un sitio web

Los autores de complementos y paquetes escriben un buen Léame, luego necesitan el mismo contenido en una página de destino. El Léame es GFM con tablas e insignias; la página de destino necesita HTML. Convierta, pegue, peine con su CSS existente. Las identificaciones de encabezado le dan un TOC de barra lateral de forma gratuita.

Publicar en un CMS que solo acepta HTML

Muchos campos CMS, plataformas de correo electrónico y paneles de administración heredados aceptan HTML y nada más. Si redactas en Markdown, y la mayoría de las personas que escriben regularmente, lo hacen, este es el puente. Convertir con Documento completo apagado, así que obtienes el fragmento en lugar de una página completa y lo pegas en el campo.

Creación de prototipos de una página de documentos

Antes de confirmar el contenido en un sitio de DOCS, convertirlo localmente muestra la jerarquía de encabezados real y si sus vallas de código llevan el idioma correcto. una h3 eso debió haber sido un h2 es obvio en el TOC e invisible en la fuente.

Auditar contenido de contenido que alguien más escribió

Pegue un colaborador 's Markdown, mire el HTML emitido y podrá ver inmediatamente si usaron encabezados reales o negritaron una línea para falsificar una, un hábito que destruye la estructura y accesibilidad del documento. Los lectores de pantalla navegan por el encabezado; **Big Text** no es un encabezado, es un párrafo en negrita, y el convertidor te muestra que en una línea de salida.

Extraer una tabla de contenido

Los documentos largos necesitan uno, y mantenerlo a mano garantiza que se vuelve obsoleto. Genérelo a partir de los encabezados, péguelo, regenera cada vez que cambien los encabezados.

Avanzado: lo que hace y no hace este parser

Es un analizador escrito a mano, de aproximadamente 400 líneas, sin dependencias, lo cual es deliberado, porque un analizador Markdown que extrae una dependencia de 200 KB en una página cuyo punto es ser rápido es una mala operación.

Cubierto: Títulos ATX (# x) y encabezados SeText (subrayados con === / ---), párrafos, énfasis y fuerte (*, _, **, __), código en línea con coincidencia de backtick, código cercado con cadenas de información, bloques de código sangrado, comillas en bloque con continuación perezosa, listas anidadas (ordenadas y desordenadas, apretadas y sueltas), cortes temáticos, enlaces e imágenes con títulos, enlaces automáticos de soporte de ángulo, enlaces automáticos de correo electrónico, escapes de barra invertida y el conjunto GFM: tablas con alineación, listas de tareas, tachado, enlace automático de URL de correo electrónico.

No cubierto: Enlaces de estilo de referencia ([text][ref] con un [ref]: url definición en otros lugares), notas al pie, listas de definición y algunos casos de esquina de Commonmark genuinamente oscuros alrededor de bloques HTML que interrumpen párrafos. Si está ejecutando el conjunto de conformidad de Commonmark contra él, no obtendrá el 100%. Si está convirtiendo un registro de cambios, un registro de cambios o una publicación de blog, no lo notará.

Esa es una operación honesta, y es la razón por la que el convertidor se carga instantáneamente y funciona con la red apagada. Para canalizaciones de contenido donde necesitas conformidad con Commonmark de Bit-Exact, usa markdown-it, remark investigaciones operacionales cmark en tu construcción; para eso están.

preguntasrán el

¿Cómo convierto Markdown a HTML?

Pegue su Markdown en el editor y el HTML aparecerá inmediatamente: no hay botón de conversión ni archivo para cargar. Active GitHub Flavored Markdown si su fuente usa tablas o listas de tareas, luego copie el HTML o descárguelo como un archivo.html. Todo se ejecuta en su navegador, por lo que los borradores inéditos y los documentos internos nunca salen de su dispositivo.

¿Qué es la reducción con sabor a GitHub?

El Markdown con sabor a GitHub (GFM) es un superconjunto formalmente especificado de Commonmark que agrega tablas, casillas de verificación de lista de tareas, tachado con doble tildes y enlaces automáticos de URL simples. Es el dialecto que GitHub usa para renderizar archivos y problemas de readme, y es lo que la mayoría de los editores de Markdown emiten hoy en día. Está habilitado de forma predeterminada en este convertidor.

¿Por qué desapareció mi salto de línea única?

El Markdown estándar une líneas consecutivas en un solo párrafo; un salto de línea solo sobrevive si termina la línea con dos espacios, usa una barra invertida o deja una línea en blanco. Si quieres que cada nueva línea se convierta en un <br />, habilite la opción de saltos de línea: ese es el comportamiento que usan los comentarios de GitHub y la mayoría de las aplicaciones de chat, pero no es lo que hacen los archivos README.

¿El convertidor resalta mi código?

Emite el marcado que necesita un resaltador pero no colorea el código en sí. Un bloque de códigos cercado etiquetado con el idioma js se convierte en <pre><code class="language-js">, que es la convención de clase prisma, Highlight.js y Shiki buscan. Agregue una de esas bibliotecas a la página donde pega la salida y el resaltado aparece automáticamente.

¿Se conserva HTML sin procesar dentro de mi Markdown?

Por defecto se escapa, por lo que <div> aparece como texto literal en lugar de una etiqueta. Active la opción permitir-raw-HTML para pasar etiquetas directamente, que es lo que desea cuando su Markdown se mezcla deliberadamente en HTML - a <details> bloque o una imagen con atributos. Solo habilítelo para la fuente en la que confíe, porque HTML sin procesar de un autor no confiable es un vector XSS.

¿Es seguro pegar la reducción que no escribí?

Sí. HTML se escapa de forma predeterminada y la vista previa en vivo además elimina las etiquetas de estilo y scripts, los controladores de eventos en línea y javascript: URL antes de renderizar. Nada de lo que pegas se transmite a ninguna parte. Si está creando un producto que representa Markdown de extraños, siga usando un desinfectante dedicado como DOMPurify del lado del servidor; un filtro de vista previa no sustituye a uno.

¿Puedo generar una tabla de contenidos a partir de mis encabezados?

Sí. Con los ID de encabezado habilitados, cada encabezado obtiene un ancla de duplicado y des-duplicado, y la herramienta crea una tabla de contenidos que se vincula a cada uno. Cópielo nuevamente en la parte superior de su documento y los enlaces se resuelven con los ID generados. Regenerarlo cada vez que tus encabezados cambien en lugar de mantenerlo a mano.

¿Este convertidor implementa completamente Commonmark?

Implementa las construcciones que la gente realmente escribe: encabezados, párrafos, énfasis, enlaces, imágenes, enlaces automáticos, comillas en bloque, listas anidadas y sueltas, código cercado y sangrado, pausas temáticas, escapes de barra invertida, además de las extensiones GFM. Los enlaces de estilo de referencia, las notas a pie de página y algunos casos raros de bordes de bloques HTML de CommonMark no están cubiertos. Para una conformidad exacta de bits en una canalización de compilación, utilice markdown-it, comment o cmark.

Herramientas relacionadas: Rebaja a HTML · Entidades HTML · Minifiero HTML · Contador de palabras · generador de babosas

Lectura relacionada: El kit de herramientas del desarrollador web · Guía de herramientas de texto