Перейти к основному содержимому

Вставка изображений Docusaurus

Руководство по работе с изображениями в Docusaurus 3.x

Структура статических файлов​

Docusaurus использует директорию static/ как корневую для всех статических ресурсов. Рекомендуемая структура:

website
├── static
│   └── img
│       ├── docs
│       │   └── getting-started
│       │       └── example.png
│       ├── blog
│       │   └── 2024-01-01
│       │       └── blog-image.jpg
│       └── common
│           └── logo.svg

Способы вставки изображений​

1. Markdown синтаксис​

![Альтернативный текст](/img/docs/getting-started/example.png)

2. Использование компонента MDX​

import Image from '@theme/IdealImage';

<Image img={require('/img/docs/getting-started/example.png')} />

3. Вставка с указанием размеров​

<img src="/img/docs/getting-started/example.png" alt="Альтернативный текст" width="300" height="200" />

Рекомендуемые плагины​

  1. @docusaurus/plugin-ideal-image

    npm install @docusaurus/plugin-ideal-image

    Конфигурация в docusaurus.config.js:

    module.exports = {
      plugins: [
        [
          '@docusaurus/plugin-ideal-image',
          {
            quality: 70,
            max: 1030,
            min: 640,
            steps: 2,
            disableInDev: false,
          },
        ],
      ],
    };

  2. image-size-transform-loader

    npm install image-size-transform-loader --save-dev

Настройка горячих клавиш в популярных редакторах​

VS Code​

  1. Откройте настройки сочетаний клавиш (Ctrl/Cmd + K, Ctrl/Cmd + S)
  2. Добавьте новое сочетание:
{
  "key": "ctrl+alt+v",
  "command": "editor.action.insertSnippet",
  "when": "editorTextFocus",
  "args": {
    "snippet": "![${1:alt text}](${2:${CLIPBOARD}})"
  }
}

JetBrains (WebStorm, IntelliJ IDEA)​

  1. Перейдите в Settings → Editor → Live Templates
  2. Создайте новый шаблон:
    • Abbreviation: img
    • Template text: ![$ALT$]($CLIPBOARD$)$END$
    • Applicable in: Markdown

Лучшие практики​

  1. Оптимизация изображений

    • Используйте форматы WebP для фотографий
    • SVG для векторной графики
    • PNG для скриншотов и изображений с текстом

  2. Именование файлов

    • Используйте kebab-case: my-screenshot.png
    • Добавляйте суффиксы размеров: hero-image-large.jpg

  3. Организация файлов

    • Группируйте изображения по разделам
    • Используйте отдельные директории для разных типов контента

  4. Альтернативный текст

    • Всегда предоставляйте информативный alt-текст
    • Описывайте содержимое изображения для SEO

  5. Отзывчивые изображения

    <img
      src="/img/logo.png"
      srcSet="/img/logo.png 1x, /img/logo@2x.png 2x"
      alt="Logo"
    />