Cómo escribir Markdown accesible

Publicado el 27 de julio de 2026

Markdown produce HTML, y ese HTML es lo que acaba leyendo un lector de pantalla. La mayoría de los problemas de accesibilidad de una documentación no nacen del diseño, nacen de decisiones que se toman al escribir el texto en crudo.

Por qué esto empieza en el archivo, no en el CSS

Cuando escribes ## Instalación, no estás eligiendo un tamaño de letra. Estás declarando que ahí empieza una sección de segundo nivel, y esa información viaja hasta el HTML final convertida en una etiqueta que las tecnologías de asistencia entienden.

Ahí está la clave: Markdown es un lenguaje semántico. Cada símbolo que escribes se traduce en estructura, no en apariencia. Si esa estructura es coherente, el documento resultante es navegable. Si la usas como si fuera una barra de formato, produces un documento que se ve bien y se escucha fatal.

Hay además un motivo que ha dejado de ser solo una cuestión de buenas intenciones. La Directiva Europea de Accesibilidad es aplicable desde el 28 de junio de 2025 y extiende los requisitos de accesibilidad a un buen número de productos y servicios digitales. Que te afecte o no depende del tipo de organización y del servicio, así que conviene consultar la documentación oficial en lugar de fiarse de resúmenes de terceros.

La buena noticia es que casi todo se arregla con cinco o seis costumbres al escribir, sin herramientas extra.

Los encabezados son un índice, no un tamaño de letra

Quien usa un lector de pantalla rara vez escucha un documento de principio a fin. Lo habitual es pedirle la lista de encabezados y saltar directamente a la sección que interesa, igual que tú recorres una página con la vista.

Eso implica dos reglas. La primera es no saltarse niveles: después de un ## viene un ###, nunca un ####. Cuando saltas un nivel, quien navega por la estructura percibe un hueco y pierde la referencia de dónde está.

La segunda es no elegir el nivel por cómo se ve. Si un ### te parece más bonito que un ## para un apartado principal, el problema es del CSS, no del documento. Cambia el estilo, no la semántica.

Conviene además que cada documento tenga un único encabezado de primer nivel, el título, y que el resto cuelgue de él de forma ordenada. En este sitio las páginas ponen ese título desde el frontmatter, así que en el cuerpo se empieza directamente por ##.

Si el documento es largo, una tabla de contenidos construida sobre esos encabezados ayuda a todo el mundo, no solo a quien usa un lector de pantalla.

El texto alternativo de las imágenes

En Markdown, el texto alternativo es lo que va entre corchetes: ![aquí](imagen.png). Es el equivalente al atributo alt del HTML, y es lo único que va a escuchar quien no puede ver la imagen.

El error más común no es dejarlo vacío, es rellenarlo con lo primero que había a mano. Un texto alternativo que dice imagen, captura o Captura de pantalla 2026-07-14 a las 12.03.41 no aporta absolutamente nada.

Un buen texto alternativo describe la información que aporta la imagen en su contexto, no la imagen en sí:

Mal:  ![captura](panel.png)
Mal:  ![imagen del panel de control](panel.png)
Bien: ![Panel de control con el uso de CPU al 92 por ciento](panel.png)

Fíjate en que tampoco hace falta empezar con "imagen de" ni "gráfico que muestra". El lector de pantalla ya anuncia por su cuenta que se trata de una imagen, así que ese prefijo solo añade ruido.

Caso aparte son las imágenes decorativas, las que no aportan información y solo acompañan. Ahí lo correcto es dejar el texto alternativo vacío, ![](adorno.png), para que la tecnología de asistencia pueda saltársela en lugar de anunciar algo irrelevante.

Markdown no tiene sintaxis nativa para leyendas visibles, así que si necesitas un pie de imagen tendrás que recurrir a HTML, con las limitaciones que eso implica según dónde publiques. Lo tienes explicado en agregar leyendas a una imagen.

Los enlaces tienen que decir a dónde van

Igual que con los encabezados, los lectores de pantalla permiten pedir la lista de todos los enlaces de la página. Imagina esa lista cuando el documento está lleno de "haz clic aquí", "leer más" y "este enlace".

El texto del enlace tiene que funcionar por sí solo, sacado de su frase:

Mal:  Para configurar el entorno, [haz clic aquí](/guia).
Bien: Consulta la [guía de configuración del entorno](/guia).

Hay dos detalles más que conviene cuidar. Evita usar la URL desnuda como texto del enlace, porque el lector de pantalla puede acabar deletreando una dirección larguísima. Y si un enlace abre en una pestaña nueva, avísalo en el texto, porque el cambio de contexto sin previo aviso desorienta. Sobre esto último, revisa definir el target de los enlaces.

Las tablas son para datos, no para maquetar

En Markdown la primera fila de una tabla es siempre la fila de encabezado, y eso es justo lo que permite a un lector de pantalla anunciar "columna Precio, valor 39 euros" en lugar de recitar celdas sueltas sin contexto.

De ahí se deducen dos cosas. La primera es que una tabla siempre debe llevar encabezados con sentido, no dejarlos vacíos ni rellenarlos con guiones. La segunda es que usar una tabla para colocar dos bloques de texto en paralelo destroza esa lectura, porque convierte una maquetación en datos que no lo son.

Si lo que necesitas es alinear o distribuir contenido, ese es trabajo del CSS o de la plantilla, no de una tabla. Para el resto, formatear tablas cubre la sintaxis y sus límites.

Ten en cuenta también que las tablas anchas son un problema de accesibilidad por sí mismas en pantallas pequeñas. Si una tabla tiene ocho columnas, plantéate si no funcionaría mejor como una lista de definiciones o como varias tablas más pequeñas.

Las listas tienen que ser listas de verdad

Una lista escrita con guiones se convierte en una lista real en el HTML, y el lector de pantalla anuncia cuántos elementos tiene antes de empezar. Esa información es útil: te dice si te esperan tres puntos o veinte.

Cuando en cambio simulas una lista poniendo un guión o un asterisco a mano dentro de un párrafo, esa información se pierde y el resultado se lee como un bloque de texto corrido.

Lo mismo aplica al anidamiento: si una sublista está mal indentada, se rompe la relación entre el elemento padre y sus hijos. Tienes los detalles en anidar listas.

Los emojis, con moderación

Los emojis no son invisibles para un lector de pantalla. Lo habitual es que los anuncie en voz alta con el nombre asociado al carácter, de modo que un ✅ se convierte en "marca de verificación" y un 🚀 en "cohete". El comportamiento exacto varía según el lector, el navegador y la configuración de cada persona, así que no puedes dar por hecho ni que se lean ni que se omitan.

Esa incertidumbre tiene dos consecuencias prácticas. La primera es que un emoji a mitad de frase puede interrumpir la lectura con una descripción que no encaja en la sintaxis de la oración. La segunda, y más molesta, es que una ristra de emojis seguidos se convierte en una retahíla larga antes de que llegue el contenido de verdad.

No se trata de renunciar a ellos, sino de colocarlos donde no estorben, normalmente al final de una línea, y de no usarlos nunca como único portador de información. Si un ✅ significa "compatible" y un ❌ significa "no compatible", escríbelo también con palabras. Puedes consultar la lista completa en la página de emojis.

El color y el formato no son información

Este es el mismo principio ampliado: ninguna información puede depender de un único canal sensorial.

Si marcas en rojo las opciones obsoletas, quien no distingue ese color no recibe el mensaje. Si pones en negrita los campos obligatorios, quien escucha el documento puede no percibir el énfasis en absoluto, porque no todos los lectores de pantalla anuncian el formato por defecto.

La solución siempre es la misma: añade una palabra. "Obsoleto", "obligatorio", "recomendado". El color y la negrita refuerzan el mensaje, pero nunca lo sustituyen. Esto pesa especialmente en técnicas como cambiar el color del texto, que además dependen de HTML y pueden desaparecer al publicar.

Vídeos, GIFs y contenido incrustado

El contenido en movimiento merece atención aparte. Un GIF animado que se repite en bucle puede resultar incómodo para personas con sensibilidad al movimiento, y en casos extremos el parpadeo rápido es un riesgo real para personas con epilepsia fotosensible.

La recomendación práctica es evitar las animaciones que arrancan solas y se repiten sin fin, y sustituir el GIF por un vídeo con controles siempre que se pueda, para que quien lo vea decida cuándo empieza. Lo tienes en insertar GIFs e insertar vídeos.

Con los vídeos, lo esencial son los subtítulos, y conviene acompañarlos de un resumen en texto de lo que se explica. Ese resumen sirve además a quien no puede o no quiere reproducir el vídeo en ese momento.

Cómo comprobarlo sin ser experto

No hace falta una auditoría formal para detectar los problemas gordos. Con tres pruebas caseras cubres la mayor parte del terreno.

La primera es mirar el HTML que genera tu Markdown. Al fin y al cabo, eso es lo que van a recibir las tecnologías de asistencia, y ahí se ve de un vistazo si los encabezados salen con el nivel que esperabas, si las imágenes llevan su atributo alt y si la tabla tiene una fila de encabezado de verdad. Puedes hacerlo pegando el texto en el conversor de Markdown a HTML y leyendo el resultado.

La segunda es recorrer la página publicada usando solo el teclado, saltando de elemento en elemento con el tabulador. Si en algún momento no sabes dónde está el foco, o llegas a algo con lo que no puedes interactuar, ahí tienes un problema.

La tercera es escuchar el documento. Todos los sistemas operativos traen un lector de pantalla integrado, y no necesitas dominarlo: basta con activarlo y oír los primeros párrafos. Es incómodo al principio y tremendamente revelador, porque lo que en pantalla parecía obvio se convierte en una sucesión de "enlace, enlace, imagen, marca de verificación" que no se entiende.

Si mantienes documentación en un sitio estático, además puedes automatizar parte de esto en el proceso de publicación, igual que se automatiza el linting del propio Markdown. Lo tienes cubierto en automatizar tareas con Markdown.

Una comprobación rápida antes de publicar

Cuando termines un documento, este repaso corto detecta la mayoría de los problemas:

¿Los encabezados bajan de nivel sin saltos y describen su sección?
¿Todas las imágenes informativas tienen un texto alternativo que aporta algo, y las decorativas lo tienen vacío?
¿Los textos de los enlaces se entienden fuera de contexto?
¿Las tablas tienen encabezados reales y contienen datos, no maquetación?
¿Hay información que dependa solo del color, de la negrita o de un emoji?
¿El contenido en movimiento se puede detener?

Un truco que funciona sorprendentemente bien: mira el documento en texto plano, sin renderizar. Si entendiéndolo así conserva todo el sentido, es que la estructura está bien puesta.