#Статические ресурсы

#Введение

В Rspress можно использовать следующие статические ресурсы:

• Изображения, видео и другие статические ресурсы, используемые в файлах MDX
• Изображение логотипа в левом верхнем углу сайта
• Иконка сайта
• Логотип на главной странице
• Прочие статические ресурсы

Далее мы поочерёдно рассмотрим, как использовать каждый из этих ресурсов.

import { defineConfig } from '@rspress/core';

export default defineConfig({
  root: 'docs',
});

#Статические ресурсы, используемые в файлах MDX

Вы можете импортировать статические ресурсы в файлах markdown (или mdx). Rspress построен поверх статических ресурсов Rsbuild.

#Обычные статические ресурсы

Например, если структура директорий выглядит следующим образом:

docs
├── guide
│   ├── index.mdx
│   └── demo.png

Если изображение находится в той же директории, что и markdown-файл, вы можете сослаться на него следующим образом:

![](./demo.png)

Конечно, вы также можете напрямую использовать тег <img> в файлах .mdx:

<img src="./demo.png" />

Оба варианта использования, описанные выше, будут преобразованы в:

import image from './demo.png';

<img src={image}>

Не только изображения, но вы также можете импортировать видео, аудио и другие статические ресурсы. Остальные способы использования полностью соответствуют Rsbuild.

#Папка public

Папка public в директории с документацией может использоваться для размещения статических ресурсов. Эти файлы не обрабатываются во время сборки и могут быть напрямую доступны по URL.

• При запуске dev-сервера эти ресурсы будут доступны по пути, соответствующему base (по умолчанию — /).
• При выполнении production-сборки эти файлы копируются в директорию сборки документации (outdir).

Например, в папку public можно поместить такие файлы, как robots.txt, manifest.json или favicon.ico.

Вот пример размещения статических ресурсов в папке public. Если корневая директория документации — docs, и структура директорий выглядит следующим образом:

docs
├── public
│   └── demo.png
├── index.mdx

В указанном выше файле index.mdx вы можете использовать абсолютный путь для ссылки на demo.png:

![](/demo.png)

Когда ваш сайт настроен с путём base и вы используете тег img с абсолютным путём, вам необходимо вручную добавить путь base к атрибуту src, используя функцию normalizeImagePath, предоставляемую из @rspress/core/runtime. Вот пример:

import { normalizeImagePath } from '@rspress/core/runtime';

<img src={normalizeImagePath('/demo.png')} />;

#Логотип в левом верхнем углу

В Rspress логотип в левом верхнем углу можно указать с помощью поля logo. Например:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  logo: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
});

Поле logo поддерживает как строковую, так и объектную конфигурацию.

Когда logo — строка, возможны следующие варианты:

• Внешняя ссылка — как в примере выше.
• Абсолютный путь, например /rspress-logo.png. В этом случае Rspress автоматически найдёт файл rspress-logo.png в папке public внутри корневой директории документов и отобразит его.
• Относительный путь, например ./docs/public/rspress-logo.png. В этом случае Rspress найдёт файл rspress-logo.png относительно корня проекта и отобразит его.

Если ваш сайт должен поддерживать тёмную тему, можно использовать объектную конфигурацию logo, например:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  logo: {
    light: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
    dark: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
  },
});

Здесь light — адрес логотипа в светлой теме, dark — адрес логотипа в тёмной теме. Способы их указания полностью совпадают с описанной выше строковой конфигурацией.

#Favicon

В Rspress иконку сайта можно указать через поле icon. Например:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  icon: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4',
});

Поле icon поддерживает строку или URL, доступны следующие варианты:

• Внешняя ссылка — как в примере выше.
• Абсолютный путь, например /favicon.ico. В этом случае Rspress автоматически найдёт файл favicon.ico в папке public внутри корневой директории документов и использует его.
• Относительный путь, например ./docs/public/favicon.ico. В этом случае Rspress найдёт файл favicon.ico относительно корня проекта.
• Протокол file:// или URL, например file:///local_path/favicon.ico. В этом случае Rspress напрямую использует локальный файл по абсолютному пути /local_path/favicon.ico.

#Логотип на главной странице

В метаданных главной страницы логотип можно указать через поле hero.image.src. Например:

---
pageType: home

hero:
  image:
    src: https://avatars.githubusercontent.com/u/56892468?s=200&v=4
    alt: Rspress
---

Здесь src — строка, поддерживаются следующие варианты:

• Внешняя ссылка — как в примере выше.
• Настроен как абсолютный путь, например /rspress-logo.png. В этом случае Rspress автоматически найдёт изображение rspress-logo.png в папке public вашей корневой директории документации и отобразит его.

#Другие статические ресурсы

В некоторых сценариях вам может понадобиться развернуть определённые специальные статические ресурсы, например, добавить файл конфигурации развёртывания _headers для Netlify, чтобы указать пользовательские HTTP-заголовки ответа.

В таком случае вы можете напрямую поместить эти статические ресурсы в директорию public корневой директории документации (например, docs). Во время процесса сборки проекта Rspress автоматически скопирует все ресурсы из public-директории в директорию сборки. Таким образом, ресурсы из public могут быть развернуты на сервере.