Конфигурация сайта

Конфигурация сайта позволяет определить глобальные настройки сайта. Опции конфигурации приложения определяют настройки, которые применяются ко всем сайтам VitePress, независимо от используемой темы. Например, базовый каталог или заголовок сайта.

Обзор

Разрешение конфигурации

Файл конфигурации всегда разрешается из <root>/.vitepress/config.[ext], где <root> - это ваш корневой каталог проекта VitePress, а [ext] - одно из поддерживаемых расширений файлов. TypeScript поддерживается из коробки. Поддерживаемые расширения включают .js, .ts, .mjs и .mts.

Рекомендуется использовать синтаксис модулей ES в файлах конфигурации. Файл конфигурации должен экспортировать объект по умолчанию:

export default {
  // опции конфигурации на уровне приложения
  lang: 'en-US',
  title: 'VitePress',
  description: 'Генератор статических сайтов на Vite & Vue.',
  ...
}

Динамическая (асинхронная) конфигурация

Если вам нужно динамически сгенерировать конфигурацию, вы также можете экспортировать функцию по умолчанию. Например:

import { defineConfig } from 'vitepress'

export default async () => {
  const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

  return defineConfig({
    // опции конфигурации на уровне приложения
    lang: 'en-US',
    title: 'VitePress',
    description: 'Генератор статических сайтов на Vite & Vue.',

    // опции конфигурации на уровне темы
    themeConfig: {
      sidebar: [
        ...posts.map((post) => ({
          text: post.name,
          link: `/posts/${post.name}`
        }))
      ]
    }
  })
}

Вы также можете использовать await на верхнем уровне. Например:

import { defineConfig } from 'vitepress'

const posts = await (await fetch('https://my-cms.com/blog-posts')).json()

export default defineConfig({
  // опции конфигурации на уровне приложения
  lang: 'en-US',
  title: 'VitePress',
  description: 'Генератор статических сайтов на Vite & Vue.',

  // опции конфигурации на уровне темы
  themeConfig: {
    sidebar: [
      ...posts.map((post) => ({
        text: post.name,
        link: `/posts/${post.name}`
      }))
    ]
  }
})

Интеллектуальное автодополнение конфигурации

Использование помощника defineConfig обеспечит интеллектуальное автодополнение для опций конфигурации на основе TypeScript. Предполагая, что ваша среда разработки это поддерживает, это должно работать как в JavaScript, так и в TypeScript.

import { defineConfig } from 'vitepress'

export default defineConfig({
  // ...
})

Типизированная конфигурация темы

По умолчанию, помощник defineConfig ожидает тип конфигурации темы от темы по умолчанию:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    // Тип `DefaultTheme.Config`
  }
})

Если вы используете пользовательскую тему и хотите проверки типов для конфигурации темы, вам нужно будет использовать defineConfigWithTheme вместо этого и передать тип конфигурации для вашей пользовательской темы через обобщенный аргумент:

import { defineConfigWithTheme } from 'vitepress'
import type { ThemeConfig } from 'your-theme'

export default defineConfigWithTheme<ThemeConfig>({
  themeConfig: {
    // Тип `ThemeConfig`
  }
})

Конфигурация Vite, Vue & Markdown

Vite
Вы можете настроить внутренний экземпляр Vite, используя опцию vite в вашей конфигурации VitePress. Нет необходимости создавать отдельный файл конфигурации Vite.
Vue
VitePress уже включает официальный плагин Vue для Vite (@vitejs/plugin-vue). Вы можете настроить его опции, используя опцию vue в вашей конфигурации VitePress.
**Markdown

Вы можете настроить внутренний экземпляр Markdown-It, используя опцию markdown в вашей конфигурации VitePress.

Метаданные сайта

title

Тип: string
По умолчанию: VitePress
Может быть переопределено на странице через frontmatter

Заголовок сайта. При использовании темы по умолчанию он будет отображаться в панели навигации.

Он также будет использоваться в качестве стандартного суффикса для всех индивидуальных заголовков страниц, если не определен titleTemplate. Финальный заголовок страницы будет текстовым содержимым её первого заголовка <h1>, объединенным с глобальным title в качестве суффикса. Например, с следующей конфигурацией и содержимым страницы:

export default {
  title: 'Мой потрясающий сайт'
}

# Привет

Заголовок страницы будет Привет | Мой потрясающий сайт.

titleTemplate

Тип: string | boolean
Может быть переопределено на странице через frontmatter

Позволяет настраивать суффикс заголовка каждой страницы или весь заголовок. Например:

export default {
  title: 'Мой потрясающий сайт',
  titleTemplate: 'Пользовательский суффикс'
}

# Привет

Заголовок страницы будет Привет | Пользовательский суффикс.

Чтобы полностью настроить отображение заголовка, вы можете использовать символ :title в titleTemplate:

export default {
  titleTemplate: ':title - Пользовательский суффикс'
}

Здесь :title будет заменен текстом, полученным из первого заголовка <h1> страницы. Заголовок предыдущей примерной страницы будет Привет - Пользовательский суффикс.

Опция может быть установлена в false, чтобы отключить суффиксы заголовков.

description

Тип: string
По умолчанию: Сайт на VitePress
Может быть переопределено на странице через frontmatter

Описание сайта. Это будет отображаться как тег <meta> в HTML страницы.

export default {
  description: 'Сайт на VitePress'
}

head

Тип: HeadConfig[]
По умолчанию: []
Может быть добавлено на странице через frontmatter

Дополнительные элементы для отображения в теге <head> в HTML страницы. Добавленные пользователем теги отображаются перед закрывающим тегом head, после тегов VitePress.

type HeadConfig =
  | [string, Record<string, string>]
  | [string, Record<string, string>, string]

Пример: Добавление favicon

export default {
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]]
} // поместите favicon.ico в публичный каталог, если установлен base, используйте /base/favicon.ico

/* Будет отображено:
  <link rel="icon" href="/favicon.ico">
*/

Пример: Добавление шрифтов Google

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' }
    ]
  ]
}

/* Будет отображено:
  <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">
*/

Пример: Регистрация сервис-воркера

export default {
  head: [
    [
      'script',
      { id: 'register-sw' },
      `;(() => {
        if ('serviceWorker' in navigator) {
          navigator.serviceWorker.register('/sw.js')
        }
      })()`
    ]
  ]
}

/* Будет отображено:
  <script id="register-sw">
    ;(() => {
      if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/sw.js')
      }
    })()
  </script>
*/

Пример: Использование Google Analytics

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');`
    ]
  ]
}

/* Будет отображено:
  <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'TAG_ID');
  </script>
*/

lang

Тип: `string

По умолчанию: en-US

Атрибут языка для сайта. Это будет отображаться как тег <html lang="en-US"> в HTML страницы.

export default {
  lang: 'en-US'
}

base

Тип: string
По умолчанию: /

Базовый URL, на котором будет развернут сайт. Вам нужно будет установить это, если планируете развернуть свой сайт в подпапке, например, на GitHub pages. Если вы планируете развернуть свой сайт на https://foo.github.io/bar/, то вы должны установить base в '/bar/'. Он всегда должен начинаться и заканчиваться слешем.

Base автоматически добавляется ко всем URL, которые начинаются с / в других опциях, поэтому вам нужно указать его только один раз.

export default {
  base: '/base/'
}

Маршрутизация

cleanUrls

Тип: boolean
По умолчанию: false

Когда установлено в true, VitePress удалит окончание .html из URL. Смотрите также Генерация чистых URL.

Требуется поддержка сервера

Включение этой опции может потребовать дополнительной настройки на вашей хостинг-платформе. Для ее работы ваш сервер должен уметь обслуживать /foo.html при посещении /foo без перенаправления.

rewrites

Тип: Record<string, string>

Определяет пользовательские сопоставления каталогов и URL. Смотрите Маршрутизация: Перезапись маршрутов для более подробной информации.

export default {
  rewrites: {
    'source/:page': 'destination/:page'
  }
}

Сборка

srcDir

Тип: string
По умолчанию: .

Каталог, где хранятся ваши страницы в формате markdown, относительно корневого каталога проекта. Смотрите также Корневой и исходный каталог.

export default {
  srcDir: './src'
}

srcExclude

Тип: string
По умолчанию: undefined

Шаблон glob для сопоставления файлов markdown, которые должны быть исключены из исходного контента.

export default {
  srcExclude: ['**/README.md', '**/TODO.md']
}

outDir

Тип: string
По умолчанию: ./.vitepress/dist

Местоположение выходных данных сборки для сайта, относительно корневого каталога проекта.

export default {
  outDir: '../public'
}

assetsDir

Тип: string
По умолчанию: assets

Укажите каталог для вложения сгенерированных активов. Путь должен находиться внутри outDir и разрешается относительно него.

export default {
  assetsDir: 'static'
}

cacheDir

Тип: string
По умолчанию: ./.vitepress/cache

Каталог для файлов кэша, относительно корневого каталога проекта. Смотрите также: cacheDir.

export default {
  cacheDir: './.vitepress/.vite'
}

ignoreDeadLinks

Тип: boolean | 'localhostLinks' | (string | RegExp | ((link: string) => boolean))[]
По умолчанию: false

Когда установлено в true, VitePress не будет прерывать сборку из-за мертвых ссылок.

Когда установлено в 'localhostLinks', сборка будет прервана из-за мертвых ссылок, но не будет проверять ссылки localhost.

export default {
  ignoreDeadLinks: true
}

Это также может быть массивом точных строк URL, шаблонов регулярных выражений или пользовательских функций фильтрации.

export default {
  ignoreDeadLinks: [
    // игнорировать точный URL "/playground"
    '/playground',
    // игнорировать все ссылки localhost
    /^https?:\/\/localhost/,
    // игнорировать все ссылки, содержащие "/repl/"
    /\/repl\//,
    // пользовательская функция, игнорировать все ссылки, содержащие "ignore"
    (url) => {
      return url.toLowerCase().includes('ignore')
    }
  ]
}

mpa экспериментально

Тип: boolean
По умолчанию: false

Когда установлено в true, приложение для продакшена будет собрано в MPA режиме. В режиме MPA по умолчанию поставляется 0kb JavaScript, в ущерб отключению кли

ентской навигации и требуется явное включение интерактивности.

Темизация

appearance

Тип: boolean | 'dark' | 'force-dark' | import('@vueuse/core').UseDarkOptions
По умолчанию: true

Включить темный режим (добавляя класс .dark к элементу <html>).

Если опция установлена в true, тема по умолчанию будет определяться предпочтительной цветовой схемой пользователя.
Если опция установлена в dark, тема будет темной по умолчанию, если пользователь не переключит ее вручную.
Если опция установлена в false, пользователи не смогут переключать тему.

Эта опция внедряет встроенный скрипт, который восстанавливает настройки пользователя из локального хранилища с использованием ключа vitepress-theme-appearance. Это гарантирует, что класс .dark применяется до отрисовки страницы, чтобы избежать мерцания.

appearance.initialValue может быть только 'dark' | undefined. Ссылки или геттеры не поддерживаются.

lastUpdated

Тип: boolean
По умолчанию: false

Получить временную метку последнего обновления для каждой страницы с использованием Git. Временная метка будет включена в данные каждой страницы, доступные через useData.

При использовании темы по умолчанию, включение этой опции будет отображать время последнего обновления каждой страницы. Вы можете настроить текст через опцию themeConfig.lastUpdatedText.

Настройка

markdown

Тип: MarkdownOption

Настройте опции парсера Markdown. VitePress использует Markdown-it в качестве парсера и Shiki для подсветки синтаксиса языков. Внутри этой опции вы можете передать различные опции, связанные с Markdown, чтобы они соответствовали вашим потребностям.

export default {
  markdown: {...}
}

Проверьте объявление типа и jsdocs для всех доступных опций.

vite

Тип: import('vite').UserConfig

Передайте сырую конфигурацию Vite внутреннему серверу разработки / сборщику Vite.

export default {
  vite: {
    // опции конфигурации Vite
  }
}

vue

Тип: import('@vitejs/plugin-vue').Options

Передайте сырые опции @vitejs/plugin-vue внутреннему экземпляру плагина.

export default {
  vue: {
    // опции @vitejs/plugin-vue
  }
}

Хуки сборки

Хуки сборки VitePress позволяют добавлять новые функции и поведение на ваш сайт:

Карта сайта
Индексирование поиска
PWA
Телепорты

buildEnd

Тип: (siteConfig: SiteConfig) => Awaitable<void>

buildEnd - это хук CLI сборки, он будет запущен после завершения сборки (SSG), но перед выходом из процесса CLI VitePress.

export default {
  async buildEnd(siteConfig) {
    // ...
  }
}

postRender

Тип: (context: SSGContext) => Awaitable<SSGContext | void>

postRender - это хук сборки, вызываемый после завершения рендеринга SSG. Он позволит вам обрабатывать содержимое телепортов во время SSG.

export default {
  async postRender(context) {
    // ...
  }
}

interface SSGContext {
  content: string
  teleports?: Record<string, string>
  [key: string]: any
}

transformHead

Тип: (context: TransformContext) => Awaitable<HeadConfig[]>

transformHead - это хук сборки для преобразования заголовка перед генерацией каждой страницы. Он позволит вам добавлять записи в заголовок, которые не могут быть статически добавлены в вашу конфигурацию VitePress. Вам нужно вернуть только дополнительные записи, они будут автоматически объединены с существующими.

WARNING

Не изменяйте ничего внутри context.

export default {
  async transformHead(context) {
    // ...
  }
}

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:

export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push([
      'meta',
      {
        name: 'og:title',
        content:
          pageData.frontmatter.layout === 'home'
            ? `VitePress`
            : `${pageData.title} | VitePress`
      }
    ])
  }
}

Пример: Добавление канонической ссылки `<link>`

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

Тип: (code: string, id: string, context: TransformContext) => Awaitable<string | void>

transformHtml - это хук сборки для преобразования содержимого каждой страницы перед сохранением на диск.

WARNING

Не изменяйте ничего внутри context. Кроме того, изменение содержимого HTML может вызвать проблемы с гидратацией во время выполнения.

export default {
  async transformHtml(code, id, context) {
    // ...
  }
}

transformPageData

Тип: (pageData: PageData, context: TransformPageContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>

transformPageData - это хук для преобразования pageData каждой страницы. Вы можете напрямую изменять pageData или возвращать измененные значения, которые будут объединены с данными страницы.

WARNING

Не изменяйте ничего внутри context и будьте осторожны, так как это может повлиять на производительность сервера разработки, особенно если у вас есть сетевые запросы или тяжелые вычисления (например, генерация изображений) в хуке. Вы можете проверить process.env.NODE_ENV === 'production' для условной логики.

export default {
  async transformPageData(pageData, { siteConfig }) {
    pageData.contributors = await getPageContributors(pageData.relativePath)
  }

  // или возвращайте данные для объединения
  async transformPageData(pageData, { siteConfig }) {
    return {
      contributors: await getPageContributors(pageData.relativePath)
    }
  }
}

interface TransformPageContext {
  siteConfig: SiteConfig
}

Конфигурация сайта ​

Обзор ​

Разрешение конфигурации ​

Интеллектуальное автодополнение конфигурации ​

Типизированная конфигурация темы ​

Конфигурация Vite, Vue & Markdown ​

Метаданные сайта ​

title ​

titleTemplate ​

description ​

head ​

Пример: Добавление favicon ​

Пример: Добавление шрифтов Google ​

Пример: Регистрация сервис-воркера ​

Пример: Использование Google Analytics ​

lang ​

base ​

Маршрутизация ​

cleanUrls ​

rewrites ​

Сборка ​

srcDir ​

srcExclude ​

outDir ​

assetsDir ​

cacheDir ​

ignoreDeadLinks ​

mpa экспериментально ​

Темизация ​

appearance ​

lastUpdated ​

Настройка ​

markdown ​

vite ​

vue ​

Хуки сборки ​

buildEnd ​

postRender ​

transformHead ​

Пример: Добавление канонической ссылки <link> ​

transformHtml ​

transformPageData ​

Конфигурация сайта

Обзор

Разрешение конфигурации

Интеллектуальное автодополнение конфигурации

Типизированная конфигурация темы

Конфигурация Vite, Vue & Markdown

Метаданные сайта

title

titleTemplate

description

head

Пример: Добавление favicon

Пример: Добавление шрифтов Google

Пример: Регистрация сервис-воркера

Пример: Использование Google Analytics

lang

base

Маршрутизация

cleanUrls

rewrites

Сборка

srcDir

srcExclude

outDir

assetsDir

cacheDir

ignoreDeadLinks

mpa экспериментально

Темизация

appearance

lastUpdated

Настройка

markdown

vite

vue

Хуки сборки

buildEnd

postRender

transformHead

Пример: Добавление канонической ссылки `<link>`

transformHtml

transformPageData