Как добавить изображение в Markdown:восклицательный знак, alt-текст, путь.

Синтаксис

![Alt text](path/to/image.png "Optional title")

• Alt-текст в квадратных скобках описывает изображение для программ чтения с экрана и показывается, если картинка не загрузилась. Пишите, что на картинке, а не «изображение».
• Путь идёт в круглых скобках. Если в нём есть пробелы, пишите их как %20 или заключите путь в угловые скобки.
• Title — необязательный текст в кавычках, обычно он показывается как подсказка при наведении.

Работает и ссылочный стиль, он убирает длинные адреса из текста:

![Logo][logo]

[logo]: https://example.com/logo.png "DotMD logo"

Относительные пути и где лежит файл

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

docs/
  spec.md
  assets/
    flow.png

то изображение в spec.md — это ![Flow](assets/flow.png). Из файла на папку выше пишите docs/assets/flow.png, а из папки ниже — ../assets/flow.png. На GitHub путь, начинающийся с /, отсчитывается от корня репозитория. Храните изображения рядом с документом, в папке assets, чтобы при переносе папки переносились и картинки.

Имена файлов изображений на серверах Linux чувствительны к регистру, хотя Mac регистр не различает; это частая причина, почему картинка работает локально и пропадает в сети.

Как задать размер изображения

У самого Markdown размера нет. Используйте HTML-тег img с шириной, а высота подстроится по пропорциям:

<img src="assets/screen.png" alt="Settings window" width="400">

Ширина и высота задаются в пикселях, а процент, например width="50%", работает в большинстве приложений. GitHub поддерживает этот тег в README и комментариях. Некоторые приложения принимают размер и в alt-тексте, например ![Screenshot|400](assets/screen.png). Эта форма пришла из Obsidian, и DotMD её понимает, но другие приложения покажут |400 как часть alt-текста, поэтому для файла, который должен работать везде, используйте HTML-тег. В ячейке таблицы вертикальную черту нужно писать как \|.

Выравнивание и подписи

Выравнивание и подписи — тоже HTML. Чтобы выровнять изображение по центру, поместите его в абзац с align:

<p align="center">
  <img src="assets/logo.png" alt="Logo" width="200">
</p>

Для подписи используйте figure с figcaption:

<figure>
  <img src="assets/flow.png" alt="Request flow" width="500">
  <figcaption>Figure 1. The request flow.</figcaption>
</figure>

Не каждое приложение сохраняет эти теги: GitHub сохраняет большинство, а DotMD показывает оба. Если нужна подпись, которая работает везде, поставьте под изображением строку курсивом: *Figure 1. The request flow.*.

Кликабельное изображение и другие приёмы

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

[![Build status](https://example.com/badge.svg)](https://example.com/builds)

Так делают бейджи в начале README. Чтобы показать другую картинку в тёмной теме, используйте элемент picture с <source media="(prefers-color-scheme: dark)">, если приложение это поддерживает.

Alt-текст, размер файла и форматы

Пишите alt-текст так, будто описываете картинку по телефону: Settings window with the Sync option turned on говорит больше, чем screenshot. Для чисто декоративного изображения оставьте скобки пустыми, чтобы программа чтения с экрана его пропустила.

PNG подходит для скриншотов и диаграмм, JPEG для фотографий, SVG для логотипов и линейной графики, и держите файлы небольшими: скриншот на 6 МБ замедляет README и репозиторий. Большинство приложений показывают анимированные GIF так же, как любое другое изображение.

Почему изображение не показывается

• Путь неверный. Проверьте его от папки Markdown-файла и проверьте регистр в имени файла.
• Нет восклицательного знака. Без него получится ссылка, а не картинка.
• Неэкранированный пробел в пути.
• Локальный файл на странице в сети. Путь к файлу на вашем диске работает только на вашем диске.
• Заблокированное внешнее изображение. Некоторые приложения не загружают картинки из сети, пока вы не разрешите.

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

Вопросы об изображениях в Markdown

Другие вопросы