From 9ca82afdfc4060455ad6ccbc444dead678f0afdc Mon Sep 17 00:00:00 2001 From: Bugo <229402+dragomano@users.noreply.github.com> Date: Tue, 7 Jul 2026 10:11:48 +0500 Subject: [PATCH] Update ru/reference/site-config.md --- docs/ru/reference/site-config.md | 129 +++++++++++++++++++++++-------- 1 file changed, 96 insertions(+), 33 deletions(-) diff --git a/docs/ru/reference/site-config.md b/docs/ru/reference/site-config.md index d8c0d2558..b04a3bdd4 100644 --- a/docs/ru/reference/site-config.md +++ b/docs/ru/reference/site-config.md @@ -134,13 +134,43 @@ export default defineConfigWithTheme({ Вы можете настроить базовый экземпляр [Markdown-It](https://github.com/markdown-it/markdown-it) с помощью опции [markdown](#markdown) в конфигурации VitePress. +### Переопределение на уровне страницы {#page-level-overrides} + +Некоторые настройки можно переопределить для отдельных страниц с помощью метаданных. + +Подробности см. в разделе [Конфигурация метаданных](./frontmatter-config). + +### Переопределение на уровне директории {#directory-level-overrides} + +Некоторые параметры конфигурации можно переопределить на уровне директории, что позволяет всем страницам в этой директории использовать общие настройки без необходимости повторять их в блоке метаданных каждой страницы. + +Для этого добавьте файл с именем `config.ts` (или `.js`, `.mjs` или `.mts`) в соответствующую директорию. Этот файл должен экспортировать объект конфигурации с помощью `export default`, аналогично основному файлу конфигурации. + +Вложенные директории наследуют настройки от родительской директории, при этом переопределения конфигурации объединяются соответствующим образом. + +Вспомогательную функцию `defineAdditionalConfig` можно использовать для получения подсказок TypeScript по доступным параметрам, однако, как и в случае с `defineConfig`, её использование необязательно. + +Например, для сайта с несколькими языками может потребоваться разное значение `description` для каждого языка. Мы можем добавить файл `es/config.ts` со следующим содержимым: + +```ts +import { defineAdditionalConfig } from 'vitepress' + +export default defineAdditionalConfig({ + description: 'Generador de Sitios Estáticos desarrollado con Vite y Vue.' +}) +``` + +Этот `description` затем будет использоваться для всех страниц в директории `es`. + +В качестве альтернативы, при использовании встроенных возможностей i18n настройки для директории локали можно переопределить через параметр `locales` в основном файле конфигурации. Подробности см. в разделе [Интернационализация](../guide/i18n). + ## Метаданные сайта {#site-metadata} ### title {#title} - Тип: `string` - По умолчанию: `VitePress` -- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#title) +- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#title) или на [уровне директории](#directory-level-overrides) Название для сайта. При использовании темы по умолчанию оно будет отображаться в панели навигации. @@ -161,7 +191,7 @@ export default { ### titleTemplate {##titletemplate} - Тип: `string | boolean` -- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#titletemplate) +- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#titletemplate) или на [уровне директории](#directory-level-overrides) Позволяет настраивать суффикс заголовка каждой страницы или весь заголовок. Например: @@ -194,7 +224,7 @@ export default { - Тип: `string` - По умолчанию: `A VitePress site` -- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#description) +- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#description) или на [уровне директории](#directory-level-overrides) Описание для сайта. Это будет отображаться как тег `` в HTML-странице. @@ -208,7 +238,7 @@ export default { - Тип: `HeadConfig[]` - По умолчанию: `[]` -- Можно добавлять на страницу через [метаданные](./frontmatter-config#head) +- Можно добавлять на страницу через [метаданные](./frontmatter-config#head) или на [уровне директории](#directory-level-overrides) Дополнительные элементы для отображения в теге `` в HTML-странице. Добавленные пользователем теги выводятся перед закрывающим тегом `head`, после тегов VitePress. @@ -320,6 +350,7 @@ export default { - Тип: `string` - По умолчанию: `en-US` +- Может быть переопределено [на уровне директории](#directory-level-overrides) Атрибут lang для сайта. Будет выглядеть как тег `` в HTML-странице. @@ -530,6 +561,8 @@ export default { Проверьте [объявление типа и jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) на наличие всех доступных опций. +Установите `markdown.headers` в значение `true` или передайте параметры [`@mdit-vue/plugin-headers`](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers), чтобы собирать заголовки в [`useData().page.headers`](./runtime-api#usedata). Этот параметр отключён по умолчанию. + ### vite {#vite} - Тип: `import('vite').UserConfig` @@ -607,7 +640,7 @@ interface SSGContext { - Тип: `(context: TransformContext) => Awaitable` -`transformHead` — это хук сборки для преобразования заголовка перед генерацией каждой страницы. Это позволит вам добавить в конфигурацию VitePress записи, которые не могут быть добавлены статически. Вам нужно только вернуть дополнительные записи, они будут автоматически объединены с существующими. +`transformHead` — это хук сборки для добавления дополнительных тегов в `` каждой страницы. Он позволяет добавлять элементы в head, которые невозможно статически добавить в конфигурацию VitePress. Вам нужно только вернуть дополнительные элементы — они будут автоматически объединены с уже существующими. ::: warning ПРЕДУПРЕЖДЕНИЕ Не мутируйте ничего внутри `context`. @@ -635,44 +668,38 @@ interface TransformContext { } ``` -Обратите внимание, что этот хук вызывается только при статической генерации сайта. Он не вызывается во время разработки. Если вам нужно добавить динамические записи в голову во время разработки, вместо этого вы можете использовать хук [`transformPageData`](#transformpagedata): +Этот хук вызывается только при выполнении сборки и не вызывается в режиме разработки. -```ts -export default { - transformPageData(pageData) { - pageData.frontmatter.head ??= [] - pageData.frontmatter.head.push([ - 'meta', - { - name: 'og:title', - content: - pageData.frontmatter.layout === 'home' - ? `VitePress` - : `${pageData.title} | VitePress` - } - ]) - } -} -``` +Дополнительные теги будут добавлены в статические HTML-файлы, созданные во время сборки. Они не будут обновляться при навигации на стороне клиента. -#### Пример: Добавление канонического URL-адреса `` {#example-adding-a-canonical-url-link} +Во многих случаях более подходящим решением будет использование хука [`transformPageData`](#transformpagedata). Этот хук также применяется как при клиентской навигации, так и в режиме разработки. Однако если генерация тегов head требует значительных вычислительных ресурсов, `transformHead` позволяет избежать этих затрат во время разработки. + +#### Пример: добавление мета-тега `og:image` {#example-adding-og-image-meta} ```ts export default { - transformPageData(pageData) { - const canonicalUrl = `https://example.com/${pageData.relativePath}` - .replace(/index\.md$/, '') - .replace(/\.md$/, '.html') + async transformHead(context) { + if (context.page === '404.md') { + return + } - pageData.frontmatter.head ??= [] - pageData.frontmatter.head.push([ - 'link', - { rel: 'canonical', href: canonicalUrl } - ]) + // Детали реализации `generatePageImage` зависят от ваших требований. + // Здесь мы предполагаем, что она создаёт подходящее изображение + // для каждой страницы и возвращает URL изображения. + const imageUrl = await generatePageImage(context) + + return [[ + 'meta', + { name: 'og:image', content: imageUrl } + ]] } } ``` +Здесь мы предполагаем, что URL изображения является динамическим и требует много времени для генерации. Использование `transformHead` позволяет избежать этих затрат во время разработки. + +Для более простых случаев может быть достаточно использовать параметр [`head`](./frontmatter-config#head) в метаданных или [`transformPageData`](#transformpagedata). + ### transformHtml {#transformhtml} - Тип: `(code: string, id: string, context: TransformContext) => Awaitable` @@ -721,3 +748,39 @@ interface TransformPageContext { siteConfig: SiteConfig } ``` + +#### Пример: добавление `` {#example-adding-a-meta-name-og-title} + +```ts +export default { + transformPageData(pageData) { + const title = pageData.frontmatter.layout === 'home' + ? 'VitePress' + : `${pageData.title} | VitePress` + + pageData.frontmatter.head ??= [] + pageData.frontmatter.head.push([ + 'meta', + { name: 'og:title', content: title } + ]) + } +} +``` + +#### Пример: добавление `` с каноническим URL {#example-adding-a-canonical-url-link} + +```ts +export default { + transformPageData(pageData) { + const canonicalUrl = `https://example.com/${pageData.relativePath}` + .replace(/index\.md$/, '') + .replace(/\.md$/, '.html') + + pageData.frontmatter.head ??= [] + pageData.frontmatter.head.push([ + 'link', + { rel: 'canonical', href: canonicalUrl } + ]) + } +} +```