Как вставлять изображения в Markdown

Узнай все о работе с изображениями в документах Markdown: от базового синтаксиса до продвинутых техник, включая оптимизацию, доступность, отзывчивый дизайн и устранение неполадок. Идеально подходит для разработчиков, технических писателей и создателей контента.

Денис Расулев · Nov 10, 2024 ·

Случайная фотка с сайта Picsum.photos

Визуальный контент крайне важен для создания увлекательной документации и постов в блогах. Исследования показывают, что читатели на 65% чаще запоминают информацию, когда она сопровождается соответствующими изображениями. Это руководство покажет тебе все, что нужно знать о работе с изображениями в Markdown, начиная с базовой вставки и заканчивая продвинутыми техниками форматирования.

Сам по себе Markdown - это простой и удобный язык разметки, который можно использовать для форматирования практически любого документа. Если ты новичок в Markdown, начни с The Markdown Guide.

Локальные изображения

Предположим, что нужные тебе изображения находятся в папке images:

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

👉 Совет: Имей в виду, что если имя файла содержит скобки или любые другие специальные символы, то изображение может не отобразиться в финальном документе. Если ты хочешь узнать, как правильно называть файлы для веб-проектов, почитай Рекомендации по наименованию файлов для веб-проектов.

Итак, как добавить изображение в маркдаун из локального файла? Первый способ вставить локальное изображение в markdown документ - использовать следующий синтаксис:

![Описание изображения](/images/picture.jpg)

👉 Совет: Всегда используй прямые слэши (/) в путях, даже в системах Windows, чтобы обеспечить совместимость на разных платформах. Текст в квадратных скобках («Описание изображения») - это так называемый альтернативный текст, который важен по следующим причинам:

Для доступности. Программы для чтения с экрана читают это. Например, для тех, у кого слабое зрение.
Этот текст будет отображаться вместо картинки, если файл с изображением по каким-либо причинам не может быть загружен.
Он обеспечивает контекст и описание изображения для поисковых систем, помогая им найти его.

Часть в круглых скобках - это путь к файлу. Обрати внимание на самый первый / перед images. Без этого символа твой документ может нормально отображаться на твоем компьютере, но после загрузки на сервер в Интернете картинка перестанет отображаться в документе. Отсутствие первого слэша - одна из основных причин, почему так происходит.

Второй способ отобразить локальное изображение в markdown публикации - это использовать тег image в теле документа:

<image src="/images/picture.jpg" alt="Описание изображения">

Одно из преимуществ этого метода заключается в том, что таким образом ты можешь использовать дополнительные функции управления изображениями. Специфика зависит от ресурса, на котором ты публикуешь документ.

Любой из этих методов даст тебе желаемый результат, так что выбор за тобой.

Внешние изображения

Как добавить изображение в Markdown из ссылки? Когда тебе нужно вставить изображение, размещенное где-то в интернете, просто используй ссылку на него:

![Описание изображения](https://picsum.photos/800/600)

или

<image src="https://picsum.photos/800/600" alt="Описание изображения">

Описание изображения

Если ты наведешь мышку на это изображение, то увидишь альтернативный текст.

Эффективный альтернативный текст

Эффективное составление alt-текста повышает доступность и SEO. Сравни эти примеры:

Плохой Alt-текст: ![картинка](/images/picture.jpg).
Хороший Alt-текст: ![График, показывающий ежемесячный рост продаж на 25% с января по июнь 2024 года](/images/picture.jpg).

Для сложных изображений используй ARIA Labels (HTML Method):

<img 
  src="/images/complex-diagram.jpg" 
  alt="Описание изображения"
  aria-label="Подробное описание диаграммы и ее значение"
>

Установка размера и оптимизация изображения

HTML метод (рекомендуется)

Для точного контроля над размерами:

<img src="/images/picture.jpg" alt="Описание изображения" width="500" height="300">

Маркдаун синтаксис.

Некоторые процессоры Markdown (например, GitHub) поддерживают аттрибуты размеров, но уточни это:

![](image.jpg =100x200)

Или можно установить только ширину:

![](image.jpg =500x)

Поддержка такого синтаксиса варьируется в зависимости от процессора markdown, поэтому проверь документацию своей платформы.

Лучшие практики оптимизации изображений

Выбор формата файла:

JPG: для фотографий
PNG: для скриншотов и изображений с прозрачностью
SVG: для логотипов и иконок
WebP: для современных браузеров (с возможностью возврата).

Рекомендуемые размеры:

Изображения для постов в блоге: 1200px-1600px в ширину
Миниатюры: 150px-300px в ширину
Изображения статей: 1600px-2000px в ширину

Рекомендации по размеру файлов:

Изображения героев: < 200 КБ
Изображения в контенте: < 100 КБ
Миниатюры: < 30 КБ

Расширенное форматирование

Добавление подписей

Подписи к изображениям - важная часть изображений в документе markdown, потому что они предоставляют читателю дополнительную информацию. Итак, как добавить подпись к изображению в markdown? Чтобы задать подпись к изображению с помощью синтаксиса markdown, просто добавь текст в кавычках, разделенных пробелом:

![Описание изображения](/images/picture.jpg "Текст под изображением")

Или же в HTML ты можешь задать атрибут figcaption внутри figure:

<figure>
  <img src="/images/picture.jpg" width="800" height="600" alt="Описание изображения">
  <figcaption>Текст под изображением</figcaption>
</figure>

Описание изображения — Текст под изображением

Добавление рамок и границ

Иногда тебе нужно добавить рамку вокруг изображения. Например, если изображение и страница имеют одинаковый фон, а картинку нужно визуально разделить. У изображения в формате markdown нет возможности добавить стили оформления, поэтому здесь это невозможно.

Ты можешь попробовать добавить специальный атрибут к тегу img, как в коде ниже:

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

Но, увы, это тоже не сработает. Рамка не будет отображаться. Итак, как добавить рамку к изображению в markdown? Решение есть, и довольно необычное. Найдено на StackOverflow. Все, что тебе нужно сделать, - это окружить тег image еще одним - kbd:

<kbd>
  <img src="/images/picture.jpg" width="800" height="600" alt="Описание изображения" />
</kbd>

Это неплохой прием, но он плохо виден и, на мой вкус, довольно странный. Есть лучший способ добавить границу вокруг изображения в маркдаун. Ты можешь использовать встроенные стили (но для этого необходима поддержка CSS). Это дает тебе гораздо более широкий набор опций и больший контроль над внешним видом.

<figure>
  <img
    src="https://picsum.photos/800/600"
    width="800" height="600"
    alt="Описание изображения"
    style="border: 2px solid red; border-radius: 5px; padding: 5px;">
  <figcaption>Текст под изображением</figcaption>
</figure>

или это тоже подойдет:

<img 
  src="/images/picture.jpg" 
  width="800" height="600" 
  alt="Описание изображения" 
  style="border: 2px solid red; border-radius: 5px; padding: 5px;"
>

Создание ссылок на изображения

Чтобы сделать изображения кликабельными в markdown, ты можешь использовать стандартную конструкцию:

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

Если ты нажмешь на это изображение, то в новом окне откроется блог Den’s Hub.

Респонсивные изображения

Чтобы обеспечить лучшее юзабилити на мобильных устройствах, ты можешь создать несколько копий своего изображения с разными размерами и использовать следующую конструкцию:

<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="Описание изображения"
>

Поиск и устранение неисправностей

Изображения не загружаются

Проверь пути к файлам (чувствительность к регистру имеет значение).
Проверь права доступа к файлам
Убедись в правильности кодировки URL для специальных символов.

Неработающие макеты

Используй относительные размеры (%, vw) вместо фиксированных пикселей.
Учитывай ограничения по максимальной ширине
Тестируй на разных размерах экрана

Краткий обзор лучших практик

Всегда включай осмысленное описание изображения
Оптимизируй изображения перед загрузкой
Тестируй на разных устройствах
Используй подходящие форматы файлов
Поддерживай последовательное именование
Учитывай отзывчивый (responsive) дизайн
Следи за тем, чтобы пути изображений были упорядочены
Используй описательные имена файлов

Дополнительные ресурсы

Помни, что хотя Markdown создан для простоты, ты всегда можешь вернуться к HTML, когда тебе понадобится больше контроля над представлением изображений. Главное - найти правильный баланс между удобством и функциональностью для твоего конкретного случая использования.

😎