Изображения в Markdown

Ниже правила для документации на этом движке (MkDocs Material).

Куда класть картинки

Рекомендуемая структура:

docs/
  assets/
    images/
      quick-start-login.webp
      architecture-diagram.webp

Как вставлять

Базовый вариант:

![Экран входа](assets/images/quick-start-login.webp)

Если страница лежит в подпапке (например, docs/guides/...), используйте ../:

![Схема](../assets/images/architecture-diagram.webp)

С ограничением размера через атрибуты:

![Схема](../assets/images/architecture-diagram.webp){ width="900" loading=lazy }

Кликабельное превью:

[![Схема](../assets/images/architecture-diagram.webp){ width="520" loading=lazy }](../assets/images/architecture-diagram.webp)

Как не раздувать документацию

1. Используйте webp (или avif) вместо png/jpg, где возможно.
2. Сжимайте изображения перед коммитом.
3. Ограничивайте ширину до 1400-1800px для скриншотов интерфейса.
4. Добавляйте версию в имя файла (page-v2.webp), чтобы изменения сразу подхватывались.

Пример сжатия через ImageMagick:

magick input.png -resize "1600x>" -strip -quality 82 docs/assets/images/input.webp

Пример через cwebp:

cwebp -q 82 input.png -o docs/assets/images/input.webp

Почему картинки быстро подхватываются

• mkdocs serve отслеживает изменения файлов и перезагружает страницу автоматически.
• Для production: меняйте имя файла при заметном обновлении картинки (cache busting по имени файла).