Formateador Markdown

Qué hace un formateador Markdown

Un formateador Markdown pone orden en un formato que es muy tolerante. Puedes escribir una viñeta con -, * o +, el énfasis con * o _, y un encabezado con una fila de signos de igual o con #. Esa libertad es cómoda al escribir, pero un archivo editado por varias personas pronto mezcla todos los estilos. Las tablas se desalinean, faltan líneas en blanco y los diffs se llenan de ruido.

Este formateador reescribe el código fuente con un único estilo uniforme. Está basado en Prettier, el formateador que la mayoría de los proyectos de JavaScript ya usan para su documentación, así que el resultado coincide con lo que da Prettier en VS Code o en la línea de comandos.

Cómo usarlo

1. Pega tu Markdown en el cuadro de la izquierda, o pulsa Abrir archivo para cargar un archivo .md. Al pegarlo, se formatea en el acto.
2. Pulsa Ejemplo si quieres ver una muestra primero.
3. Elige la Sangría, el Ancho de línea y cómo Ajustar texto: Mantener tal cual, Al ancho de línea o Una línea por párrafo.
4. Pulsa Formatear (o Ctrl+Intro) para volver a ejecutarlo después de cambiar algo.
5. Usa Copiar o Descargar para llevarte el resultado. Borrar vacía la entrada.

Después de formatear una vez, el resultado sigue lo que escribes.

Antes y después

Este es un archivo corto escrito con estilos mezclados:

Project Notes
=============
* Install the tools
* Run the build
+ Deploy

|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|

Some *emphasis* and __bold__ text.

El formateador devuelve:

Project Notes
=============

- Install the tools
- Run the build

* Deploy

| Name  | Role   |
| ----- | ------ |
| Ada   | Admin  |
| Linus | Editor |

Some _emphasis_ and **bold** text.

Pasaron varias cosas. Ahora hay una línea en blanco después del encabezado. La primera lista usa -. La negrita usa ** y la cursiva usa _. Las columnas de la tabla se rellenan para que queden alineadas en texto plano. Fíjate en que “Deploy” se quedó aparte: usaba otra viñeta, así que Markdown la trata como una segunda lista, y el formateador conserva ese significado dándole un marcador distinto.

Ajustar párrafos largos

Con Ajustar texto en Al ancho de línea y un ancho de línea de 60, este párrafo:

Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.

pasa a:

Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.

Una línea por párrafo hace lo contrario y vuelve a unir las líneas partidas. Mantener tal cual es la opción predeterminada segura cuando no sabes qué espera tu equipo.

Lo que no toca

El formateador cambia la disposición, no el significado. Hay cosas que deja sin tocar a propósito:

• Bloques de código. El código dentro de un bloque delimitado se queda exactamente como está. Un bloque marcado como js que contiene const a={b:1} no se reformatea. Para eso usa el formateador JavaScript.
• Listas numeradas. Si todos los elementos empiezan por 1., mantiene 1. en cada línea. Si los numeraste 1, 2, 3, mantiene esa numeración.
• Texto que no es sintaxis válida. #Title sin espacio no es un encabezado en CommonMark, así que sigue siendo un párrafo normal. Añade el espacio y se convierte en encabezado.
• HTML en línea. Las etiquetas HTML dentro de tu Markdown se conservan tal cual.

Consejos

• Formatea antes de hacer commit. Con archivos uniformes, el diff de un pull request solo muestra los cambios reales.
• Elige una sola regla de ajuste para todo el repositorio. Mezclar archivos ajustados y sin ajustar provoca diffs enormes la primera vez que alguien los formatea.
• Crear una tabla a mano es lento. El generador de tablas Markdown te da una cuadrícula para escribir y acepta datos pegados desde hojas de cálculo.
• ¿Necesitas Markdown a partir de una página web o de un archivo de Word? Usa el convertidor de HTML a Markdown o el convertidor de Word a Markdown, y luego ordena el resultado aquí.

Otras formas de formatear Markdown

• VS Code: instala la extensión de Prettier, abre un archivo .md y ejecuta Dar formato al documento. El resultado coincide con esta página.
• Línea de comandos: npx prettier --write README.md formatea un archivo en su sitio. Añade --prose-wrap always para ajustar los párrafos.
• Linting: markdownlint comprueba reglas de estilo como los niveles de encabezado y la longitud de las líneas. Informa de los problemas, mientras que un formateador corrige la disposición por ti. Muchos proyectos usan los dos.

Límites

El formateador sigue CommonMark con las extensiones de GitHub, como las tablas y las listas de tareas. Las extensiones de otras herramientas, como los contenedores personalizados o los enlaces de wiki, se tratan como texto normal y pueden quedar con un espaciado distinto del que espera esa herramienta. El front matter al principio de un archivo (el bloque entre dos líneas ---) se conserva. Los archivos muy grandes funcionan, pero el formateo tarda más porque todo ocurre en tu dispositivo.