28 KiB

Raw Blame History Unescape Escape

outline
deep

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

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

Обзор

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

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

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

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

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

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

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 верхнего уровня. Например:

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

:::

Интеллектуальная настройка

Использование помощника defineConfig обеспечит интеллектуальный анализ опций конфигурации на основе TypeScript. Если ваша IDE поддерживает эту функцию, она должна работать как в 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: {
    // Tип `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
Можно переопределить для каждой страницы с помощью метаданных

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

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

export default {
  title: 'Мой замечательный сайт'
}

# Привет

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

titleTemplate

Тип: string | boolean
Можно переопределить для каждой страницы с помощью метаданных

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

export default {
  title: 'Мой замечательный сайт',
  titleTemplate: 'Пользовательский суффикс'
}

# Привет

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

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

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

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

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

description

Тип: string
По умолчанию: A VitePress site
Можно переопределить для каждой страницы с помощью метаданных

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

export default {
  description: 'A VitePress site'
}

head

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

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

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

Пример: Добавление значка сайта

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

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

export default {
  lang: 'en-US'
}

base

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

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

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

export default {
  base: '/base/'
}

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

cleanUrls

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

Если установить значение true, VitePress будет удалять из URL-адресов завершающий .html. Также смотрите Создание чистого URL-адреса.

::: warning Требуется поддержка сервера Для включения этой функции может потребоваться дополнительная настройка на вашей хостинговой платформе. Чтобы это сработало, ваш сервер должен быть способен обслуживать /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

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

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, шаблонов regex или пользовательских функций фильтрации.

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

metaChunk

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

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

mpa

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

Если установлено значение true, производственное приложение будет создано в режиме MPA. В режиме MPA по умолчанию используется 0 КБ 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), но до выхода из процесса VitePress CLI.

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

Пример: Добавление канонического URL-адреса `<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 ПРЕДУПРЕЖДЕНИЕ Не мутируйте ничего внутри контекста. Кроме того, изменение 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 и будьте осторожны, это может повлиять на производительность dev-сервера, особенно если у вас есть некоторые сетевые запросы или тяжёлые вычисления (например, генерация изображений) в хуке. Вы можете проверить 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
}

28 KiB Raw Blame History Unescape Escape