Markdown es permisivo.Es posible que aún se reproduzca un documento con errores estructurales, lo que hace que esos errores sean fáciles de pasar por alto hasta que una tabla se rompe, un título desaparece de la navegación o una imagen deja de tener sentido para el usuario de un lector de pantalla.
Markdown linting es el proceso de comprobar el texto fuente para detectar problemas estructurales, de accesibilidad y de coherencia antes de su publicación.Comience con el Linter de Markdown para detectar niveles de encabezado omitidos, texto alternativo de imagen faltante, URL desnudas, barreras de código sin etiquetar o sin cerrar y espacios en blanco al final.Luego utilice la lista de verificación manual de esta guía para una revisión editorial más amplia.
Linting no consiste en hacer cumplir preferencias arbitrarias.Una regla útil debería evitar un problema real de lectura, renderizado, mantenimiento o accesibilidad.
Lista de verificación rápida previa a la publicación
| Verificar | Por qué es importante | ¿Automatizado o manual? |
|---|---|---|
| Jerarquía de títulos | Preserva la estructura del documento | Linter |
| Texto alternativo de la imagen | Hace que las imágenes sean comprensibles sin la vista | Linter |
| Enlaces descriptivos | Mejora la accesibilidad y el escaneo | Linter + revisión manual |
| Vallas de código cerrado | Evita que el resto de la página se convierta en código | Linter |
| Etiquetas de lenguaje de código | Habilita el resaltado de sintaxis útil | Linter |
| Espacio en blanco final | Evita comportamientos invisibles y específicos del dialecto | Linter |
| Un título de página claro | Mantiene el propósito de la página sin ambigüedades | Revisión manual |
| Listas consistentes | Previene el anidamiento roto | Revisión manual |
| Tablas válidas | Mantiene intacta la estructura de la columna | Revisión manual |
| Encabezamientos únicos | Evita la confusión de anclajes duplicados | Revisión manual |
| Uso portátil HTML | Evita fallas específicas del renderizador | Revisión manual |
| Párrafos legibles | Mejora la comprensión | Revisión manual |
Pegue un documento representativo en el linter, ejecute las comprobaciones, corrija las líneas informadas y luego obtenga una vista previa de la página completa en su sistema de publicación real.
1. Niveles de encabezado omitidos
Problema
# Deployment Guide
### Configure credentials
El documento salta de H1 a H3.Puede parecer aceptable cuando los tamaños de fuente son la única señal visible, pero al contorno estructural le falta un nivel.
Arreglar
# Deployment Guide
## Configure credentials
Utilice títulos para describir la jerarquía, no para elegir un tamaño visual.Si "Configurar credenciales" realmente pertenece a una sección que falta, agregue esa sección:
# Deployment Guide
## Preparation
### Configure credentials
El Linter de Markdown informa de un título que salta más de un nivel.
2. Encabezados H1 múltiples o faltantes
Normalmente, una página debe tener un título claro.Algunos sistemas de documentación generan el H1 a partir del texto frontal, mientras que otros lo esperan en el cuerpo Markdown.Sepa qué convención utiliza su sitio.
Fuente ambigua
# Installation
# Configuration
Borrar fuente
# Product setup
## Installation
## Configuration
Si la plantilla de su sitio muestra title: Product setup como página H1, el cuerpo puede comenzar con H2.La regla no es “cada archivo Markdown debe contener exactamente un #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. Encabezados utilizados únicamente para énfasis
Esta fuente crea una entrada de esquema innecesaria:
#### Important!
Si el texto no introduce una sección, utilice prosa o una leyenda apropiada:
**Important:** Back up the database before continuing.
Los títulos deben ayudar a los lectores a navegar.Los títulos decorativos hacen que el índice sea ruidoso y reducen la utilidad de la navegación asistida.
4. Imágenes sin texto alternativo
Problema

La imagen no tiene alternativa de texto.Un lector que no puede verlo no recibe ninguna explicación, y alguien que explora imágenes rotas o deshabilitadas no puede determinar su propósito.
Arreglar

Describe la información que aporta la imagen, no solo su apariencia.Evite frases como “imagen de” a menos que el medio sea importante.
Las imágenes decorativas son un caso especial.El texto alternativo vacío puede ser correcto en HTML cuando una imagen no transmite información, pero los renderizadores y los flujos de trabajo de contenido de Markdown difieren.Si una imagen es puramente decorativa, primero pregunte si pertenece o no a la documentación técnica.
El linter marca imágenes Markdown con texto alternativo vacío.el Formateador de imágenes puede generar marcas de imagen con una alternativa explícita y un título opcional.
5. Vínculos débiles o desnudos
Problema
Visit https://example.com/docs/setup for more information.
Las URL desnudas son difíciles de escanear y pueden resultar desagradables cuando se leen en voz alta.El texto del enlace genérico no es mucho mejor:
[Click here](https://example.com/docs/setup).
Arreglar
Read the [service setup guide](https://example.com/docs/setup).
Los enlaces descriptivos indican a los lectores lo que abrirán.También siguen siendo significativos cuando se extraen en una lista de enlaces.
El linter identifica muchos desnudos http:// and https:// URL, pero aún se requiere una revisión editorial para juzgar si el texto del enlace es útil.
6. Cercas de código no cerradas
Problema
```javascript
const status = 'ready';
## Next section
Sin una valla de cierre, el renderizador puede tratar el resto de la página como código.
Arreglar
```javascript
const status = 'ready';
```
## Next section
Una valla no cerrada puede romper una gran sección de un documento que de otro modo sería válido.El linter informa la línea donde comienza la valla inigualable.
7. Vallas de código sin identificadores de idioma
Menos útil
```
npm run build
```
Mejor
```bash
npm run build
```
Un identificador de idioma permite resaltar la sintaxis y comunica qué tipo de contenido está viendo el lector.Utilice identificadores comunes como javascript, typescript, json, html, css, bash, powershell, yaml, o markdown.
No agregue un lenguaje inexacto simplemente para obtener colores.Para resultados no estructurados, utilice text cuando el destino lo reconoce.
8. Sangría de lista inconsistente
Problema
- Install dependencies
- Production packages
* Development packages
- Optional tools
Las pestañas, espacios y marcadores mixtos son difíciles de revisar y pueden renderizarse en diferentes niveles.
Arreglar
- Install dependencies
- Production packages
- Development packages
- Optional tools
Elija un ancho de sangría consistente para el proyecto.El número exacto de espacios puede depender del dialecto Markdown y del contenido de la lista, pero la coherencia es esencial.
Utilizar el Formateador de listas anidadas para normalizar la combinación de viñetas, numeración, tabulaciones y sangrías antes de la revisión final.
9. Secuencias numéricas escritas manualmente
Las listas numeradas largas son caras de mantener:
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
Muchos renderizadores Markdown permiten el uso de cada elemento 1. mientras todavía se muestra una secuencia ordenada:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
Esto reduce el ruido de renumeración en las diferencias de fuente.Sin embargo, es más fácil discutir la fuente explícitamente numerada cuando las instrucciones se refieren al “paso 3”.Elija una convención de proyecto y aplíquela de manera consistente.
No combine números escritos, marcadores de lista ordenada y texto de párrafo.Confirme el resultado renderizado después de editar los pasos anidados.
10. Tablas mal formadas
Problema
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
Las filas de separador y de datos no contienen el mismo número lógico de columnas.
Arreglar
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
También verifique si hay caracteres de canalización sin escape dentro de las celdas:
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
El Formateador de tablas Markdown ayuda a exponer filas desiguales y produce una fuente alineada.Para crear una nueva tabla visualmente, utilice el Markdown Generador de tablas.
11. Rumbos duplicados y colisiones de anclas
Un documento puede repetir legítimamente un encabezado visible como “Ejemplos”, pero los ID de anclaje generados automáticamente pueden convertirse en #examples, #examples-1, y #examples-2.La regla exacta varía según el renderizador.
Los títulos repetidos hacen que los enlaces manuales sean frágiles:
- [API examples](#examples)
- [CLI examples](#examples)
Prefiere títulos descriptivos:
## API examples
## CLI examples
Luego genere una tabla de contenidos con el Markdown Generador TOC y verificar los anclajes en la plataforma de destino.
12. Espacios en blanco al final
Los espacios al final de una línea son invisibles.En algunos dialectos Markdown, dos espacios finales crean un salto de línea, lo que significa que una acción accidental del editor puede cambiar la representación.
El linter informa espacios en blanco al final para que pueda decidir si es deliberado.Prefiere una línea vacía para la separación de párrafos.Si realmente se requiere un salto de línea estricto, documente y aplique la convención elegida para el proyecto de manera consistente.
Los editores generalmente pueden eliminar los espacios en blanco finales automáticamente al guardar, pero verifique que esto no cambie los saltos de línea intencionales en el contenido heredado.
13. HTML Bruto Que Reduce La Portabilidad
Markdown a menudo permite incorporar HTML:
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
Ese bloque puede funcionar en un sitio web y tener escapes, desinfectarse o tener un estilo incorrecto en otro lugar.Prefiere portátil Markdown cuando pueda expresar el mismo significado:
> **Warning:** Restarting the service ends active sessions.
Utilice HTML deliberadamente para funciones que Markdown no puede expresar, como el tamaño de imagen controlado o un soporte <details> .Mantenga una lista de los destinos donde debe renderizarse el contenido y pruebe cada uno.
El Generador de llamadas puede producir una sintaxis específica de plataforma para GitHub, Obsidian y MkDocs cuando la portabilidad es menos importante que la presentación nativa.
14. Párrafos demasiado largos y mala capacidad de escaneo
Markdown puede ser estructuralmente válido y aún así difícil de leer.Se debe reorganizar un muro de texto que contiene varias decisiones, advertencias y procedimientos.
Uso:
- párrafos cortos para una idea principal;
- títulos descriptivos para la navegación;
- para elementos paralelos;
- para campos realmente comparables;
- bloques de código para entrada y salida literal;
- llamadas para un pequeño número de excepciones importantes.
No conviertas cada frase en una viñeta.Las listas funcionan mejor cuando los elementos tienen la misma función gramatical y conceptual.
Utilización Recuento de palabras y tiempo de lectura para inspeccionar el recuento de párrafos, el recuento de encabezados y la longitud de lectura, pero trate las estadísticas como señales en lugar de objetivos.
15. Sintaxis específica del renderizador sin un plan de compatibilidad
GitHub, los enlaces wiki Obsidian, las advertencias MkDocs, las notas a pie de página, las listas de definiciones y los textos preliminares son útiles, pero no se admiten de manera idéntica en todas partes.
Por ejemplo:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
Antes de adoptar una prórroga, responda tres preguntas:
- ¿Qué renderizador posee el resultado final?
- ¿Es necesario trasladar el contenido a otro lugar más adelante?
- ¿Qué verán los lectores cuando la extensión no sea compatible?
Mantenga una base portátil Markdown y agregue sintaxis de plataforma en el borde de publicación cuando sea posible.
Un flujo de trabajo práctico de Linting
Paso 1: Verificar la estructura
Pegue la fuente en el Linter de Markdown.Primero corrija los errores, luego las advertencias y luego los elementos de coherencia informativa.Los controles automatizados deben identificar las ubicaciones;no deberían reescribir silenciosamente el significado.
Paso 2: Normalizar elementos difíciles
Utilice herramientas específicas para la limpieza mecánica:
- Formateador de listas anidadas para sangría;
- Formateador de tablas Markdown para mesas de tuberías;
- Formateador de imágenes para marcado de imágenes;
- Generador de tabla de contenidos para anclajes de rumbo.
Los cambios enfocados producen diferencias más pequeñas y más fáciles de revisar que un formateador amplio que reescribe todo el archivo.
Paso 3: Vista previa del documento
Abrir la fuente en el Markdown Editor y compare el Markdown con la salida renderizada.Comprobar:
- títulos y índice;
- y listas de tareas;
- mesas en una pantalla estrecha;
- imágenes y enlaces;
- bloques de código y código en línea;
- rótulos o brutos HTML.
Paso 4: Probar el destino real
Una vista previa genérica no puede reproducir todos los renderizadores.Abra el archivo en GitHub, Obsidian, GitLab, MkDocs o el sitio de documentación real antes de publicarlo.
Paso 5: Revisar el significado, no solo la sintaxis
Ningún linter puede determinar si un procedimiento es seguro, si un enlace apunta a la política prevista o si una descripción de imagen comunica la conclusión importante.Un revisor humano debe confirmar la precisión, la integridad, el tono y la adecuación a la audiencia.
Recomendaciones de la guía de estilo del equipo
Una convención breve y documentada es más eficaz que docenas de preferencias tácitas.Definir:
- si el título de la página se encuentra en la portada o en el cuerpo Markdown;
- la progresión de rumbo permitida;
- sangría de lista y estilo de lista ordenada;
- requisitos de lenguaje de delimitación de códigos;
- cómo se revisan las imágenes y el texto alternativo;
- límites de complejidad de la tabla;
- permite HTML y ampliaciones de andén;
- longitud máxima de línea, si el equipo utiliza una;
- cómo se comprueban los enlaces;
- cuyas reglas de linter bloquean la publicación.
Comience con reglas que prevengan defectos reales.Agregue una regla solo cuando el equipo comprenda el problema que resuelve.
FAQ
¿Se puede acceder automáticamente al Markdown válido?
No. La sintaxis válida aún puede contener texto alternativo vacío, enlaces vagos, títulos confusos, diagramas inaccesibles y un orden de lectura deficiente.La accesibilidad requiere revisión estructural y editorial.
¿El Linter Markdown reescribirá mi documento?
El linter WordToMD informa problemas con los números de línea.No reescribe silenciosamente la fuente, por lo que usted conserva el control sobre cada corrección.
¿Por qué el linter informa una URL vacía?
El texto del enlace descriptivo es más fácil de escanear y más útil para la tecnología de asistencia.Reemplace la URL con una etiqueta significativa a menos que la dirección literal sea la información que los lectores necesitan.
¿Es siempre incorrecta una valla codificada sin etiquetar?
No siempre, pero un identificador de idioma correcto generalmente mejora la claridad y el resaltado de sintaxis.uso text para una salida simple cuando sea compatible en lugar de asignar un lenguaje de programación inexacto.
¿Todos los proyectos deberían utilizar las mismas reglas de linting?
No. Un GitHub README, una bóveda Obsidian, una referencia API y un sitio de publicación tienen convenciones diferentes.Comparta un conjunto básico de reglas estructurales y de accesibilidad y luego agregue comprobaciones específicas del destino.
¿Puede el linting reemplazar la revisión?
No. Un linter detecta patrones.No puede verificar de manera confiable la verdad técnica, la calidad de los argumentos, la intención del usuario o si una oración es comprensible en contexto.
Conclusión
Bueno Markdown es más que fuente que pasa a renderizar.Tiene un esquema claro, enlaces significativos, imágenes accesibles, barreras de código completas, listas consistentes, tablas válidas y una relación definida con su plataforma de publicación.
Ejecute el Linter de Markdown para verificaciones estructurales rápidas, utilice el Markdown Editor para revisión visual y aplique formateadores específicos solo cuando faciliten el mantenimiento de la fuente.El resultado es Markdown, que es más portátil, accesible y confiable en futuras ediciones.