Cómo Insertar Imágenes en Markdown

Aprenda todo sobre el uso de imágenes en documentos Markdown: desde la sintaxis básica hasta técnicas avanzadas, incluyendo optimización, accesibilidad, diseño responsivo y resolución de problemas. Ideal para desarrolladores, redactores técnicos y creadores de contenido.

Denis Rasulev ·   · 
Cómo Insertar Imágenes en Markdown

El contenido visual es crucial para que la documentación y las entradas de blog resulten atractivas. Los estudios demuestran que los lectores tienen un 65% más de probabilidades de recordar la información cuando va acompañada de imágenes relevantes. Esta guía te mostrará todo lo que necesitas saber para trabajar con imágenes en Markdown, desde la inserción básica hasta las técnicas de formato avanzadas.

Markdown es un lenguaje de marcado sencillo y fácil de usar que puede utilizarse para dar formato a casi cualquier documento. Si es la primera vez que utiliza Markdown, puede empezar por The Markdown Guide.

Supongamos que las imágenes que necesitas están en la carpeta images:

 ├─ images/
     └─ picture.jpg
     └─ picture-2.jpg
     └─ picture-three.jpg
 ├─ README.md

👉 Consejo profesional: Tenga en cuenta que si el nombre del archivo contiene corchetes o cualquier otro carácter especial, entonces la imagen puede no mostrarse en el documento renderizado. Si quieres saber cómo nombrar correctamente los archivos para proyectos web, echa un vistazo a estas directrices para nombres de archivo en proyectos web.

Entonces, ¿cómo añadir una imagen en markdown desde un archivo local? La primera forma de insertar una imagen local en un documento markdown es utilizar la siguiente sintaxis:

![Descripción de la imagen](/images/picture.jpg)

👉 Consejo profesional: Utilice siempre barras inclinadas (/) en las rutas, incluso en sistemas Windows, para garantizar la compatibilidad entre plataformas. El texto entre corchetes (“Descripción de la imagen”) es el llamado texto alternativo, que es importante por las siguientes razones:

  1. Para la accesibilidad. Los programas lectores de pantalla lo leen. Por ejemplo, para los discapacitados visuales.
  2. Este texto se mostrará en lugar de la imagen si el archivo de imagen no se puede cargar por cualquier motivo.
  3. Proporciona contexto y una descripción de la imagen para los motores de búsqueda, ayudándoles a encontrarla.

La parte entre paréntesis es la ruta al archivo. Fíjese en la primera / delante de images. Sin este símbolo, su documento puede mostrarse normalmente en su ordenador, pero una vez subido a un servidor en Internet, puede dejar de mostrarse. Esta es una de las principales razones por las que ocurre esto.

La segunda forma de mostrar una imagen local en una publicación markdown es utilizar la etiqueta image en el cuerpo del documento:

<image src="/images/picture.jpg" alt="Descripción de la imagen">

Una de las ventajas de este método es que permite utilizar funciones adicionales de control de imágenes. Los detalles dependen del recurso en el que publique el documento.

Cualquiera de los dos métodos le dará los resultados que desea, así que la elección es suya.

¿Cómo añadir una imagen a Markdown desde un enlace? Cuando necesites insertar una imagen que esté alojada en algún lugar de Internet, sólo tienes que utilizar un enlace a la imagen:

![Descripción de la imagen](https://picsum.photos/800/600)

o

<image src="https://picsum.photos/800/600" alt="Descripción de la imagen">

Descripción de la imagen](https://picsum.photos/800/600)

Si pasas el ratón por encima de esta imagen, verás que aparece un texto alternativo.

Texto alternativo eficaz

Un texto alternativo eficaz mejora la accesibilidad y el SEO. Compare estos ejemplos:

  • Texto alternativo pobre: ![image](/images/picture.jpg)

  • Texto alternativo bueno: ![Gráfico de barras que muestra el crecimiento mensual de las ventas de enero a junio de 2024, con un aumento del 25%](/images/picture.jpg)

Para imágenes complejas, utilice ARIA label (Método HTML):

<img
  src="/images/complex-diagram.jpg"
  alt="Descripción de la imagen"
  aria-label="Descripción detallada del diagrama y su significado"
>

Método HTML (recomendado)

Para un control preciso de las dimensiones:

<img src="/images/picture.jpg" alt="Description" width="500" height="300">

Medida nativa

Algunos procesadores de Markdown (como GitHub) admiten el dimensionamiento en línea, pero compruebe la compatibilidad:

![](image.jpg =100x200)

O sólo en anchura:

![](image.jpg =500x)

La compatibilidad con esta sintaxis varía según el procesador markdown, así que consulta la documentación de tu plataforma.

Mejores prácticas para la optimización de imágenes

  1. Selección del formato de archivo:
  • JPG: Para fotografías
  • PNG: Para capturas de pantalla e imágenes con transparencia
  • SVG: Para logotipos e iconos
  • WebP: Para navegadores modernos (con fallback)
  1. Dimensiones recomendadas
  • Imágenes de entradas de blog: 1200px-1600px de ancho
  • Miniaturas: 150px-300px ancho
  • Imágenes destacadas: 1600px-2000px ancho
  1. Directrices sobre el tamaño de los archivos:
  • Imágenes héroe: < 200 KB
  • Imágenes dentro del contenido: < 100 KB
  • Miniaturas: < 30 KB

Los pies de imagen son una parte importante de las imágenes en un documento markdown porque proporcionan información adicional al lector. Entonces, ¿cómo añadir un pie de foto a una imagen en markdown? Para añadir un título a una imagen utilizando la sintaxis markdown, basta con añadir el texto entre comillas, separado por un espacio:

![Descripción de la imagen](/images/picture.jpg "Text under the image")

O con HTML, puede establecer el atributo figcaption dentro de figure:

<figure>
  <img src="/images/picture.jpg" width="800" height="600" alt="Descripción de la imagen">
  <figcaption>Texto bajo la imagen</figcaption>
</figure>
Descripción de la imagen
Texto bajo la imagen

A veces es necesario añadir un marco alrededor de una imagen. Por ejemplo, si la imagen y la página tienen el mismo fondo y es necesario separar visualmente la imagen. Una imagen en formato markdown no tiene la posibilidad de añadir estilos de diseño, por lo que esto no es posible aquí.

Puede intentar añadir un atributo especial a la etiqueta img como en el código siguiente:

<img src="/images/picture.jpg" border="5px solid red" />

Pero, por desgracia, eso tampoco funcionará. El marco no se mostrará. Entonces, ¿cómo añadir un marco a una imagen en markdown? Hay una solución y una bastante inusual. Encontrada en StackOverflow. Todo lo que tienes que hacer es rodear la etiqueta image con otra - kbd:

<kbd>
  <img src="/images/picture.jpg" width="800" height="600" alt="Descripción de la imagen" />
</kbd>

Descripción de la imagen

Aunque no es un mal truco, es poco visible y bastante extraño para mi gusto. Hay una forma mejor de añadir un borde alrededor de una imagen en markdown. Puede utilizar el estilo en línea (pero se requiere soporte CSS). Esto le da un conjunto mucho más amplio de opciones y más control sobre el aspecto.

<figure>
  <img
    src="https://picsum.photos/800/600"
    width="800" height="600"
    alt="Descripción de la imagen"
    style="border: 2px solid red; border-radius: 5px; padding: 5px;">
  <figcaption>Texto bajo la imagen</figcaption>
</figure>

o esto también funcionará:

<img 
  src="/images/picture.jpg" 
  width="800" height="600" 
  alt="Descripción de la imagen" 
  style="border: 2px solid red; border-radius: 5px; padding: 5px;"
>
Descripción de la imagen
Texto bajo la imagen

Para hacer que las imágenes sean clicables en markdown, puede utilizar la construcción estándar:

[![Alt text](/path/to/thumbnail.jpg)](https://denshub.com)

Alt text

Si hace clic en esta imagen, se abrirá el blog Den’s Hub en una nueva ventana.

Para ofrecer una experiencia móvil aún mejor, puedes crear varias copias de tu imagen con distintos tamaños y utilizar lo siguiente:

<img 
  src="/images/picture.jpg"
  srcset="/images/picture-300.jpg 300w,
          /images/picture-600.jpg 600w,
          /images/picture-900.jpg 900w"
  sizes="(max-width: 600px) 300px,
         (max-width: 900px) 600px,
         900px"
  alt="Descripción de la imagen"
>
  1. Las imágenes no se cargan
  • Compruebe las rutas de los archivos (es importante distinguir entre mayúsculas y minúsculas)
  • Compruebe los permisos de los archivos
  • Asegúrese de que los caracteres especiales de la URL están codificados correctamente.
  1. Diseños rotos
  • Utilice dimensiones relativas (%, vw) en lugar de píxeles fijos
  • Tenga en cuenta las restricciones de ancho máximo
  • Pruebas en diferentes tamaños de pantalla
  1. Incluye siempre un texto alternativo significativo
  2. Optimice las imágenes antes de subirlas
  3. Pruebe en diferentes dispositivos
  4. Utilice formatos de archivo adecuados
  5. Mantener una nomenclatura coherente
  6. Tenga en cuenta el diseño adaptable
  7. Mantener organizadas las rutas de las imágenes
  8. Utilice nombres de archivo descriptivos

Recuerda que, aunque Markdown está diseñado para la simplicidad, siempre puedes recurrir a HTML cuando necesites un mayor control sobre la presentación de las imágenes. La clave está en encontrar el equilibrio adecuado entre facilidad de mantenimiento y funcionalidad para tu caso de uso específico.

😎

 Blog, Howto, Markdown, Images
Publicado en Aug 18, 2019