6.0 KiB
Обработка ресурсов
Ссылки на статические ресурсы
Все файлы Markdown компилируются в компоненты Vue и обрабатываются Vite. Вы можете, и должны, ссылаться на любые ресурсы, используя относительные URL:
Вы можете ссылаться на статические ресурсы в ваших файлах разметки, компоненты *.vue в теме, стили и обычные файлы .css, используя абсолютные пути (основанные на корне проекта) или относительные пути (основанные на вашей файловой системе). Последнее похоже на поведение, к которому вы привыкли, если использовали Vite, Vue CLI или file-loader в webpack.
Распространённые типы файлов изображений, мультимедиа и шрифтов определяются и включаются в качестве ресурсов автоматически.
::: tip Связанные файлы не рассматриваются как ресурсы
PDF-файлы или другие документы, на которые есть ссылки в файлах с разметкой, не рассматриваются автоматически как ресурсы. Чтобы сделать связанные файлы доступными, вы должны вручную поместить их в каталог public вашего проекта.
:::
Все ссылающиеся ресурсы, включая те, которые используют абсолютные пути, будут скопированы в выходной каталог с хэшированным именем файла в производственной сборке. Ресурсы, на которые никогда не ссылались, не будут скопированы. Изображения размером менее 4 КБ будут вставляться в формате base64 — это можно настроить с помощью опции конфигурации vite.
Все статические ссылки на пути, включая абсолютные пути, должны быть основаны на структуре ваших рабочих каталогов.
Директория public
Иногда вам может понадобиться предоставить статические ресурсы, на которые нет прямых ссылок ни в одном из компонентов Markdown или темы, или вы можете захотеть предоставить определённые файлы с оригинальным именем. Примерами таких файлов являются robots.txt, favicon.ico и иконки PWA.
Вы можете поместить эти файлы в директорию public в директории с исходными файлами. Например, если корень вашего проекта — ./docs, и вы используете стандартное расположение исходного каталога, то ваш публичный каталог будет ./docs/public.
Ресурсы, размещённые в public, будут скопированы в корень выходного каталога как есть.
Обратите внимание, что вы должны ссылаться на файлы, размещённые в public, используя корневой абсолютный путь — например, public/icon.png всегда должен упоминаться в исходном коде как /icon.png.
Базовый URL
Если ваш сайт развёрнут на URL-адресе, не являющемся корневым, вам нужно установить параметр base в файле .vitepress/config.js. Например, если вы планируете развернуть свой сайт на https://foo.github.io/bar/, то параметр base следует установить на '/bar/' (он всегда должен начинаться и заканчиваться слэшем).
Все пути к статическим ресурсам автоматически обрабатываются с учётом различных значений конфигурации base. Например, если в вашей разметке есть абсолютная ссылка на ресурс в директории public:
В этом случае вам не нужно обновлять его при изменении значения конфигурации base.
Однако если вы создаете компонент темы, который динамически ссылается на активы, например, изображение, атрибут src которого основан на значении конфигурации темы:
<img :src="theme.logoPath" />
В этом случае рекомендуется обернуть путь с помощью хелпера withBase, предоставляемого VitePress:
<script setup>
import { withBase, useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<img :src="withBase(theme.logoPath)" />
</template>