From ef6ddcb9a9ee4dd3129d4024074ac29a877781df Mon Sep 17 00:00:00 2001 From: Bugo Date: Tue, 26 Mar 2024 21:58:12 +0500 Subject: [PATCH] Translate reference/site-config.md --- docs/ru/reference/site-config.md | 720 +++++++++++++++++++++++++++++++ 1 file changed, 720 insertions(+) create mode 100644 docs/ru/reference/site-config.md diff --git a/docs/ru/reference/site-config.md b/docs/ru/reference/site-config.md new file mode 100644 index 00000000..d089e709 --- /dev/null +++ b/docs/ru/reference/site-config.md @@ -0,0 +1,720 @@ +--- +outline: deep +--- + +# Настройка сайта {#site-config} + +Настройка сайта - это место, где вы можете определить глобальные настройки сайта. Параметры конфигурации приложения определяют настройки, которые применяются к каждому сайту VitePress, независимо от того, какая тема на нем используется. Например, базовый каталог или название сайта. + +## Обзор {#overview} + +### Разрешение конфигурации {#config-resolution} + +Файл конфигурации всегда разрешается из `/.vitepress/config.[ext]`, где `` — это корень вашего [проекта](../guide/routing#root-and-source-directory) VitePress, а `[ext]` — одно из поддерживаемых расширений файла. TypeScript поддерживается из коробки. Поддерживаемые расширения включают `.js`, `.ts`, `.mjs` и `.mts`. + +В файлах конфигурации рекомендуется использовать синтаксис ES-модулей. Файл конфигурации должен по умолчанию экспортировать объект: + +```ts +export default { + // параметры конфигурации на уровне приложения + lang: 'ru-RU', + title: 'VitePress', + description: 'Генератор статических сайтов на основе Vite и Vue.', + ... +} +``` + +:::details Динамическая (асинхронная) конфигурация + +Если вам нужно генерировать конфигурацию динамически, вы также можете экспортировать функцию по умолчанию. Например: + +```ts +import { defineConfig } from 'vitepress' + +export default async () => { + const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + + return defineConfig({ + // параметры конфигурации на уровне приложения + lang: 'ru-RU', + title: 'VitePress', + description: 'Генератор статических сайтов на основе Vite и Vue.', + + // параметры конфигурации на уровне темы + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } + }) +} +``` + +Вы также можете использовать `await` верхнего уровня. Например: + +```ts +import { defineConfig } from 'vitepress' + +const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + +export default defineConfig({ + // параметры конфигурации на уровне приложения + lang: 'ru-RU', + title: 'VitePress', + description: 'Генератор статических сайтов на основе Vite и Vue.', + + // параметры конфигурации на уровне темы + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } +}) +``` + +::: + +### Интеллектуальная настройка {#config-intellisense} + +Использование помощника `defineConfig` обеспечит интеллектуальный анализ опций конфигурации на основе TypeScript. Если ваша IDE поддерживает эту функцию, она должна работать как в JavaScript, так и в TypeScript. + +```js +import { defineConfig } from 'vitepress' + +export default defineConfig({ + // ... +}) +``` + +### Типизированная конфигурация темы {#typed-theme-config} + +По умолчанию помощник `defineConfig` ожидает тип конфигурации темы из темы по умолчанию: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + // Тип `DefaultTheme.Config` + } +}) +``` + +Если вы используете пользовательскую тему и хотите проверять типы для конфигурации темы, вам нужно использовать `defineConfigWithTheme`, и передавать тип конфигурации для вашей пользовательской темы через общий аргумент: + +```ts +import { defineConfigWithTheme } from 'vitepress' +import type { ThemeConfig } from 'your-theme' + +export default defineConfigWithTheme({ + themeConfig: { + // Tип `ThemeConfig` + } +}) +``` + +### Настройка Vite, Vue и Markdown {#vite-vue-markdown-config} + +- **Vite** + + Вы можете настроить базовый экземпляр Vite с помощью опции [vite](#vite) в конфигурации VitePress. Нет необходимости создавать отдельный файл конфигурации Vite. + +- **Vue** + + VitePress уже включает в себя официальный плагин Vue для Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Вы можете настроить его параметры с помощью опции [vue](#vue) в конфигурации VitePress. + +- **Markdown** + + Вы можете настроить базовый экземпляр [Markdown-It](https://github.com/markdown-it/markdown-it) с помощью опции [markdown](#markdown) в конфигурации VitePress. + +## Метаданные сайта {#site-metadata} + +### title {#title} + +- Тип: `string` +- По умолчанию: `VitePress` +- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#title) + +Название для сайта. При использовании темы по умолчанию оно будет отображаться в панели навигации. + +Оно также будет использоваться в качестве суффикса по умолчанию для всех заголовков отдельных страниц, если не определен [`titleTemplate`](#titletemplate). Окончательный заголовок отдельной страницы будет представлять собой текстовое содержимое её первого заголовка `

`, объединённое с глобальным `title` в качестве суффикса. Например, со следующей конфигурацией и содержимым страницы: + +```ts +export default { + title: 'Мой замечательный сайт' +} +``` + +```md +# Привет +``` + +Заголовок страницы будет таким: `Привет | Мой замечательный сайт`. + +### titleTemplate {##titletemplate} + +- Тип: `string | boolean` +- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#titletemplate) + +Позволяет настраивать суффикс заголовка каждой страницы или весь заголовок. Например: + +```ts +export default { + title: 'Мой замечательный сайт', + titleTemplate: 'Пользовательский суффикс' +} +``` + +```md +# Привет +``` + +Заголовок страницы будет таким: `Привет | Пользовательский суффикс`. + +Чтобы полностью настроить отображение заголовка, вы можете использовать символ `:title` в `titleTemplate`: + +```ts +export default { + titleTemplate: ':title - Пользовательский суффикс' +} +``` + +Здесь `:title` будет заменён текстом, выведенным из первого заголовка страницы `

`. Заголовок страницы предыдущего примера будет `Привет - Пользовательский суффикс`. + +Опция может быть установлена в значение `false`, чтобы отключить суффиксы заголовков. + +### description {#description} + +- Тип: `string` +- По умолчанию: `A VitePress site` +- Можно переопределить для каждой страницы с помощью [метаданных](./frontmatter-config#description) + +Описание для сайта. Это будет отображаться как тег `` в HTML-странице. + +```ts +export default { + description: 'A VitePress site' +} +``` + +### head {#head} + +- Тип: `HeadConfig[]` +- По умолчанию: `[]` +- Можно добавлять на страницу через [метаданные](./frontmatter-config#head) + +Дополнительные элементы для отображения в теге `` в HTML-странице. Добавленные пользователем теги выводятся перед закрывающим тегом `head`, после тегов VitePress. + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +#### Пример: Добавление значка сайта {#example-adding-a-favicon} + +```ts +export default { + head: [['link', { rel: 'icon', href: '/favicon.ico' }]] +} // поместите favicon.ico в публичную директорию; если установлен параметр base, используйте /base/favicon.ico + +/* Отрисуется так: + +*/ +``` + +#### Пример: Добавление шрифтов Google {#example-adding-google-fonts} + +```ts +export default { + head: [ + ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }], + [ + 'link', + { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' } + ], + [ + 'link', + { + href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', + rel: 'stylesheet' + } + ] + ] +} + +/* Отрисуется так: + + + +*/ +``` + +#### Пример: Регистрация сервис-воркера {#example-registering-a-service-worker} + +```ts +export default { + head: [ + [ + 'script', + { id: 'register-sw' }, + `;(() => { + if ('serviceWorker' in navigator) { + navigator.serviceWorker.register('/sw.js') + } + })()` + ] + ] +} + +/* Отрисуется так: + +*/ +``` + +#### Пример: Использование Google Analytics {#example-using-google-analytics} + +```ts +export default { + head: [ + [ + 'script', + { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' } + ], + [ + 'script', + {}, + `window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + gtag('config', 'TAG_ID');` + ] + ] +} + +/* Отрисуется так: + + +*/ +``` + +### lang {#lang} + +- Тип: `string` +- По умолчанию: `en-US` + +Атрибут lang для сайта. Будет выглядеть как тег `` в HTML-странице. + +```ts +export default { + lang: 'en-US' +} +``` + +### base {#base} + +- Тип: `string` +- По умолчанию: `/` + +Базовый URL-адрес, по которому будет развёрнут сайт. Этот параметр необходимо задать, если вы планируете развернуть свой сайт по подпути, например, для страниц GitHub. Если вы планируете развернуть свой сайт на `https://foo.github.io/bar/`, то вам следует установить base на `'/bar/'`. Он всегда должен начинаться и заканчиваться косой чертой. + +Параметр `base` автоматически добавляется ко всем URL, которые начинаются с `/` в других опциях, поэтому вам нужно указать его только один раз. + +```ts +export default { + base: '/base/' +} +``` + +## Маршрутизация {#routing} + +### cleanUrls {#cleanurls} + +- Тип: `boolean` +- По умолчанию: `false` + +Если установить значение `true`, VitePress будет удалять из URL-адресов завершающий `.html`. Также смотрите [Создание чистого URL-адреса](../guide/routing#generating-clean-url). + +::: warning Требуется поддержка сервера +Для включения этой функции может потребоваться дополнительная настройка на вашей хостинговой платформе. Чтобы это сработало, ваш сервер должен быть способен обслуживать `/foo.html` при посещении `/foo` **без редиректа**. +::: + +### rewrites {#rewrites} + +- Тип: `Record` + +Определяет сопоставление пользовательских каталогов с URL-адресами. Дополнительную информацию см. в разделе [Маршрутизация: перезапись маршрутов](../guide/routing#route-rewrites). + +```ts +export default { + rewrites: { + 'source/:page': 'destination/:page' + } +} +``` + +## Сборка {#build} + +### srcDir {#srcdir} + +- Тип: `string` +- По умолчанию: `.` + +Каталог, в котором хранятся ваши страницы в формате Markdown, относительно корня проекта. Также смотрите [Корневая директория и директория с исходными файлами](../guide/routing#root-and-source-directory). + +```ts +export default { + srcDir: './src' +} +``` + +### srcExclude {#srcexclude} + +- Тип: `string` +- По умолчанию: `undefined` + +[Шаблон](https://github.com/mrmlnc/fast-glob#pattern-syntax) для поиска файлов, которые должны быть исключены из исходного содержимого. + +```ts +export default { + srcExclude: ['**/README.md', '**/TODO.md'] +} +``` + +### outDir {#outdir} + +- Тип: `string` +- По умолчанию: `./.vitepress/dist` + +Расположение вывода сборки для сайта, относительно [корня проекта](../guide/routing#root-and-source-directory). + +```ts +export default { + outDir: '../public' +} +``` + +### assetsDir {#assetsdir} + +- Тип: `string` +- По умолчанию: `assets` + +Укажите каталог, в котором будут храниться сгенерированные ресурсы. Путь должен находиться внутри [`outDir`](#outdir) и разрешается относительно него. + +```ts +export default { + assetsDir: 'static' +} +``` + +### cacheDir {#cachedir} + +- Тип: `string` +- По умолчанию: `./.vitepress/cache` + +Каталог для файлов кэша, относительно [корня проекта](../guide/routing#root-and-source-directory). См. также: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir). + +```ts +export default { + cacheDir: './.vitepress/.vite' +} +``` + +### ignoreDeadLinks {#ignoredeadlinks} + +- Тип: `boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]` +- По умолчанию: `false` + +Если установлено значение `true`, VitePress не будет завершать сборку из-за неработающих ссылок. + +Если установить значение `'localhostLinks'`, сборка будет завершаться при наличии неработающих ссылок, но не будет проверять ссылки `localhost`. + +```ts +export default { + ignoreDeadLinks: true +} +``` + +Это также может быть массив точных строк url, шаблонов regex или пользовательских функций фильтрации. + +```ts +export default { + ignoreDeadLinks: [ + // игнорировать url "/playground" + '/playground', + // игнорировать все ссылки на localhost + /^https?:\/\/localhost/, + // игнорировать все ссылки, включающие "/repl/"" + /\/repl\//, + // пользовательская функция, игнорирует все ссылки, включающие "ignore" + (url) => { + return url.toLowerCase().includes('ignore') + } + ] +} +``` + +### metaChunk {#metachunk} + +- Тип: `boolean` +- По умолчанию: `false` + +Если установлено значение `true`, метаданные страницы извлекаются в отдельный фрагмент JavaScript, а не вставляются в исходный HTML. Это уменьшает полезную нагрузку HTML каждой страницы и делает метаданные страниц кэшируемыми, что позволяет снизить пропускную способность сервера при наличии большого количества страниц на сайте. + +### mpa {#mpa} + +- Тип: `boolean` +- По умолчанию: `false` + +Если установлено значение `true`, производственное приложение будет создано в [режиме MPA](../guide/mpa-mode). В режиме MPA по умолчанию используется 0 КБ JavaScript, что приводит к отключению навигации на стороне клиента и требует явного согласия на интерактивность. + +## Тема {#theming} + +### appearance {#appearance} + +- Тип: `boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions` +- По умолчанию: `true` + +Включать ли тёмный режим (путём добавления класса `.dark` к элементу ``). + +- Если опция имеет значение `true`, тема по умолчанию будет определяться цветовой гаммой, предпочитаемой пользователем. +- Если опция имеет значение `dark`, тема по умолчанию будет тёмной, если пользователь не переключит её вручную. +- Если установить значение `false`, пользователи не смогут переключать тему. + +Эта опция вставляет встроенный скрипт, который восстанавливает настройки пользователей из локального хранилища с помощью ключа `vitepress-theme-appearance`. Это гарантирует, что класс `.dark` будет применён до отрисовки страницы, чтобы избежать мерцания. + +`appearance.initialValue` может быть только `'dark' | undefined`. Ссылки или геттеры не поддерживаются. + +### lastUpdated {#lastupdated} + +- Тип: `boolean` +- По умолчанию: `false` + +Получать ли временную метку последнего обновления для каждой страницы с помощью Git. Временная метка будет включена в данные каждой страницы, доступные через [`useData`](./runtime-api#usedata). + +При использовании темы по умолчанию включение этой опции приведёт к отображению времени последнего обновления каждой страницы. Вы можете настроить текст с помощью опции [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext). + +## Кастомизация {#customization} + +### markdown {#markdown} + +- Тип: `MarkdownOption` + +Настройте параметры парсера Markdown. VitePress использует [Markdown-it](https://github.com/markdown-it/markdown-it) в качестве парсера и [Shiki](https://github.com/shikijs/shiki) для подсветки синтаксиса языка. Внутри этой опции вы можете передать различные параметры, связанные с Markdown, в соответствии с вашими потребностями. + +```js +export default { + markdown: {...} +} +``` + +Проверьте [объявление типа и jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) на наличие всех доступных опций. + +### vite {#vite} + +- Тип: `import('vite').UserConfig` + +Передаёт необработанную [конфигурацию Vite](https://vitejs.dev/config/) внутреннему серверу разработки / сборщику Vite. + +```js +export default { + vite: { + // параметры конфигурации Vite + } +} +``` + +### vue {#vue} + +- Тип: `import('@vitejs/plugin-vue').Options` + +Передаёт необработанные [параметры `@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) внутреннему экземпляру плагина. + +```js +export default { + vue: { + // параметры @vitejs/plugin-vue + } +} +``` + +## Хуки сборки {#build-hooks} + +Хуки для сборки VitePress позволяют добавлять на сайт новую функциональность и поведение: + +- Карта сайта +- Поисковая индексация +- PWA +- Телепорты + +### buildEnd {#buildend} + +- Тип: `(siteConfig: SiteConfig) => Awaitable` + +`buildEnd` — это хук CLI сборки, который будет запущен после завершения сборки (SSG), но до выхода из процесса VitePress CLI. + +```ts +export default { + async buildEnd(siteConfig) { + // ... + } +} +``` + +### postRender {#postrender} + +- Тип: `(context: SSGContext) => Awaitable` + +`postRender` — это хук сборки, вызываемый после завершения рендеринга SSG. Это позволит вам обрабатывать содержимое телепортов во время SSG. + +```ts +export default { + async postRender(context) { + // ... + } +} +``` + +```ts +interface SSGContext { + content: string + teleports?: Record + [key: string]: any +} +``` + +### transformHead {#transformhead} + +- Тип: `(context: TransformContext) => Awaitable` + +`transformHead` — это хук сборки для преобразования заголовка перед генерацией каждой страницы. Это позволит вам добавить в конфигурацию VitePress записи, которые не могут быть добавлены статически. Вам нужно только вернуть дополнительные записи, они будут автоматически объединены с существующими. + +::: warning Предупреждение +Не мутируйте ничего внутри `context`. +::: + +```ts +export default { + async transformHead(context) { + // ... + } +} +``` + +```ts +interface TransformContext { + page: string // например, index.md (относительно srcDir) + assets: string[] // все ресурсы, не относящиеся к js/css, в виде полностью разрешённых публичных URL-адресов + siteConfig: SiteConfig + siteData: SiteData + pageData: PageData + title: string + description: string + head: HeadConfig[] + content: string +} +``` + +Обратите внимание, что этот хук вызывается только при статической генерации сайта. Он не вызывается во время разработки. Если вам нужно добавить динамические записи в голову во время разработки, вместо этого вы можете использовать хук [`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` + } + ]) + } +} +``` + +#### Пример: Добавление канонического 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 } + ]) + } +} +``` + +### transformHtml {#transformhtml} + +- Тип: `(code: string, id: string, context: TransformContext) => Awaitable` + +`transformHtml` — это хук сборки для преобразования содержимого каждой страницы перед сохранением на диск. + +::: warning Предупреждение +Не мутируйте ничего внутри `контекста`. Кроме того, изменение html-содержимого может вызвать проблемы с гидратацией во время выполнения. +::: + +```ts +export default { + async transformHtml(code, id, context) { + // ... + } +} +``` + +### transformPageData {#transformpagedata} + +- Тип: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>` + +`transformPageData` — это хук для преобразования `pageData` каждой страницы. Вы можете напрямую изменять `pageData` или возвращать изменённые значения, которые будут объединены с данными страницы. + +::: warning Предупреждение +Не мутируйте ничего внутри `context` и будьте осторожны, это может повлиять на производительность dev-сервера, особенно если у вас есть некоторые сетевые запросы или тяжёлые вычисления (например, генерация изображений) в хуке. Вы можете проверить `process.env.NODE_ENV === 'production'` для условной логики. +::: + +```ts +export default { + async transformPageData(pageData, { siteConfig }) { + pageData.contributors = await getPageContributors(pageData.relativePath) + } + + // или возвращаем данные для объединения + async transformPageData(pageData, { siteConfig }) { + return { + contributors: await getPageContributors(pageData.relativePath) + } + } +} +``` + +```ts +interface TransformPageContext { + siteConfig: SiteConfig +} +```