Un linter para tu Markdown, con explicaciones que un humano puede leer
Markdown parece simple hasta que tu README, sitio de docs o blog post empieza a verse inconsistente: marcadores de lista mezclados (estilo de bullet), trailing whitespace, headings que saltan un nivel (niveles de heading), fenced code blocks sin tag de lenguaje. Un renderer seguirá renderizando la página, pero el resultado es chapucero y el ruido en el diff es enorme.
Esta herramienta corre el mismo motor que el CLI `markdownlint` (markdownlint) en tu texto. Obtienes una lista numerada de issues, cada uno con el código de regla (`MD009`, `MD040`, ...), una descripción de una línea, y donde es auto-fixable un preview del arreglo. Pulsa una fila, el textarea hace scroll a esa línea.
Cuatro presets cubren las elecciones habituales: Recomendado (el default, sensato para cualquier proyecto), GitHub (amigable con GFM), Strict (líneas de 80 columnas más sin headings duplicados), Reglas custom (todo activado). Activa Modo fix para ver el texto limpio y copiarlo con un clic.
Cómo usarlo
- Pega tu Markdown en el gran textarea de la izquierda. Por defecto se carga un pequeño ejemplo con problemas intencionales para que la herramienta tenga algo que mostrar al instante.
- Elige un preset arriba: Recomendado para casi cualquier proyecto, GitHub cuando tu fichero va a GitHub o GitLab, Strict para docs técnicas que quieren cada regla activa más líneas de 80 columnas, Reglas custom para activar cada chequeo disponible.
- Pulsa "Ejecutar lint". El panel derecho se rellena con una lista numerada de issues. Cada uno muestra el código de regla (p. ej. `MD040`), una descripción corta, el snippet relevante y un badge "auto-fix" si markdownlint puede arreglarlo por ti.
- Pulsa cualquier fila de issue para saltar a esa línea en el textarea. La línea se selecciona para que puedas editarla directamente. Útil para clasificar docenas de issues sin scrollear manualmente.
- Activa "Modo fix" para ver la salida limpia en lugar de tu entrada raw. Todos los issues auto-fixables se aplican. Los estructurales (estilo de heading, tags de lenguaje, errores de contenido) los arreglas a mano.
- Pulsa "Copiar" para coger o tu entrada raw o la salida limpia (según el Modo fix). Ese es el string que pegas de vuelta en tu README o doc.
- Lee el FAQ abajo si quieres saber qué significa una regla específica o qué preset coincide con la convención de tu equipo. Cada código de regla enlaza a una explicación breve en lenguaje claro.
Cuándo es útil
Seis situaciones concretas en las que un linter Markdown ahorra tiempo real:
- Comprobación de cordura de un README antes de hacer push. Escribiste 300 líneas, usaste `-` para bullets en la primera mitad y `*` en la segunda, tres de tus bloques de código no tienen tags de lenguaje así que el resaltador de sintaxis de GitHub los renderiza monocromos. Lint, fix, push.
- Onboarding de un sitio de docs (Astro, Hugo, Docusaurus, MkDocs). El generador envuelve cada página en un layout. El Markdown malo aparece como tablas mal alineadas, enlaces ancla rotos y jerarquía de heading inconsistente en el sidebar. Lintear antes de añadir páginas pilla todo eso.
- Revisión de código de un PR de un compañero. Pegaron Markdown desde Notion, que adora emitir trailing whitespace y smart quotes. Lint, pega la lista en el comentario del PR, "aquí hay 12 cosas que arreglar".
- Limpiar un tutorial antes de publicar en Medium o dev.to. Ambas plataformas tienen sus peculiaridades Markdown. Ejecutar el preset strict localmente primero elimina el juego de adivinanzas qué-renderiza-dónde.
- Migrar desde otra plataforma. Exportaste posts desde WordPress, Ghost o Substack como Markdown. Están llenos de wrappers HTML inline `<div>`, URLs raw que deberían auto-enlazarse y headings que empiezan en H2. El linter los detecta todos.
- Configurar un hook pre-commit en CI. Las mismas reglas usadas aquí van a un fichero de config en tu repo, obtienes un check verde en tus runs CI y un comentario amistoso en cada PR que las rompe.