msb-public
/
vitepress
mirror of https://github.com/vuejs/vitepress
2
1
Code Issues Projects Releases Wiki Activity

docs(ru): update translations (#5422)

Browse Source
main
Bugo 6 days ago committed by GitHub
parent 7afe929937
commit 3e681e2ffd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
14 changed files with 323 additions and 67 deletions
Show Stats Download Patch File Download Diff File

37
docs/ru/guide/asset-handling.md
Unescape View File

@ -36,23 +36,15 @@ PDF-файлы или другие документы, на которые ес
## Базовый URL {#base-url} ## Базовый URL {#base-url}
Если ваш сайт развёрнут на URL-адресе, не являющемся корневым, вам нужно установить параметр `base` в файле `.vitepress/config.js`. Например, если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то параметр `base` следует установить на `'/bar/'` (он всегда должен начинаться и заканчиваться слэшем). Если ваш сайт развёрнут не в корне URL, задайте параметр [`base`](../reference/site-config#base). Например, если вы планируете разместить сайт по адресу `https://foo.github.io/bar/`, то `base` должен быть установлен в `'/bar/'`.
Все пути к статическим ресурсам автоматически обрабатываются с учётом различных значений конфигурации `base`. Например, если в вашей разметке есть абсолютная ссылка на ресурс в директории `public`: Ссылки на статические ресурсы автоматически корректируются под `base`, поэтому абсолютная ссылка на файл в `public` работает с любым `base` и никогда не требует обновления:
```md ```md
![Изображение](/image-inside-public.png) ![Изображение](/image-inside-public.png)
``` ```
В этом случае вам **не** нужно обновлять его при изменении значения конфигурации `base`. Внимания требуют только динамически формируемые пути — например, изображение, `src` которого основан на значении конфигурации темы. Оборачивайте такие пути хелпером [`withBase`](../reference/runtime-api#withbase), чтобы `base` подставлялся во время выполнения:
Однако если вы создаете компонент темы, который динамически ссылается на активы, например, изображение, атрибут `src` которого основан на значении конфигурации темы:
```vue
<img :src="theme.logoPath" />
```
В этом случае рекомендуется обернуть путь с помощью [хелпера `withBase`](../reference/runtime-api#withbase), предоставляемого VitePress:
```vue ```vue
<script setup> <script setup>
@ -65,3 +57,26 @@ const { theme } = useData()
<img :src="withBase(theme.logoPath)" /> <img :src="withBase(theme.logoPath)" />
</template> </template>
``` ```
## Раздача ресурсов через CDN {#serving-assets-from-a-cdn}
Чтобы раздавать сгенерированные ресурсы — скрипты, стили, шрифты и изображения, импортированные из Markdown или компонентов — с другого домена, отличного от страниц, задайте [`assetsBase`](../reference/site-config#assetsbase):
```ts
export default {
base: '/',
assetsBase: 'https://cdn.example.com/'
}
```
Загрузите директорию `assets` из результата сборки на CDN так, чтобы она была доступна по адресу `https://cdn.example.com/assets/`, а остальную часть результата разверните на своём сайте как обычно. Файлы в `public` ссылаются относительно `base` и остаются вместе со страницами.
Поскольку это значение часто зависит от окружения, его также можно передать через командную строку:
```sh
vitepress build docs --assetsBase "$CDN_URL"
```
::: warning Требуется CORS
Модульные скрипты всегда загружаются в режиме CORS, поэтому кросс-доменный CDN должен отвечать соответствующим заголовком `Access-Control-Allow-Origin`.
:::

29
docs/ru/guide/custom-theme.md
Unescape View File

@ -33,12 +33,17 @@ interface Theme {
*/ */
Layout: Component Layout: Component
/** /**
* Улучшение экземпляра приложения Vue * Расширяем экземпляр приложения Vue
* @optional * @optional
*/ */
enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void> enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
/** /**
* Расширяем другую тему, вызывая её `enhanceApp` перед нашей * Выполняется внутри `setup()` корневого компонента
* @optional
*/
setup?: () => void
/**
* Расширяем другую тему, вызывая её `enhanceApp` и `setup` перед нашими
* @optional * @optional
*/ */
extends?: Theme extends?: Theme
@ -88,6 +93,26 @@ export default {
Верните `false` из `onBeforeRouteChange` или `onBeforePageLoad`, чтобы отменить переход. Верните `false` из `onBeforeRouteChange` или `onBeforePageLoad`, чтобы отменить переход.
Хук `setup` выполняется внутри `setup()` корневого компонента, поэтому вызовы Composition API (`onMounted`, `watch`, composables и т. д.) работают там без необходимости оборачивать компонент layout:
```ts [.vitepress/theme/index.ts]
import { watch } from 'vue'
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
export default {
extends: DefaultTheme,
setup() {
const { page } = useData()
watch(() => page.value.relativePath, (path) => {
console.log('now viewing', path)
})
}
}
```
При использовании `extends` `setup` каждой темы выполняется в порядке от базовой к производной, как и `enhanceApp`. Он также выполняется во время SSR/SSG-рендеринга, поэтому код, зависящий от браузера, следует размещать внутри `onMounted`.
Экспорт по умолчанию является единственным контрактом для пользовательской темы, и только свойство `Layout` является обязательным. Таким образом, технически тема VitePress может быть простой, как один компонент Vue. Экспорт по умолчанию является единственным контрактом для пользовательской темы, и только свойство `Layout` является обязательным. Таким образом, технически тема VitePress может быть простой, как один компонент Vue.
Внутри компонент макета работает так же, как и обычное приложение Vite + Vue 3. Обратите внимание, что тема также должна быть [SSR-совместимой](./ssr-compat). Внутри компонент макета работает так же, как и обычное приложение Vite + Vue 3. Обратите внимание, что тема также должна быть [SSR-совместимой](./ssr-compat).

111
docs/ru/guide/deploy.md
Unescape View File

@ -54,6 +54,30 @@ outline: deep
**Пример:** Если вы используете Github (или GitLab) Pages и развёртываете на `user.github.io/repo/`, то установите `base` на `/repo/`. **Пример:** Если вы используете Github (или GitLab) Pages и развёртываете на `user.github.io/repo/`, то установите `base` на `/repo/`.
## Переносимые сборки (относительный base) {#relocatable-builds-relative-base}
Когда конечный URL сайта неизвестен на момент сборки — шлюз IPFS (`https://gateway/ipfs/<cid>/…`), Wayback Machine, общая папка, документация, встроенная в приложение — установите `base` равным `'./'`:
```ts
export default {
base: './'
}
```
Каждая страница затем ссылается на ресурсы и другие страницы относительно своего собственного расположения, а клиентский рантайм восстанавливает реальную точку монтирования при загрузке страницы. Одна и та же сборка работает из **любого** подпути без пересборки — в том числе из нескольких одновременно — с полностью работающими маршрутизацией, поиском и предзагрузкой.
Открытие сгенерированных HTML-файлов напрямую из файловой системы (`file://`) также работает как стилизованный, полностью навигируемый статический сайт. Браузеры блокируют JavaScript-модули при использовании `file://`, поэтому гидратации там нет — интерактивные функции вроде поиска остаются неактивными, при этом весь предварительно отрендеренный контент и ссылки продолжают работать.
Несколько важных моментов:
- Держите [`cleanUrls`](../reference/site-config#cleanurls) выключенным (значение по умолчанию): переносимому выводу нужны ссылки, оканчивающиеся на `.html`, поскольку нет сервера для переписывания «красивых» URL.
- `404.html` генерируется для корневой глубины. Хосты, отдающие его как fallback для URL произвольной глубины, отрендерят его без стилей (для неизвестной глубины нет корректного относительного префикса).
- Записи [`head`](../reference/site-config#head) выводятся как есть, как и всегда — избегайте в них корне-абсолютных путей вроде `/favicon.ico` и предпочитайте абсолютные URL или `transformHead`.
- Сырые HTML-теги `<a>` в Markdown сохраняют `href` в том виде, как написаны — используйте синтаксис Markdown-ссылок для сайт-абсолютных ссылок (встроенные источники `<img>` проходят через пайплайн ресурсов и обрабатываются корректно).
- Ссылки, созданные [`createContentLoader`](./data-loading#createcontentloader), остаются сайт-абсолютными (их HTML встраивается в другие страницы, поэтому единого корректного относительного префикса не существует) — они разрешаются только для корневого монтирования.
- Отдавайте страницы по их каноническим URL: корень как `/dir/` (не `/dir`), и без добавленных завершающих слэшей у URL страниц. Относительный префикс разрешается относительно URL, который браузер реально показывает, а практически все статические хостинги уже канонизируют именно так.
- Dev-сервер всегда отдаёт по `/`; относительное поведение применяется к продакшен-сборке.
## Заголовки кэша HTTP {#http-cache-headers} ## Заголовки кэша HTTP {#http-cache-headers}
Если вы контролируете HTTP-заголовки на своем рабочем сервере, можно настроить заголовки `cache-control` для достижения лучшей производительности при повторных посещениях. Если вы контролируете HTTP-заголовки на своем рабочем сервере, можно настроить заголовки `cache-control` для достижения лучшей производительности при повторных посещениях.
@ -229,6 +253,8 @@ Cache-Control: max-age=31536000,immutable
- main - main
``` ```
<!-- keep headings sorted alphabetically, leave nginx at the end -->
### Azure ### Azure
1. Следуйте [официальной документации](https://docs.microsoft.com/ru-ru/azure/static-web-apps/build-configuration). 1. Следуйте [официальной документации](https://docs.microsoft.com/ru-ru/azure/static-web-apps/build-configuration).
@ -290,62 +316,77 @@ Cache-Control: max-age=31536000,immutable
Вы можете развернуть свой проект VitePress на [Hostinger](https://www.hostinger.com/web-apps-hosting), следуя этим [инструкциям](https://www.hostinger.com/support/how-to-deploy-a-nodejs-website-in-hostinger/). При настройке параметров сборки выберите VitePress в качестве фреймворка и укажите корневой каталог `./docs`. Вы можете развернуть свой проект VitePress на [Hostinger](https://www.hostinger.com/web-apps-hosting), следуя этим [инструкциям](https://www.hostinger.com/support/how-to-deploy-a-nodejs-website-in-hostinger/). При настройке параметров сборки выберите VitePress в качестве фреймворка и укажите корневой каталог `./docs`.
### Kinsta
Вы можете развернуть свой сайт VitePress на [Kinsta](https://kinsta.com/static-site-hosting/), следуя этим [инструкциям](https://kinsta.com/docs/vitepress-static-site-example/).
### Stormkit ### Stormkit
Вы можете развернуть свой проект VitePress на [Stormkit](https://www.stormkit.io), следуя следующим [инструкциям](https://stormkit.io/blog/how-to-deploy-vitepress). Вы можете развернуть свой проект VitePress на [Stormkit](https://www.stormkit.io), следуя следующим [инструкциям](https://stormkit.io/blog/how-to-deploy-vitepress).
### Surge ### Surge
1. После запуска `npm run docs:build` выполните эту команду для развёртывания: После запуска `npm run docs:build` выполните эту команду для развёртывания на [Surge](https://surge.sh):
```sh ```sh
npx surge docs/.vitepress/dist npx surge docs/.vitepress/dist
``` ```
### harvis
После выполнения `npm run docs:build` выполните эту команду для развёртывания на [harvis](https://harvis.dev):
```sh
npx harvis docs/.vitepress/dist
```
### Nginx ### Nginx
Вот пример конфигурации блока сервера Nginx. Эта настройка включает сжатие gzip для общих текстовых ресурсов, правила обслуживания статических файлов вашего сайта VitePress с правильными заголовками кэширования и обработку параметра `cleanUrls: true`. Вот пример конфигурации блока сервера Nginx. Эта настройка включает сжатие gzip для общих текстовых ресурсов, правила обслуживания статических файлов вашего сайта VitePress с правильными заголовками кэширования и обработку параметра `cleanUrls: true`.
```nginx ```nginx
server { map $uri $cache_control {
gzip on; ~^/assets/ "public, max-age=31536000, immutable";
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; default "no-cache";
}
listen 80; server {
listen 8080;
listen [::]:8080;
server_name _; server_name _;
index index.html;
location / { root /usr/share/nginx/html;
# расположение контента index index.html;
root /app; charset utf-8;
server_tokens off;
# точные совпадения -> обратные чистые URL-адреса -> папки -> не найдены absolute_redirect off;
try_files $uri $uri.html $uri/ =404;
# несуществующие страницы gzip on;
error_page 404 /404.html; gzip_vary on;
gzip_comp_level 5;
gzip_min_length 1024;
gzip_types
application/javascript
application/json
application/manifest+json
image/svg+xml
text/css
text/javascript
text/plain;
add_header Cache-Control $cache_control always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
# папка без index.html вызывает ошибку 403 в этой настройке location / {
error_page 403 /404.html; try_files $uri $uri.html $uri/index.html =404;
}
# настройка заголовков кэширования location ~ ^(?<page>.+)/$ {
# файлы в папке с ресурсами имеют хэши имён файлов if (-f $document_root$page.html) {
location ~* ^/assets/ { return 301 $page$is_args$args;
expires 1y;
add_header Cache-Control "public, immutable";
} }
try_files $page/index.html =404;
} }
error_page 404 /404.html;
} }
``` ```
Эта конфигурация предполагает, что ваш собранный сайт VitePress находится в директории `/app`. При необходимости измените директиву `root`, если файлы вашего сайта расположены в другом месте.
::: warning Не используйте index.html по умолчанию
Разрешение try_files не должно использовать index.html, как это делается в других приложениях Vue. Это может привести к недопустимому состоянию страницы.
:::
Дополнительную информацию можно найти в официальной документации [Nginx](https://nginx.org/ru/docs/), а также в следующих обсуждениях: [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235), а также в [блоге Mehdi Merah](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings).

40
docs/ru/guide/extending-default-theme.md
Unescape View File

@ -40,6 +40,46 @@ export default DefaultTheme
См. [переменные CSS темы по умолчанию](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css), которые можно переопределить. См. [переменные CSS темы по умолчанию](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css), которые можно переопределить.
### Навбар {#navbar}
Навбар отрисовывает единую поверхность фона, управляемую CSS-переменными, поэтому его вид можно изменить, не затрагивая внутреннюю реализацию компонента:
```css
:root {
/* высота бара и фон */
--vp-nav-height: 4rem;
--vp-nav-bg-color: var(--vp-c-bg);
/* фон, когда находимся поверх главной страницы (без прокрутки);
установите var(--vp-nav-bg-color), чтобы отказаться от прозрачного оформления */
--vp-nav-home-bg-color: transparent;
/* фильтр, применяемый к контенту за баром */
--vp-nav-backdrop-filter: none;
/* нижняя линия бара и фон мобильного меню */
--vp-nav-divider-color: var(--vp-c-gutter);
--vp-nav-screen-bg-color: var(--vp-c-bg);
}
```
Например, навбар в стиле матового стекла:
```css
:root {
--vp-nav-bg-color: color-mix(in srgb, var(--vp-c-bg) 65%, transparent);
--vp-nav-backdrop-filter: saturate(180%) blur(8px);
}
```
Та же обработка распространяется и на локальную навигацию: `--vp-local-nav-bg-color` по умолчанию следует за цветом поверхности навбара, и там, где два бара соприкасаются, они разделяют единую размытую поверхность, так что стекло остаётся непрерывным между ними.
::: warning
`backdrop-filter` заметно влияет на производительность прокрутки, особенно на больших или High-DPI экранах. При использовании полупрозрачного бара также проверьте контрастность текста поверх содержимого страницы. Safari 17 и более ранние версии не применяют управляемые переменными backdrop-фильтры, поэтому показывают полупрозрачный цвет без размытия.
:::
Когда элементы навигации не помещаются в доступную ширину, они перемещаются в меню `⋯` в конце навбара вместо того, чтобы обрезаться, начиная с ссылок на соцсети, переключателя внешнего вида и переключателя локали, за которыми следуют элементы навигации справа налево. Подпись этой кнопки можно локализовать с помощью [`extraMenuLabel`](../reference/default-theme-config#extramenulabel).
## Использование различных шрифтов {#using-different-fonts} ## Использование различных шрифтов {#using-different-fonts}
VitePress использует [Inter](https://rsms.me/inter/) в качестве шрифта по умолчанию, и будет включать шрифты в вывод сборки. Шрифт также автоматически загружается в производство. Однако это может быть нежелательно, если вы хотите использовать другой основной шрифт. VitePress использует [Inter](https://rsms.me/inter/) в качестве шрифта по умолчанию, и будет включать шрифты в вывод сборки. Шрифт также автоматически загружается в производство. Однако это может быть нежелательно, если вы хотите использовать другой основной шрифт.

2
docs/ru/guide/frontmatter.md
Unescape View File

@ -36,6 +36,8 @@ editLink: true
Содержание руководства Содержание руководства
``` ```
Обращения к свойствам вроде `{{ $frontmatter.title }}` разрешаются в процессе рендеринга Markdown, поэтому значение также попадает в локальный индекс поиска, в вывод [загрузчика контента](./data-loading#createcontentloader), в якоря заголовков — заголовок выше получает `id="docs-with-vitepress"` — и в цели ссылок, записанные без пробелов вокруг выражения, например `[text]({{$frontmatter.link}})`. Остальные выражения вычисляются Vue во время выполнения как обычно, а обёртывание выражения в [`v-pre`](./using-vue#escaping) выводит его буквально.
Вы также можете получить доступ к метаданным текущей страницы в `<script setup>` с помощью [хелпера `useData()`](../reference/runtime-api#usedata). Вы также можете получить доступ к метаданным текущей страницы в `<script setup>` с помощью [хелпера `useData()`](../reference/runtime-api#usedata).
## Альтернативные форматы метаданных {#alternative-frontmatter-formats} ## Альтернативные форматы метаданных {#alternative-frontmatter-formats}

2
docs/ru/guide/markdown.md
Unescape View File

@ -449,6 +449,8 @@ VitePress также поддерживает [Оповещения в стил
> [!CAUTION] > [!CAUTION]
> Негативные потенциальные последствия того или иного действия. > Негативные потенциальные последствия того или иного действия.
По умолчанию цвета оповещений совпадают с цветами GitHub, при этом caution и danger отображаются красным. Включите [`themeConfig.gradedContainers`](../reference/default-theme-config#gradedcontainers), чтобы использовать градуированную шкалу серьёзности: danger (красный), warning (оранжевый) и caution (жёлтый). Обратите внимание, что `[!DANGER]` — это расширение VitePress и на GitHub будет отображаться как обычная цитата.
## Подсветка синтаксиса в блоках кода {#syntax-highlighting-in-code-blocks} ## Подсветка синтаксиса в блоках кода {#syntax-highlighting-in-code-blocks}
VitePress использует [Shiki](https://github.com/shikijs/shiki) для выделения синтаксиса языка в блоках кода Markdown с помощью цветного текста. Shiki поддерживает широкий спектр языков программирования. Всё, что вам нужно сделать, это добавить правильный псевдоним языка к начальным обратным кавычкам блока кода: VitePress использует [Shiki](https://github.com/shikijs/shiki) для выделения синтаксиса языка в блоках кода Markdown с помощью цветного текста. Shiki поддерживает широкий спектр языков программирования. Всё, что вам нужно сделать, это добавить правильный псевдоним языка к начальным обратным кавычкам блока кода:

2
docs/ru/reference/cli.md
Unescape View File

@ -45,6 +45,7 @@ vitepress build [root]
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--mpa` (экспериментально) | Сборка в режиме [MPA](../guide/mpa-mode) без гидратации на стороне клиента (`boolean`) | | `--mpa` (экспериментально) | Сборка в режиме [MPA](../guide/mpa-mode) без гидратации на стороне клиента (`boolean`) |
| `--base <path>` | Публичный базовый путь (по умолчанию: `/`) (`string`) | | `--base <path>` | Публичный базовый путь (по умолчанию: `/`) (`string`) |
| `--assetsBase <url>` | Префикс URL, с которого раздаются сгенерированные ресурсы, например CDN (`string`) |
| `--target <target>` | Транспилировать цель (по умолчанию: `"modules"`) (`string`) | | `--target <target>` | Транспилировать цель (по умолчанию: `"modules"`) (`string`) |
| `--outDir <dir>` | Выходной каталог относительно **cwd** (по умолчанию: `<root>/.vitepress/dist`) (`string`) | | `--outDir <dir>` | Выходной каталог относительно **cwd** (по умолчанию: `<root>/.vitepress/dist`) (`string`) |
| `--assetsInlineLimit <number>` | Статический встроенный порог ресурса base64 в байтах (по умолчанию: `4096`) (`number`) | | `--assetsInlineLimit <number>` | Статический встроенный порог ресурса base64 в байтах (по умолчанию: `4096`) (`number`) |
@ -64,6 +65,7 @@ vitepress preview [root]
| Параметр | Описание | | Параметр | Описание |
| --------------- | ----------------------------------------------------- | | --------------- | ----------------------------------------------------- |
| `--base <path>` | Публичный базовый путь (по умолчанию: `/`) (`string`) | | `--base <path>` | Публичный базовый путь (по умолчанию: `/`) (`string`) |
| `--assetsBase <url>` | Префикс URL, с которого раздаются сгенерированные ресурсы, например CDN (`string`) |
| `--port <port>` | Номер порта (`number`) | | `--port <port>` | Номер порта (`number`) |
## `vitepress init` {#vitepress-init} ## `vitepress init` {#vitepress-init}

33
docs/ru/reference/default-theme-badge.md
Unescape View File

@ -11,21 +11,18 @@ description: Используйте компонент Badge для добавл
Вы можете использовать компонент `Badge`, который доступен глобально. Вы можете использовать компонент `Badge`, который доступен глобально.
```html ```html
### Заголовок <Badge type="info" text="по умолчанию" /> ### Заголовок ### Заголовок <Badge type="info" text="по умолчанию" />
<Badge type="tip" text="^1.9.0" /> ### Заголовок ### Заголовок <Badge type="tip" text="^1.9.0" />
<Badge type="warning" text="beta" /> ### Заголовок ### Заголовок <Badge type="warning" text="beta" />
<Badge type="danger" text="осторожно" /> ### Заголовок <Badge type="danger" text="устарело" />
``` ```
Приведённый выше код даёт такой результат: Приведённый выше код даёт такой результат:
### Заголовок <Badge type="info" text="по умолчанию" /> {#title} ### Заголовок <Badge type="info" text="по умолчанию" /> {#title}
### Заголовок <Badge type="tip" text="^1.9.0" /> {#title-1} ### Заголовок <Badge type="tip" text="^1.9.0" /> {#title-1}
### Заголовок <Badge type="warning" text="beta" /> {#title-2} ### Заголовок <Badge type="warning" text="beta" /> {#title-2}
### Заголовок <Badge type="danger" text="устарело" /> {#title-3}
### Заголовок <Badge type="danger" text="осторожно" /> {#title-3}
## Дочерние элементы {#custom-children} ## Дочерние элементы {#custom-children}
@ -47,9 +44,21 @@ description: Используйте компонент Badge для добавл
--vp-badge-info-text: var(--vp-c-text-2); --vp-badge-info-text: var(--vp-c-text-2);
--vp-badge-info-bg: var(--vp-c-default-soft); --vp-badge-info-bg: var(--vp-c-default-soft);
--vp-badge-note-border: transparent;
--vp-badge-note-text: var(--vp-c-note-1);
--vp-badge-note-bg: var(--vp-c-note-soft);
--vp-badge-tip-border: transparent; --vp-badge-tip-border: transparent;
--vp-badge-tip-text: var(--vp-c-brand-1); --vp-badge-tip-text: var(--vp-c-tip-1);
--vp-badge-tip-bg: var(--vp-c-brand-soft); --vp-badge-tip-bg: var(--vp-c-tip-soft);
--vp-badge-important-border: transparent;
--vp-badge-important-text: var(--vp-c-important-1);
--vp-badge-important-bg: var(--vp-c-important-soft);
--vp-badge-caution-border: transparent;
--vp-badge-caution-text: var(--vp-c-caution-1);
--vp-badge-caution-bg: var(--vp-c-caution-soft);
--vp-badge-warning-border: transparent; --vp-badge-warning-border: transparent;
--vp-badge-warning-text: var(--vp-c-warning-1); --vp-badge-warning-text: var(--vp-c-warning-1);
@ -70,7 +79,7 @@ interface Props {
// Когда передается `<slot>`, это значение игнорируется. // Когда передается `<slot>`, это значение игнорируется.
text?: string text?: string
// По умолчанию: `tip`. // По умолчанию `tip`. Соответствует цветам контейнеров/оповещений Markdown.
type?: 'info' | 'tip' | 'warning' | 'danger' type?: 'info' | 'note' | 'tip' | 'important' | 'caution' | 'warning' | 'danger'
} }
``` ```

31
docs/ru/reference/default-theme-config.md
Unescape View File

@ -254,6 +254,9 @@ export default {
{ icon: 'github', link: 'https://github.com/vuejs/vitepress' }, { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
{ icon: 'twitter', link: '...' }, { icon: 'twitter', link: '...' },
{ icon: 'discord', link: '/community', target: '_self' }, { icon: 'discord', link: '/community', target: '_self' },
// Вы можете использовать любую другую установленную в проекте коллекцию iconify
// в формате `collection:name` (например, после `npm add -D @iconify-json/lucide`):
{ icon: 'lucide:rss', link: '/feed.rss' },
// Можно добавить пользовательские иконки, передав SVG в виде строки: // Можно добавить пользовательские иконки, передав SVG в виде строки:
{ {
icon: { icon: {
@ -472,6 +475,27 @@ export interface DocFooter {
Можно использовать для настройки aria-метки кнопки переключения языка в панели навигации. Применяется только в том случае, если вы используете [i18n](../guide/i18n). Можно использовать для настройки aria-метки кнопки переключения языка в панели навигации. Применяется только в том случае, если вы используете [i18n](../guide/i18n).
## navMenuLabel
- Тип: `string`
- По умолчанию: `Main Navigation`
Может использоваться для настройки доступной метки основных ориентиров навигации (меню навбара и мобильное меню).
## mobileMenuLabel
- Тип: `string`
- По умолчанию: `Menu`
Может использоваться для настройки `aria-label` кнопки мобильного меню (гамбургер).
## extraMenuLabel
- Тип: `string`
- По умолчанию: `More options`
Может использоваться для настройки `aria-label` кнопки меню `⋯` в навбаре. Это меню собирает элементы навигации и элементы управления, которые не помещаются в бар при текущей ширине экрана.
## skipToContentLabel ## skipToContentLabel
- Тип: `string` - Тип: `string`
@ -486,6 +510,13 @@ export interface DocFooter {
Отображать ли значок внешней ссылки рядом с внешними ссылками в Markdown. Отображать ли значок внешней ссылки рядом с внешними ссылками в Markdown.
## gradedContainers
- Тип: `boolean`
- По умолчанию: `false`
Определяет, следует ли раскрашивать [пользовательские контейнеры](../guide/markdown#custom-containers), [оповещения в стиле GitHub](../guide/markdown#github-flavored-alerts) и бейджи по градуированной шкале серьёзности — danger красный, warning оранжевый, caution жёлтый. По умолчанию цвета соответствуют оповещениям GitHub, где caution использует красный цвет danger, а warning — жёлтый.
## `useLayout` <Badge type="info" text="composable" /> ## `useLayout` <Badge type="info" text="composable" />
Возвращает данные, относящиеся к макету. Возвращаемый объект имеет следующий тип: Возвращает данные, относящиеся к макету. Возвращаемый объект имеет следующий тип:

3
docs/ru/reference/default-theme-nav.md
Unescape View File

@ -215,6 +215,7 @@ export default {
Ваш компонент будет отображаться на панели навигации. VitePress предоставляет следующие дополнительные параметры компонента: Ваш компонент будет отображаться на панели навигации. VitePress предоставляет следующие дополнительные параметры компонента:
- `screenMenu`: необязательное булево значение, указывающее, находится ли компонент внутри мобильного навигационного меню - `screenMenu`: необязательный булев флаг, указывающий, находится ли компонент внутри мобильного навигационного меню
- `menu`: необязательный булев флаг, указывающий, находится ли компонент внутри выпадающей панели — например, меню `⋯`, в которое сворачиваются элементы навигации, не помещающиеся в бар. В обоих этих контекстах рендерите плоский список вместо всплывающего флайаута, который в итоге оказался бы вложенным внутрь панели
Пример можно посмотреть в тестах e2e [здесь](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress). Пример можно посмотреть в тестах e2e [здесь](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress).

14
docs/ru/reference/default-theme-search.md
Unescape View File

@ -27,11 +27,11 @@ export default defineConfig({
В качестве альтернативы можно использовать [Algolia DocSearch](#algolia-search) или некоторые плагины сообщества, например: В качестве альтернативы можно использовать [Algolia DocSearch](#algolia-search) или некоторые плагины сообщества, например:
- <https://www.npmjs.com/package/vitepress-plugin-search> - <https://npmx.dev/package/vitepress-plugin-pagefind>
- <https://www.npmjs.com/package/vitepress-plugin-pagefind> - <https://npmx.dev/package/vitepress-plugin-typesense>
- <https://www.npmjs.com/package/@orama/plugin-vitepress> - <https://npmx.dev/package/vitepress-plugin-cloudflare-ai-search>
- <https://www.npmjs.com/package/vitepress-plugin-typesense>
- <https://www.npmjs.com/package/vitepress-plugin-cloudflare-ai-search> <!-- - <https://npmx.dev/package/@orama/plugin-vitepress> -- replace with zbsearch one when published -->
### i18n {#local-search-i18n} ### i18n {#local-search-i18n}
@ -112,6 +112,10 @@ export default defineConfig({
Подробнее в [документации MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html). Подробнее в [документации MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html).
::: info Идентификаторы документов
Идентификаторы документов поиска (в том виде, в котором их видят `searchOptions.filter`, `boostDocument` и необработанный индекс) — это сайт-относительные пути вида `/guide/page.html#section`; они не включают [`base`](../reference/site-config#base). Тема разрешает их относительно `base` при отображении результатов.
:::
### Пользовательский рендерер содержимого {#custom-content-renderer} ### Пользовательский рендерер содержимого {#custom-content-renderer}
Вы можете настроить функцию, используемую для отображения содержимого в формате Markdown перед его индексацией: Вы можете настроить функцию, используемую для отображения содержимого в формате Markdown перед его индексацией:

2
docs/ru/reference/frontmatter-config.md
Unescape View File

@ -63,7 +63,7 @@ description: VitePress
- Тип: `HeadConfig[]` - Тип: `HeadConfig[]`
Укажите дополнительные теги, которые будут выводиться для текущей страницы. Они будут добавляться после других тегов внутри блока head, введённых в конфигурации сайта. Укажите дополнительные теги, которые будут выводиться для текущей страницы. Они [объединяются](./site-config#head) с тегами head, добавленными в конфигурации сайта.
```yaml ```yaml
--- ---

30
docs/ru/reference/runtime-api.md
Unescape View File

@ -136,6 +136,36 @@ router.onBeforeRouteChange = (to) => {
В пользовательских темах этот же экземпляр маршрутизатора доступен через [`enhanceApp`](../guide/custom-theme#theme-interface). В пользовательских темах этот же экземпляр маршрутизатора доступен через [`enhanceApp`](../guide/custom-theme#theme-interface).
## `useIcon` <Badge type="info" text="композабл" /> {#useicon}
- **Тип**: `(icon: MaybeRefOrGetter<string | { svg: string } | undefined>, el?: MaybeRefOrGetter<HTMLElement | null>) => ComputedRef<string | undefined>`
Отрисовывает иконку [iconify](https://iconify.design/) через пайплайн иконок VitePress. Принимает полностью квалифицированное имя `collection:name` (разрешается относительно пакетов `@iconify-json/*` в зависимостях вашего проекта) и возвращает класс, который нужно поставить на элемент — `vpi-<collection>-<name>`.
Во время SSR имя регистрируется в [`SSGContext`](./site-config#postrender) страницы, поэтому сборка добавляет стили иконки в сгенерированную таблицу стилей; в режиме разработки иконки отдаются dev-сервером по требованию из локально установленных коллекций. Ни одна иконка никогда не загружается с внешнего сервиса.
```vue
<script setup>
import { useIcon } from 'vitepress'
import { useTemplateRef } from 'vue'
const el = useTemplateRef('el')
const iconClass = useIcon('lucide:rocket', el)
</script>
<template>
<span ref="el" :class="iconClass" />
</template>
```
Передайте шаблонную ссылку элемента, несущего класс, чтобы dev-режим мог разрешить на нём иконку. Элементу нужны правила `mask`, которые поставляются с темой по умолчанию; в кастомной теме без них dev применяет встроенный эквивалент, а сгенерированная таблица стилей включает базовые правила с нулевой специфичностью для продакшена.
При использовании темы по умолчанию компонент `VPIcon` из `vitepress/theme` оборачивает этот композабл (а также принимает сырую строку `{ svg }`):
```vue-html
<VPIcon icon="lucide:rocket" />
```
Иконки, отрисовываемые только на клиенте (например, внутри `<ClientOnly />`), не могут быть собраны во время сборки — вместо этого перечислите их в [`icons.include`](./site-config#icons).
## `withBase` <Badge type="info" text="хелпер" /> {#withbase} ## `withBase` <Badge type="info" text="хелпер" /> {#withbase}
- **Тип**: `(path: string) => string` - **Тип**: `(path: string) => string`

54
docs/ru/reference/site-config.md
Unescape View File

@ -248,6 +248,13 @@ type HeadConfig =
| [string, Record<string, string>, string] | [string, Record<string, string>, string]
``` ```
Записи head из конфигурации сайта, [конфигурации локали](../guide/i18n), [конфигурации на уровне директории](#directory-level-overrides), [метаданные](./frontmatter-config#head) и [`transformHead`](#transformhead) объединяются в этом порядке. Более поздняя запись заменяет более раннюю с тем же ключом вместо того, чтобы добавляться к ней:
- Любой элемент с атрибутом `id` идентифицируется по своему `id`.
- Элемент `meta` без `id` идентифицируется по своему первому атрибуту, отличному от `content` (например, `name`, `property`, `http-equiv`), и значению этого атрибута.
Остальные элементы никогда не считаются повторяющимися и не заменяют друг друга. Чтобы отрисовать несколько тегов `meta`, которые имели бы одинаковый ключ, например несколько `<meta name="author">`, задайте каждому из них уникальный `id`
#### Пример: Добавление значка сайта {#example-adding-a-favicon} #### Пример: Добавление значка сайта {#example-adding-a-favicon}
```ts ```ts
@ -367,6 +374,8 @@ export default {
Базовый URL-адрес, по которому будет развёрнут сайт. Этот параметр необходимо задать, если вы планируете развернуть свой сайт по подпути, например, для страниц GitHub. Если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то вам следует установить base на `'/bar/'`. Он всегда должен начинаться и заканчиваться косой чертой. Базовый URL-адрес, по которому будет развёрнут сайт. Этот параметр необходимо задать, если вы планируете развернуть свой сайт по подпути, например, для страниц GitHub. Если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то вам следует установить base на `'/bar/'`. Он всегда должен начинаться и заканчиваться косой чертой.
Единственное исключение — `'./'`, которое создаёт [переносимую сборку](../guide/deploy#relocatable-builds-relative-base): страницы ссылаются на всё относительно своего собственного расположения, поэтому один и тот же результат сборки работает из любого подпути (шлюзы IPFS, архивы) без пересборки и остаётся просматриваемым при открытии напрямую из файловой системы.
Параметр `base` автоматически добавляется ко всем URL, которые начинаются с `/` в других опциях, поэтому вам нужно указать его только один раз. Параметр `base` автоматически добавляется ко всем URL, которые начинаются с `/` в других опциях, поэтому вам нужно указать его только один раз.
```ts ```ts
@ -375,6 +384,8 @@ export default {
} }
``` ```
Также может быть задан для отдельной сборки с помощью `vitepress build --base /base/`.
## Маршрутизация {#routing} ## Маршрутизация {#routing}
### cleanUrls {#cleanurls} ### cleanUrls {#cleanurls}
@ -456,6 +467,44 @@ export default {
} }
``` ```
### assetsBase
- Тип: `string`
- По умолчанию: `undefined`
Префикс URL, с которого раздаются сгенерированные ресурсы (всё, что находится под [`assetsDir`](#assetsdir)) — обычно CDN. Должен быть абсолютным URL, URL без указания протокола (начинающимся с `//`) или абсолютным путём от корня сайта (начинающимся с `/`); при отсутствии завершающего слэша он добавляется автоматически.
```ts
export default {
base: '/',
assetsBase: 'https://cdn.example.com/'
// скрипты, стили, шрифты и импортированные изображения разрешаются в
// https://cdn.example.com/assets/*
}
```
Итоговый URL ресурса — это `assetsBase`, объединённый с относительным путём файла в выводе, поэтому CDN должен зеркалировать структуру `outDir` (загрузите `outDir/assets`, чтобы он был доступен по адресу `<assetsBase>/assets/*`). HTML-страницы, ссылки Markdown, файлы [`public`](../guide/asset-handling#the-public-directory) и `hashmap.json` остаются на [`base`](#base).
Когда `assetsBase` указывает на другой домен, VitePress добавляет `crossorigin` к сгенерированным тегам script и preload — CDN должен отправлять `Access-Control-Allow-Origin` для домена вашего сайта (модульные скрипты всегда загружаются в режиме CORS).
Это влияет только на продакшен-сборки. Команда `vitepress preview` раздаёт значение `assetsBase`, заданное как путь от корня сайта (например, `/cdn/`), из локальной папки dist, а внешний адрес — запрашивает напрямую по настоящему URL. Значение также можно задать для отдельной сборки с помощью `vitepress build --assetsBase https://cdn.example.com/`.
### icons
- Тип: `{ include?: string[] }`
Опции для сгенерированных стилей иконок. Сборка собирает каждую иконку iconify, отрисованную во время SSR. Имена указываются полностью в формате `collection:name`, разрешаясь относительно пакетов `@iconify-json/*`, объявленных в зависимостях вашего проекта.
Иконки, отрисовываемые только на клиенте — внутри `<ClientOnly>` или после гидратации — невидимы для сбора во время SSR. Перечислите их в `include`, чтобы принудительно добавить в таблицу стилей:
```ts
export default {
icons: {
include: ['mdi:home', 'simple-icons:discord']
}
}
```
### cacheDir {#cachedir} ### cacheDir {#cachedir}
- Тип: `string` - Тип: `string`
@ -625,6 +674,7 @@ export default {
interface SSGContext { interface SSGContext {
content: string content: string
teleports?: Record<string, string> teleports?: Record<string, string>
vpIcons: Set<string>
[key: string]: any [key: string]: any
} }
``` ```
@ -639,6 +689,10 @@ interface SSGContext {
Не мутируйте ничего внутри `context`. Не мутируйте ничего внутри `context`.
::: :::
::: note
Ссылка на таблицу стилей иконок на этом этапе всё ещё содержит заглушку `vp-icons.__VP_ICONS_HASH__.css` — хеш содержимого появляется только после того, как отрендерены все страницы, и подставляется сразу после этого. Хуки, которые встраивают или проставляют отпечаток ресурсам в head, должны пропускать этот тег.
:::
```ts ```ts
export default { export default {
async transformHead(context) { async transformHead(context) {

Write Preview
Loading…
Cancel
Save