markdown linting accessibility guía de estilo documentation

Guía de linting para Markdown: 15 problemas comunes y cómo solucionarlos

Encuentre y solucione problemas comunes de Markdown, incluidos encabezados omitidos, texto alternativo de imagen faltante, URL desnudas, barreras de código rotas, listas inconsistentes y tablas con formato incorrecto.

W
WordToMD Equipo
·

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

VerificarPor qué es importante¿Automatizado o manual?
Jerarquía de títulosPreserva la estructura del documentoLinter
Texto alternativo de la imagenHace que las imágenes sean comprensibles sin la vistaLinter
Enlaces descriptivosMejora la accesibilidad y el escaneoLinter + revisión manual
Vallas de código cerradoEvita que el resto de la página se convierta en códigoLinter
Etiquetas de lenguaje de códigoHabilita el resaltado de sintaxis útilLinter
Espacio en blanco finalEvita comportamientos invisibles y específicos del dialectoLinter
Un título de página claroMantiene el propósito de la página sin ambigüedadesRevisión manual
Listas consistentesPreviene el anidamiento rotoRevisión manual
Tablas válidasMantiene intacta la estructura de la columnaRevisión manual
Encabezamientos únicosEvita la confusión de anclajes duplicadosRevisión manual
Uso portátil HTMLEvita fallas específicas del renderizadorRevisión manual
Párrafos legiblesMejora la comprensiónRevisió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

![](architecture.png)

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

![Request flow from the browser through the API gateway to the orders service](architecture.png)

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.

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:

  1. ¿Qué renderizador posee el resultado final?
  2. ¿Es necesario trasladar el contenido a otro lugar más adelante?
  3. ¿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:

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.