Обработка ресурсов
Ссылки на статические ресурсы
Все файлы Markdown компилируются в компоненты Vue и обрабатываются Vite. Вы можете, и должны, ссылаться на любые ресурсы, используя относительные URL:
Вы можете ссылаться на статические ресурсы в ваших файлах разметки, ваших компонентах *.vue в теме, стилях и обычных файлах .css, используя абсолютные пути (основанные на корне проекта) или относительные пути (основанные на вашей файловой системе). Последнее похоже на поведение, к которому вы привыкли, если использовали Vite, Vue CLI или file-loader в webpack.
Распространённые типы файлов изображений, мультимедиа и шрифтов определяются и включаются в качестве ресурсов автоматически.
Связанные файлы не рассматриваются как ресурсы
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. Например, если вы планируете разместить сайт по адресу https://foo.github.io/bar/, то base должен быть установлен в '/bar/'.
Ссылки на статические ресурсы автоматически корректируются под base, поэтому абсолютная ссылка на файл в public работает с любым base и никогда не требует обновления:
Внимания требуют только динамически формируемые пути — например, изображение, src которого основан на значении конфигурации темы. Оборачивайте такие пути хелпером withBase, чтобы base подставлялся во время выполнения:
<script setup>
import { withBase, useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<img :src="withBase(theme.logoPath)" />
</template>Раздача ресурсов через CDN
Чтобы раздавать сгенерированные ресурсы — скрипты, стили, шрифты и изображения, импортированные из Markdown или компонентов — с другого домена, отличного от страниц, задайте assetsBase:
export default {
base: '/',
assetsBase: 'https://cdn.example.com/'
}Загрузите директорию assets из результата сборки на CDN так, чтобы она была доступна по адресу https://cdn.example.com/assets/, а остальную часть результата разверните на своём сайте как обычно. Файлы в public ссылаются относительно base и остаются вместе со страницами.
Поскольку это значение часто зависит от окружения, его также можно передать через командную строку:
vitepress build docs --assetsBase "$CDN_URL"Требуется CORS
Модульные скрипты всегда загружаются в режиме CORS, поэтому кросс-доменный CDN должен отвечать соответствующим заголовком Access-Control-Allow-Origin.