|
|
# Обработка ресурсов {#asset-handling}
|
|
|
|
|
|
## Ссылки на статические ресурсы {#referencing-static-assets}
|
|
|
|
|
|
Все файлы Markdown компилируются в компоненты Vue и обрабатываются [Vite](https://vitejs.dev/guide/assets.html). Вы можете, **и должны**, ссылаться на любые ресурсы, используя относительные URL:
|
|
|
|
|
|
```md
|
|
|
|
|
|
```
|
|
|
|
|
|
Вы можете ссылаться на статические ресурсы в ваших файлах разметки, компоненты `*.vue` в теме, стили и обычные файлы `.css`, используя абсолютные пути (основанные на корне проекта) или относительные пути (основанные на вашей файловой системе). Последнее похоже на поведение, к которому вы привыкли, если использовали Vite, Vue CLI или `file-loader` в webpack.
|
|
|
|
|
|
Распространенные типы файлов изображений, мультимедиа и шрифтов определяются и включаются в качестве ресурсов автоматически.
|
|
|
|
|
|
::: tip Связанные файлы не рассматриваются как ресурсы
|
|
|
PDF-файлы или другие документы, на которые есть ссылки в файлах с разметкой, не рассматриваются автоматически как ресурсы. Чтобы сделать связанные файлы доступными, вы должны вручную поместить их в каталог [`public`](#the-public-directory) вашего проекта.
|
|
|
:::
|
|
|
|
|
|
Все ссылающиеся ресурсы, включая те, которые используют абсолютные пути, будут скопированы в выходной каталог с хэшированным именем файла в производственной сборке. Ресурсы, на которые никогда не ссылались, не будут скопированы. Изображения размером менее 4 КБ будут вставляться в формате base64 — это можно настроить с помощью опции конфигурации [`vite`](../reference/site-config#vite).
|
|
|
|
|
|
Все **статические** ссылки на пути, включая абсолютные пути, должны быть основаны на структуре ваших рабочих каталогов.
|
|
|
|
|
|
## Директория `public` {#the-public-directory}
|
|
|
|
|
|
Иногда вам может понадобиться предоставить статические ресурсы, на которые нет прямых ссылок ни в одном из компонентов Markdown или темы, или вы можете захотеть предоставить определённые файлы с оригинальным именем. Примерами таких файлов являются `robots.txt`, `favicon.ico` и иконки PWA.
|
|
|
|
|
|
Вы можете поместить эти файлы в директорию `public` в [директории с исходными файлами](./routing#source-directory). Например, если корень вашего проекта — `./docs`, и вы используете стандартное расположение исходного каталога, то ваш публичный каталог будет `./docs/public`.
|
|
|
|
|
|
Ресурсы, размещённые в `public`, будут скопированы в корень выходного каталога как есть.
|
|
|
|
|
|
Обратите внимание, что вы должны ссылаться на файлы, размещённые в `public`, используя корневой абсолютный путь — например, `public/icon.png` всегда должен упоминаться в исходном коде как `/icon.png`.
|
|
|
|
|
|
## Базовый URL {#base-url}
|
|
|
|
|
|
Если ваш сайт развёрнут на URL-адресе, не являющемся корневым, вам нужно установить параметр `base` в файле `.vitepress/config.js`. Например, если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то параметр `base` следует установить на `'/bar/'` (он всегда должен начинаться и заканчиваться слэшем).
|
|
|
|
|
|
Все пути к статическим ресурсам автоматически обрабатываются с учётом различных значений конфигурации `base`. Например, если в вашей разметке есть абсолютная ссылка на ресурс в директории `public`:
|
|
|
|
|
|
```md
|
|
|
|
|
|
```
|
|
|
|
|
|
В этом случае вам **не** нужно обновлять его при изменении значения конфигурации `base`.
|
|
|
|
|
|
Однако если вы создаете компонент темы, который динамически ссылается на активы, например, изображение, атрибут `src` которого основан на значении конфигурации темы:
|
|
|
|
|
|
```vue
|
|
|
<img :src="theme.logoPath" />
|
|
|
```
|
|
|
|
|
|
В этом случае рекомендуется обернуть путь с помощью [хелпера `withBase`](../reference/runtime-api#withbase), предоставляемого VitePress:
|
|
|
|
|
|
```vue
|
|
|
<script setup>
|
|
|
import { withBase, useData } from 'vitepress'
|
|
|
|
|
|
const { theme } = useData()
|
|
|
</script>
|
|
|
|
|
|
<template>
|
|
|
<img :src="withBase(theme.logoPath)" />
|
|
|
</template>
|
|
|
```
|
