From 3e681e2ffd89b84d017fe0516d4b3af365950abb Mon Sep 17 00:00:00 2001
From: Bugo <229402+dragomano@users.noreply.github.com>
Date: Sat, 5 Sep 2026 00:37:18 +0500
Subject: [PATCH] docs(ru): update translations (#5422)

---
 docs/ru/guide/asset-handling.md           |  37 +++++---
 docs/ru/guide/custom-theme.md             |  29 +++++-
 docs/ru/guide/deploy.md                   | 111 +++++++++++++++-------
 docs/ru/guide/extending-default-theme.md  |  40 ++++++++
 docs/ru/guide/frontmatter.md              |   2 +
 docs/ru/guide/markdown.md                 |   2 +
 docs/ru/reference/cli.md                  |   2 +
 docs/ru/reference/default-theme-badge.md  |  33 ++++---
 docs/ru/reference/default-theme-config.md |  31 ++++++
 docs/ru/reference/default-theme-nav.md    |   3 +-
 docs/ru/reference/default-theme-search.md |  14 ++-
 docs/ru/reference/frontmatter-config.md   |   2 +-
 docs/ru/reference/runtime-api.md          |  30 ++++++
 docs/ru/reference/site-config.md          |  54 +++++++++++
 14 files changed, 323 insertions(+), 67 deletions(-)

diff --git a/docs/ru/guide/asset-handling.md b/docs/ru/guide/asset-handling.md
index b2f26719..4cb0c0d4 100644
--- a/docs/ru/guide/asset-handling.md
+++ b/docs/ru/guide/asset-handling.md
@@ -36,23 +36,15 @@ PDF-файлы или другие документы, на которые ес
 
 ## Базовый 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
 ![Изображение](/image-inside-public.png)
 ```
 
-В этом случае вам **не** нужно обновлять его при изменении значения конфигурации `base`.
-
-Однако если вы создаете компонент темы, который динамически ссылается на активы, например, изображение, атрибут `src` которого основан на значении конфигурации темы:
-
-```vue
-<img :src="theme.logoPath" />
-```
-
-В этом случае рекомендуется обернуть путь с помощью [хелпера `withBase`](../reference/runtime-api#withbase), предоставляемого VitePress:
+Внимания требуют только динамически формируемые пути — например, изображение, `src` которого основан на значении конфигурации темы. Оборачивайте такие пути хелпером [`withBase`](../reference/runtime-api#withbase), чтобы `base` подставлялся во время выполнения:
 
 ```vue
 <script setup>
@@ -65,3 +57,26 @@ const { theme } = useData()
   <img :src="withBase(theme.logoPath)" />
 </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`.
+:::
diff --git a/docs/ru/guide/custom-theme.md b/docs/ru/guide/custom-theme.md
index 24d75bae..22da9f02 100644
--- a/docs/ru/guide/custom-theme.md
+++ b/docs/ru/guide/custom-theme.md
@@ -33,12 +33,17 @@ interface Theme {
    */
   Layout: Component
   /**
-   * Улучшение экземпляра приложения Vue
+   * Расширяем экземпляр приложения Vue
    * @optional
    */
   enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
   /**
-   * Расширяем другую тему, вызывая её `enhanceApp` перед нашей
+   * Выполняется внутри `setup()` корневого компонента
+   * @optional
+   */
+  setup?: () => void
+  /**
+   * Расширяем другую тему, вызывая её `enhanceApp` и `setup` перед нашими
    * @optional
    */
   extends?: Theme
@@ -88,6 +93,26 @@ export default {
 
 Верните `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.
 
 Внутри компонент макета работает так же, как и обычное приложение Vite + Vue 3. Обратите внимание, что тема также должна быть [SSR-совместимой](./ssr-compat).
diff --git a/docs/ru/guide/deploy.md b/docs/ru/guide/deploy.md
index 56cc8a0a..c9541f2f 100644
--- a/docs/ru/guide/deploy.md
+++ b/docs/ru/guide/deploy.md
@@ -54,6 +54,30 @@ outline: deep
 
 **Пример:** Если вы используете 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-заголовки на своем рабочем сервере, можно настроить заголовки `cache-control` для достижения лучшей производительности при повторных посещениях.
@@ -229,6 +253,8 @@ Cache-Control: max-age=31536000,immutable
        - main
    ```
 
+<!-- keep headings sorted alphabetically, leave nginx at the end -->
+
 ### Azure
 
 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`.
 
-### Kinsta
-
-Вы можете развернуть свой сайт VitePress на [Kinsta](https://kinsta.com/static-site-hosting/), следуя этим [инструкциям](https://kinsta.com/docs/vitepress-static-site-example/).
-
 ### Stormkit
 
 Вы можете развернуть свой проект VitePress на [Stormkit](https://www.stormkit.io), следуя следующим [инструкциям](https://stormkit.io/blog/how-to-deploy-vitepress).
 
 ### Surge
 
-1. После запуска `npm run docs:build` выполните эту команду для развёртывания:
+После запуска `npm run docs:build` выполните эту команду для развёртывания на [Surge](https://surge.sh):
 
-   ```sh
-   npx surge docs/.vitepress/dist
-   ```
+```sh
+npx surge docs/.vitepress/dist
+```
+
+### harvis
+
+После выполнения `npm run docs:build` выполните эту команду для развёртывания на [harvis](https://harvis.dev):
+
+```sh
+npx harvis docs/.vitepress/dist
+```
 
 ### Nginx
 
 Вот пример конфигурации блока сервера Nginx. Эта настройка включает сжатие gzip для общих текстовых ресурсов, правила обслуживания статических файлов вашего сайта VitePress с правильными заголовками кэширования и обработку параметра `cleanUrls: true`.
 
 ```nginx
-server {
-    gzip on;
-    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+map $uri $cache_control {
+    ~^/assets/  "public, max-age=31536000, immutable";
+    default     "no-cache";
+}
 
-    listen 80;
+server {
+    listen 8080;
+    listen [::]:8080;
     server_name _;
-    index index.html;
 
-    location / {
-        # расположение контента
-        root /app;
+    root /usr/share/nginx/html;
+    index index.html;
+    charset utf-8;
+    server_tokens off;
 
-        # точные совпадения -> обратные чистые URL-адреса -> папки -> не найдены
-        try_files $uri $uri.html $uri/ =404;
+    absolute_redirect off;
 
-        # несуществующие страницы
-        error_page 404 /404.html;
+    gzip on;
+    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 в этой настройке
-        error_page 403 /404.html;
+    location / {
+        try_files $uri $uri.html $uri/index.html =404;
+    }
 
-        # настройка заголовков кэширования
-        # файлы в папке с ресурсами имеют хэши имён файлов
-        location ~* ^/assets/ {
-            expires 1y;
-            add_header Cache-Control "public, immutable";
+    location ~ ^(?<page>.+)/$ {
+        if (-f $document_root$page.html) {
+            return 301 $page$is_args$args;
         }
+        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).
diff --git a/docs/ru/guide/extending-default-theme.md b/docs/ru/guide/extending-default-theme.md
index c07677a8..52e14d2e 100644
--- a/docs/ru/guide/extending-default-theme.md
+++ b/docs/ru/guide/extending-default-theme.md
@@ -40,6 +40,46 @@ export default DefaultTheme
 
 См. [переменные 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}
 
 VitePress использует [Inter](https://rsms.me/inter/) в качестве шрифта по умолчанию, и будет включать шрифты в вывод сборки. Шрифт также автоматически загружается в производство. Однако это может быть нежелательно, если вы хотите использовать другой основной шрифт.
diff --git a/docs/ru/guide/frontmatter.md b/docs/ru/guide/frontmatter.md
index 3c0ced5e..7f97ae16 100644
--- a/docs/ru/guide/frontmatter.md
+++ b/docs/ru/guide/frontmatter.md
@@ -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).
 
 ## Альтернативные форматы метаданных {#alternative-frontmatter-formats}
diff --git a/docs/ru/guide/markdown.md b/docs/ru/guide/markdown.md
index ae58bfb8..b3e702f8 100644
--- a/docs/ru/guide/markdown.md
+++ b/docs/ru/guide/markdown.md
@@ -449,6 +449,8 @@ VitePress также поддерживает [Оповещения в стил
 > [!CAUTION]
 > Негативные потенциальные последствия того или иного действия.
 
+По умолчанию цвета оповещений совпадают с цветами GitHub, при этом caution и danger отображаются красным. Включите [`themeConfig.gradedContainers`](../reference/default-theme-config#gradedcontainers), чтобы использовать градуированную шкалу серьёзности: danger (красный), warning (оранжевый) и caution (жёлтый). Обратите внимание, что `[!DANGER]` — это расширение VitePress и на GitHub будет отображаться как обычная цитата.
+
 ## Подсветка синтаксиса в блоках кода {#syntax-highlighting-in-code-blocks}
 
 VitePress использует [Shiki](https://github.com/shikijs/shiki) для выделения синтаксиса языка в блоках кода Markdown с помощью цветного текста. Shiki поддерживает широкий спектр языков программирования. Всё, что вам нужно сделать, это добавить правильный псевдоним языка к начальным обратным кавычкам блока кода:
diff --git a/docs/ru/reference/cli.md b/docs/ru/reference/cli.md
index 90497fda..07f797b7 100644
--- a/docs/ru/reference/cli.md
+++ b/docs/ru/reference/cli.md
@@ -45,6 +45,7 @@ vitepress build [root]
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
 | `--mpa` (экспериментально)     | Сборка в режиме [MPA](../guide/mpa-mode) без гидратации на стороне клиента (`boolean`)                                              |
 | `--base <path>`                | Публичный базовый путь (по умолчанию: `/`) (`string`)                                                                               |
+| `--assetsBase <url>`           | Префикс URL, с которого раздаются сгенерированные ресурсы, например CDN (`string`)                                  |
 | `--target <target>`            | Транспилировать цель (по умолчанию: `"modules"`) (`string`)                                                                         |
 | `--outDir <dir>`               | Выходной каталог относительно **cwd** (по умолчанию: `<root>/.vitepress/dist`) (`string`)                                           |
 | `--assetsInlineLimit <number>` | Статический встроенный порог ресурса base64 в байтах (по умолчанию: `4096`) (`number`)                                              |
@@ -64,6 +65,7 @@ vitepress preview [root]
 | Параметр        | Описание                                              |
 | --------------- | ----------------------------------------------------- |
 | `--base <path>` | Публичный базовый путь (по умолчанию: `/`) (`string`) |
+| `--assetsBase <url>` | Префикс URL, с которого раздаются сгенерированные ресурсы, например CDN (`string`) |
 | `--port <port>` | Номер порта (`number`)                                |
 
 ## `vitepress init` {#vitepress-init}
diff --git a/docs/ru/reference/default-theme-badge.md b/docs/ru/reference/default-theme-badge.md
index ff69726c..fd1141d0 100644
--- a/docs/ru/reference/default-theme-badge.md
+++ b/docs/ru/reference/default-theme-badge.md
@@ -11,21 +11,18 @@ description: Используйте компонент Badge для добавл
 Вы можете использовать компонент `Badge`, который доступен глобально.
 
 ```html
-### Заголовок <Badge type="info" text="по умолчанию" /> ### Заголовок
-<Badge type="tip" text="^1.9.0" /> ### Заголовок
-<Badge type="warning" text="beta" /> ### Заголовок
-<Badge type="danger" text="осторожно" />
+### Заголовок <Badge type="info" text="по умолчанию" />
+### Заголовок <Badge type="tip" text="^1.9.0" />
+### Заголовок <Badge type="warning" text="beta" />
+### Заголовок <Badge type="danger" text="устарело" />
 ```
 
 Приведённый выше код даёт такой результат:
 
 ### Заголовок <Badge type="info" text="по умолчанию" /> {#title}
-
 ### Заголовок <Badge type="tip" text="^1.9.0" /> {#title-1}
-
 ### Заголовок <Badge type="warning" text="beta" /> {#title-2}
-
-### Заголовок <Badge type="danger" text="осторожно" /> {#title-3}
+### Заголовок <Badge type="danger" text="устарело" /> {#title-3}
 
 ## Дочерние элементы {#custom-children}
 
@@ -47,9 +44,21 @@ description: Используйте компонент Badge для добавл
   --vp-badge-info-text: var(--vp-c-text-2);
   --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-text: var(--vp-c-brand-1);
-  --vp-badge-tip-bg: var(--vp-c-brand-soft);
+  --vp-badge-tip-text: var(--vp-c-tip-1);
+  --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-text: var(--vp-c-warning-1);
@@ -70,7 +79,7 @@ interface Props {
   // Когда передается `<slot>`, это значение игнорируется.
   text?: string
 
-  // По умолчанию: `tip`.
-  type?: 'info' | 'tip' | 'warning' | 'danger'
+  // По умолчанию `tip`. Соответствует цветам контейнеров/оповещений Markdown.
+  type?: 'info' | 'note' | 'tip' | 'important' | 'caution' | 'warning' | 'danger'
 }
 ```
diff --git a/docs/ru/reference/default-theme-config.md b/docs/ru/reference/default-theme-config.md
index afd17954..2bfb158c 100644
--- a/docs/ru/reference/default-theme-config.md
+++ b/docs/ru/reference/default-theme-config.md
@@ -254,6 +254,9 @@ export default {
       { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
       { icon: 'twitter', link: '...' },
       { icon: 'discord', link: '/community', target: '_self' },
+      // Вы можете использовать любую другую установленную в проекте коллекцию iconify
+      // в формате `collection:name` (например, после `npm add -D @iconify-json/lucide`):
+      { icon: 'lucide:rss', link: '/feed.rss' },
       // Можно добавить пользовательские иконки, передав SVG в виде строки:
       {
         icon: {
@@ -472,6 +475,27 @@ export interface DocFooter {
 
 Можно использовать для настройки aria-метки кнопки переключения языка в панели навигации. Применяется только в том случае, если вы используете [i18n](../guide/i18n).
 
+## navMenuLabel
+
+- Тип: `string`
+- По умолчанию: `Main Navigation`
+
+Может использоваться для настройки доступной метки основных ориентиров навигации (меню навбара и мобильное меню).
+
+## mobileMenuLabel
+
+- Тип: `string`
+- По умолчанию: `Menu`
+
+Может использоваться для настройки `aria-label` кнопки мобильного меню (гамбургер).
+
+## extraMenuLabel
+
+- Тип: `string`
+- По умолчанию: `More options`
+
+Может использоваться для настройки `aria-label` кнопки меню `⋯` в навбаре. Это меню собирает элементы навигации и элементы управления, которые не помещаются в бар при текущей ширине экрана.
+
 ## skipToContentLabel
 
 - Тип: `string`
@@ -486,6 +510,13 @@ export interface DocFooter {
 
 Отображать ли значок внешней ссылки рядом с внешними ссылками в 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" />
 
 Возвращает данные, относящиеся к макету. Возвращаемый объект имеет следующий тип:
diff --git a/docs/ru/reference/default-theme-nav.md b/docs/ru/reference/default-theme-nav.md
index 0dabb064..64762a12 100644
--- a/docs/ru/reference/default-theme-nav.md
+++ b/docs/ru/reference/default-theme-nav.md
@@ -215,6 +215,7 @@ export default {
 
 Ваш компонент будет отображаться на панели навигации. VitePress предоставляет следующие дополнительные параметры компонента:
 
-- `screenMenu`: необязательное булево значение, указывающее, находится ли компонент внутри мобильного навигационного меню
+- `screenMenu`: необязательный булев флаг, указывающий, находится ли компонент внутри мобильного навигационного меню
+- `menu`: необязательный булев флаг, указывающий, находится ли компонент внутри выпадающей панели — например, меню `⋯`, в которое сворачиваются элементы навигации, не помещающиеся в бар. В обоих этих контекстах рендерите плоский список вместо всплывающего флайаута, который в итоге оказался бы вложенным внутрь панели
 
 Пример можно посмотреть в тестах e2e [здесь](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress).
diff --git a/docs/ru/reference/default-theme-search.md b/docs/ru/reference/default-theme-search.md
index f40721a6..cd302734 100644
--- a/docs/ru/reference/default-theme-search.md
+++ b/docs/ru/reference/default-theme-search.md
@@ -27,11 +27,11 @@ export default defineConfig({
 
 В качестве альтернативы можно использовать [Algolia DocSearch](#algolia-search) или некоторые плагины сообщества, например:
 
-- <https://www.npmjs.com/package/vitepress-plugin-search>
-- <https://www.npmjs.com/package/vitepress-plugin-pagefind>
-- <https://www.npmjs.com/package/@orama/plugin-vitepress>
-- <https://www.npmjs.com/package/vitepress-plugin-typesense>
-- <https://www.npmjs.com/package/vitepress-plugin-cloudflare-ai-search>
+- <https://npmx.dev/package/vitepress-plugin-pagefind>
+- <https://npmx.dev/package/vitepress-plugin-typesense>
+- <https://npmx.dev/package/vitepress-plugin-cloudflare-ai-search>
+
+<!-- - <https://npmx.dev/package/@orama/plugin-vitepress> -- replace with zbsearch one when published -->
 
 ### i18n {#local-search-i18n}
 
@@ -112,6 +112,10 @@ export default defineConfig({
 
 Подробнее в [документации 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}
 
 Вы можете настроить функцию, используемую для отображения содержимого в формате Markdown перед его индексацией:
diff --git a/docs/ru/reference/frontmatter-config.md b/docs/ru/reference/frontmatter-config.md
index d9ee46ba..3c8ed7e9 100644
--- a/docs/ru/reference/frontmatter-config.md
+++ b/docs/ru/reference/frontmatter-config.md
@@ -63,7 +63,7 @@ description: VitePress
 
 - Тип: `HeadConfig[]`
 
-Укажите дополнительные теги, которые будут выводиться для текущей страницы. Они будут добавляться после других тегов внутри блока head, введённых в конфигурации сайта.
+Укажите дополнительные теги, которые будут выводиться для текущей страницы. Они [объединяются](./site-config#head) с тегами head, добавленными в конфигурации сайта.
 
 ```yaml
 ---
diff --git a/docs/ru/reference/runtime-api.md b/docs/ru/reference/runtime-api.md
index 5157bd67..6130ef4d 100644
--- a/docs/ru/reference/runtime-api.md
+++ b/docs/ru/reference/runtime-api.md
@@ -136,6 +136,36 @@ router.onBeforeRouteChange = (to) => {
 
 В пользовательских темах этот же экземпляр маршрутизатора доступен через [`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}
 
 - **Тип**: `(path: string) => string`
diff --git a/docs/ru/reference/site-config.md b/docs/ru/reference/site-config.md
index 6c593eda..50aae646 100644
--- a/docs/ru/reference/site-config.md
+++ b/docs/ru/reference/site-config.md
@@ -248,6 +248,13 @@ type HeadConfig =
   | [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}
 
 ```ts
@@ -367,6 +374,8 @@ export default {
 
 Базовый URL-адрес, по которому будет развёрнут сайт. Этот параметр необходимо задать, если вы планируете развернуть свой сайт по подпути, например, для страниц GitHub. Если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то вам следует установить base на `'/bar/'`. Он всегда должен начинаться и заканчиваться косой чертой.
 
+Единственное исключение — `'./'`, которое создаёт [переносимую сборку](../guide/deploy#relocatable-builds-relative-base): страницы ссылаются на всё относительно своего собственного расположения, поэтому один и тот же результат сборки работает из любого подпути (шлюзы IPFS, архивы) без пересборки и остаётся просматриваемым при открытии напрямую из файловой системы.
+
 Параметр `base` автоматически добавляется ко всем URL, которые начинаются с `/` в других опциях, поэтому вам нужно указать его только один раз.
 
 ```ts
@@ -375,6 +384,8 @@ export default {
 }
 ```
 
+Также может быть задан для отдельной сборки с помощью `vitepress build --base /base/`.
+
 ## Маршрутизация {#routing}
 
 ### 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}
 
 - Тип: `string`
@@ -625,6 +674,7 @@ export default {
 interface SSGContext {
   content: string
   teleports?: Record<string, string>
+  vpIcons: Set<string>
   [key: string]: any
 }
 ```
@@ -639,6 +689,10 @@ interface SSGContext {
 Не мутируйте ничего внутри `context`.
 :::
 
+::: note
+Ссылка на таблицу стилей иконок на этом этапе всё ещё содержит заглушку `vp-icons.__VP_ICONS_HASH__.css` — хеш содержимого появляется только после того, как отрендерены все страницы, и подставляется сразу после этого. Хуки, которые встраивают или проставляют отпечаток ресурсам в head, должны пропускать этот тег.
+:::
+
 ```ts
 export default {
   async transformHead(context) {