@ -6,7 +6,7 @@ description: Узнайте, как ссылаться на статически
## Ссылки на статические ресурсы {#referencing-static-assets}
Все файлы Markdown компилируются в компоненты Vue и обрабатываются [Vite](https://vite.dev/guide/assets.html). Вы можете, **и должны**, ссылаться на любые ресурсы, используя относительные URL:
Все файлы Markdown компилируются в компоненты Vue и обрабатываются [Vite](https://vite-docs.ru/guide/assets.html). Вы можете, **и должны**, ссылаться на любые ресурсы, используя относительные URL:
@ -62,11 +62,14 @@ import Layout from './Layout.vue'
export default {
Layout,
enhanceApp({ app, router, siteData }) {
// ...
// app.component(...)
// app.use(...)
}
}
```
Хук `enhanceApp` предоставляет доступ к [экземпляру приложения Vue](https://ru.vuejs.org/api/application.html) и другим данным времени выполнения. Это позволяет, например, [регистрировать глобальные компоненты](./extending-default-theme.md#registering-global-components), интегрироваться с библиотеками Vue и выполнять другие подобные задачи.
Значение `router` представляет собой тот же экземпляр маршрутизатора VitePress, который возвращает [`useRouter()`](../reference/runtime-api#userouter). Чтобы отслеживать изменения маршрутов, назначьте обработчики для маршрутизатора:
```ts [.vitepress/theme/index.ts]
@ -226,10 +229,10 @@ export default {
```ts [.vitepress/config.ts]
import baseConfig from 'awesome-vitepress-theme/config'
import { defineConfigWithTheme } from 'vitepress'
import { defineConfig } from 'vitepress'
import type { ThemeConfig } from 'awesome-vitepress-theme'
Поскольку мы используем Vite, можно применять [глобальную функцию импорта](https://vite.dev/guide/features.html#glob-import) Vite для автоматической регистрации каталога компонентов.
Поскольку мы используем Vite, можно применять [глобальную функцию импорта](https://vite-docs.ru/guide/features.html#glob-import) Vite для автоматической регистрации каталога компонентов.
## Переопределение внутренних компонентов {#overriding-internal-components}
Вы можете использовать [псевдонимы](https://vite.dev/config/shared-options.html#resolve-alias) Vite, чтобы заменить стандартные компоненты темы на свои собственные:
Вы можете использовать [псевдонимы](https://vite-docs.ru/config/shared-options.html#resolve-alias) Vite, чтобы заменить стандартные компоненты темы на свои собственные:
VitePress — это пакет, предназначенный только для ESM. Не используйте `require()` для импорта, и убедитесь, что ближайший `package.json` содержит `"type": "module"`, или измените расширение соответствующих файлов, например, `.vitepress/config.js` на `.mjs`/`.mts`. Более подробную информацию см. в [Руководстве по устранению неполадок Vite](https://vite.dev/guide/troubleshooting.html#this-package-is-esm-only). Кроме того, внутри асинхронных контекстов CJS можно использовать `await import('vitepress')` вместо этого.
VitePress — это пакет, предназначенный только для ESM. Не используйте `require()` для импорта, и убедитесь, что ближайший `package.json` содержит `"type": "module"`, или измените расширение соответствующих файлов, например, `.vitepress/config.js` на `.mjs`/`.mts`. Более подробную информацию см. в [Руководстве по устранению неполадок Vite](https://vite-docs.ru/guide/troubleshooting.html#this-package-is-esm-only). Кроме того, внутри асинхронных контекстов CJS можно использовать `await import('vitepress')` вместо этого.
**Совет:** Конфигурационный файл можно хранить и в `docs/.vitepress/config/index.ts`. Это может помочь вам организовать работу, создав конфигурационный файл для каждой локали, а затем объединить и экспортировать их из `index.ts`.
Строки, встраиваемые в страницы Markdown-рендерером, — стандартные заголовки [пользовательских контейнеров](./markdown#custom-containers), [оповещений в стиле GitHub](./markdown#github-flavored-alerts), а также строки кнопки копирования кода — можно переопределить для каждой локали с помощью ключа `markdown` в записи соответствующей локали:
```ts [docs/.vitepress/config.ts]
import { defineConfig } from 'vitepress'
export default defineConfig({
locales: {
root: { label: 'English', lang: 'en' },
zh: {
label: 'Русский',
lang: 'ru',
markdown: {
container: {
tipLabel: 'Подсказка',
warningLabel: 'Предупреждение'
// ...остальные метки, а также заголовки `customContainers`
},
codeCopyButton: {
tooltipText: 'Копировать код',
copiedText: 'Скопировано'
}
}
}
}
})
```
Если значение не задано для конкретной локали, используется соответствующее значение из параметров `markdown` корневого уровня. Записи локалей могут переопределять только заголовки контейнеров, зарегистрированных на корневом уровне — регистрация новых контейнеров отдельно для каждой локали не поддерживается. Также обратите внимание, что, поскольку Markdown-рендерер создаётся один раз для всего сайта, эти параметры можно объявлять только в основном файле конфигурации, а не в дополнительных конфигурационных файлах.
## Отдельный каталог для каждой локали {#separate-directory-for-each-locale}
@ -63,7 +63,7 @@ VitePress поставляется со встроенными расширен
Исходящие ссылки автоматически получают значение `target="_blank" rel="noreferrer"`:
- [vuejs.org](https://vuejs.org)
- [vuejs.org](https://ru.vuejs.org)
- [VitePress on GitHub](https://github.com/vuejs/vitepress)
## Метаданные {#frontmatter}
@ -101,6 +101,36 @@ lang: ru-RU
| столбец 2 | отцентрован | \$12 |
| полосатые строки | как полоски у зебры | \$1 |
## Списки задач {#task-lists}
**Разметка**
```md
- [ ] Написать пресс-релиз
- [x] Обновить сайт
```
**Результат**
- [ ] Написать пресс-релиз
- [x] Обновить сайт
## Сноски {#footnotes}
**Разметка**
```md
Сноски поддерживаются[^1], включая встроенные^[Это встроенная сноска.].
[^1]: Определения могут содержать **Markdown** и отображаются в конце страницы.
```
**Результат**
Сноски поддерживаются[^1], включая встроенные^[Это встроенная сноска.].
[^1]: Определения могут содержать **Markdown** и отображаются в конце страницы.
## Эмодзи :tada: {#emoji}
**Разметка**
@ -234,6 +264,79 @@ export default defineConfig({
})
```
На многоязычных сайтах эти метки также можно переопределить для каждой локали отдельно — см. раздел [Локализованные Markdown-строки](./i18n#per-locale-markdown-strings).
### Регистрация новых контейнеров {#registering-new-containers}
Помимо встроенных типов, вы можете зарегистрировать дополнительные контейнеры, сопоставив их имена с их заголовками по умолчанию:
```ts
// config.ts
export default defineConfig({
// ...
markdown: {
container: {
customContainers: {
success: 'УСПЕШНО'
}
}
}
// ...
})
```
Зарегистрированные имена работают так же, как и встроенные — включая пользовательские заголовки, атрибуты и [синтаксис оповещений в стиле GitHub](#github-flavored-alerts):
```md
:::
Вы успешно завершили руководство!
:::
> [!SUCCESS] Пользовательский заголовок
> Этот вариант отображается точно так же.
```
Для новых контейнеров стили по умолчанию отсутствуют, поэтому добавьте их в своей теме, используя имя контейнера в качестве класса. В этом примере палитра темы по умолчанию уже содержит подходящие цвета:
```css
/* .vitepress/theme/custom.css */
.custom-block.success {
border-color: transparent;
color: var(--vp-c-text-1);
background-color: var(--vp-c-success-soft);
}
```
### Вложенность {#nesting}
Маркеры `:::` подчиняются тем же правилам, что и ограждения блоков кода (` ``` `): ограждение закрывается только соответствующим маркером, который имеет **не меньшую длину**, чем открывающий. Чтобы вкладывать контейнеры друг в друга (или сочетать их с [группами кодов](#code-groups)), сделайте внешнее ограждение длиннее внутренних.
**Разметка**
`````md
:::: info Внешний контейнер
Этот блок содержит ещё один контейнер.
::: details Внутренний контейнер
```js
console.log('Привет, VitePress!')
```
:::
::::
`````
**Результат**
:::: info Внешний контейнер
Этот блок содержит ещё один контейнер.
::: details Внутренний контейнер
```js
console.log('Привет, VitePress!')
```
:::
::::
### Дополнительные атрибуты {#additional-attributes}
Вы можете добавить дополнительные атрибуты к пользовательским контейнерам. Мы используем [@mdit/plugin-attrs](https://mdit-plugins.github.io/attrs.html) для этой функции, и она поддерживается почти для всех элементов Markdown. Например, можно установить атрибут `open`, чтобы сделать блок подробностей открытым по умолчанию:
Специальный атрибут `no-title` отображает контейнер без элемента заголовка (он не влияет на `details`, поскольку этому контейнеру всегда требуется сводка):
**Разметка**
```md
::: tip {no-title}
Хотите просто попробовать? Перейдите сразу к разделу [Первые шаги](./getting-started).
:::
```
**Результат**
::: tip {no-title}
Хотите просто попробовать? Перейдите сразу к разделу [Первые шаги](./getting-started).
:::
### `raw` {#raw}
Это специальный контейнер, который можно использовать для предотвращения конфликтов стилей и маршрутизаторов с VitePress. Это особенно полезно при документировании библиотек компонентов.
## Оповещения в стиле GitHub {#github-flavored-alerts}
VitePress также поддерживает [Оповещения в стиле GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) для отображения в виде вставок. Они будут отображаться так же, как и [пользовательские контейнеры](#custom-containers).
VitePress также поддерживает [Оповещения в стиле GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) для отображения в виде вставок. Они будут отображаться так же, как и [пользовательские контейнеры](#custom-containers).В отличие от GitHub, текст, размещённый сразу после маркера, становится заголовком оповещения (`> [!NOTE] Пользовательский заголовок`), и здесь также работают [контейнеры, зарегистрированные вами самостоятельно](#registering-new-containers).
```md
> [!NOTE]
@ -679,6 +798,16 @@ const line4 = 'Строка 4'
<<<@/snippets/snippet-with-region.js#snippet{1}
Если файл содержит несколько регионов с одинаковым именем, все они импортируются и объединяются — включая регионы, записанные с использованием разных стилей комментариев, например `<!-- #region -->` в шаблоне и `// #region` в скрипте одного и того же однофайлового компонента Vue. Комментарии-маркеры, ограничивающие регионы, удаляются из результата. Установите `markdown.snippet.stripRegionMarkers` в `'all'`, чтобы также удалить маркеры других стилей комментариев, вложенные в регион, или в `false`, чтобы сохранить все маркеры.
:::tip
Имена регионов могут содержать буквы, цифры, символы `_`, `-` и `.`. Поскольку имя региона берётся из конца пути, для файла, имя которого само содержит символ `#`, необходимо явно указать регион — используйте `<<< ./my#file.js#region` вместо `<<< ./my#file.js`.
:::
:::warning
Импорт файла или региона, который не существует, вызывает ошибку сборки. Установите `markdown.snippet.silent: true`, чтобы вместо этого записывать предупреждение в журнал и ничего не выводить.
:::
Кроме того, можно указать язык внутри фигурных скобок (`{}`) следующим образом:
```md
@ -693,7 +822,9 @@ const line4 = 'Строка 4'
<<<@/snippets/snippet.cs{1,2,4-6c#:line-numbers}
```
Это полезно, если исходный язык нельзя определить по расширению вашего файла.
Это полезно, если исходный язык нельзя определить по расширению вашего файла. Автоматически определяются только буквенно-цифровые расширения, поэтому для таких файлов, как `main.c++` или `scss.code-snippets`, язык необходимо указывать явно.
Всё, что следует после языка внутри фигурных скобок, передаётся в блок кода как дополнительные атрибуты. Например, `<<< @/snippets/snippet.ts{ts twoslash}` включает обработку twoslash, если настроен пакет [`@shikijs/vitepress-twoslash`](https://shiki.style/packages/vitepress#twoslash). Обратите внимание, что атрибуты не могут содержать квадратные скобки.
## Группы кодов {#code-groups}
@ -901,7 +1032,7 @@ export default config
```
::: warning ПРЕДУПРЕЖДЕНИЕ
Обратите внимание, что это не приводит к ошибкам, если ваш файл отсутствует. Поэтому при использовании этой функции убедитесь, что содержимое отображается так, как ожидается.
Включение файла, региона, якоря заголовка или диапазона строк, который не существует, приводит к ошибке сборки. Установите `markdown.include.silent: true`, чтобы вместо этого выводить предупреждение в журнал и пропускать включение.
:::
Вместо регионов VS Code вы также можете использовать якоря заголовков, чтобы включить определённый раздел файла. Например, если у вас есть заголовок в вашем markdown-файле, например:
@ -951,6 +1082,28 @@ export default config
<!--@@include: ./parts/basics.md#custom-id-->
```
Относительные ссылки и изображения внутри включаемых файлов разрешаются относительно расположения **включаемого** файла, поэтому частичный файл может ссылаться на соседние файлы независимо от того, с какой страницы он подключён. Установите `markdown.include.rebaseRelativeUrls: false`, чтобы они вместо этого разрешались относительно страницы, которая выполняет включение.
### Включение файлов с кодом {#including-code-files}
Поскольку включение выполняется до разбора блоков кода, эта директива также работает внутри кодовых ограждений. В сочетании с диапазоном строк это позволяет показывать только часть файла с кодом — это альтернатива [импорту сниппетов](#import-code-snippets), когда использование регионов невозможно:
Обратите внимание, что включаемые строки вставляются дословно (отступы сохраняются), а если содержимое включает символы обратных кавычек (`` ` ``), необходимо использовать более длинное внешнее ограждение блока кода.
## Математические уравнения {#math-equations}
В настоящее время эта фича предоставляется по желанию. Чтобы включить её, вам нужно установить `markdown-it-mathjax3` и установить значение `true` для опции `markdown.math` в вашем файле конфигурации:
Вы также можете условно импортировать зависимость с помощью флага `import.meta.env.SSR` (часть [env-переменных Vite](https://vite.dev/guide/env-and-mode.html#env-variables)):
Вы также можете условно импортировать зависимость с помощью флага `import.meta.env.SSR` (часть [переменных окружения Vite](https://vite-docs.ru/guide/env-and-mode.html#env-variables)):
@ -201,7 +201,7 @@ HTML, обёрнутый `<code>`, будет отображаться как е
## Использование препроцессоров CSS {#using-css-pre-processors}
VitePress имеет [встроенную поддержку](https://vite.dev/guide/features.html#css-pre-processors) для препроцессоров CSS: файлы `.scss`, `.sass`, `.less`, `.styl` и `.stylus`. Для них не нужно устанавливать специфические для Vite плагины, но сам соответствующий препроцессор должен быть установлен:
VitePress имеет [встроенную поддержку](https://vite-docs.ru/guide/features.html#css-pre-processors) для препроцессоров CSS: файлы `.scss`, `.sass`, `.less`, `.styl` и `.stylus`. Для них не нужно устанавливать специфические для Vite плагины, но сам соответствующий препроцессор должен быть установлен:
@ -16,7 +16,7 @@ VitePress — это [Генератор статических сайтов](ht
VitePress поставляется с темой по умолчанию, предназначенной для технической документации. Именно она обеспечивает работу этой страницы, которую вы сейчас читаете, а также документации для [Vite](https://vite-docs.ru/), [Rollup](https://rollupjs.org/), [Pinia](https://pinia-ru.netlify.app), [VueUse](https://vueuse.org/), [Vitest](https://vitest.dev/), [D3](https://d3js.org/), [UnoCSS](https://unocss.dev/), [Iconify](https://iconify.design/) и [многих других](https://github.com/search?q=/%22vitepress%22:+/+path:/(?:package%7Cdeno)%5C.jsonc?$/+NOT+is:fork+NOT+is:archived&type=code).
[Официальная документация Vue.js](https://vuejs.org/) также основана на VitePress, но использует кастомную тему, общую для нескольких переводов.
[Официальная документация Vue.js](https://ru.vuejs.org/) также основана на VitePress, но использует кастомную тему, общую для нескольких переводов.
- **Блоги, портфолио и маркетинговые сайты**
@ -28,7 +28,7 @@ VitePress — это [Генератор статических сайтов](ht
VitePress стремится обеспечить отличные возможности для разработчиков при работе с содержимым в формате Markdown.
- **[На базе Vite:](https://vite.dev/)** мгновенный запуск сервера, правки всегда отражаются мгновенно (<100мс)безперезагрузкистраницы.
- **[На базе Vite:](https://vite-docs.ru/)** мгновенный запуск сервера, правки всегда отражаются мгновенно (<100мс)безперезагрузкистраницы.
- **[Встроенные расширения Markdown:](./markdown)** Frontmatter, таблицы, подсветка синтаксиса... называйте как хотите. В частности, VitePress предоставляет множество расширенных возможностей для работы с блоками кода, что делает его идеальным для создания технической документации.
Если структура вашей документации содержит глубоко вложенные каталоги или группы, расположенные в одном подкаталоге, вы можете использовать параметр `base`, чтобы автоматически добавлять префикс пути ко всем вложенным элементам `items` внутри этой группы. Это избавляет от необходимости повторять один и тот же префикс пути для каждого `link`.
Параметр `base` поддерживается как в конфигурациях с несколькими боковыми панелями, так и во вложенных группах боковой панели.
### В нескольких боковых панелях {#in-multiple-sidebars}
Вы можете определить `base` в корне конфигурации раздела боковой панели:
```js {5}
export default {
themeConfig: {
sidebar: {
'/guide/': {
base: '/guide/',
items: [
// Эта ссылка будет разрешена в `/guide/introduction`
{ text: 'Введение', link: 'introduction' },
// Эта ссылка будет разрешена в `/guide/getting-started`
{ text: 'Первые шаги', link: 'getting-started' }
]
}
}
}
}
```
### Во вложенных группах {#in-nested-groups}
Параметр `base` также можно использовать во вложенных группах боковой панели. Он применяется к непосредственным дочерним элементам этой группы:
```js{6,13}
export default {
themeConfig: {
sidebar: [
{
text: 'Справочник',
base: '/reference/',
items: [
// Эта ссылка будет разрешена в `/reference/site-config`
Каталог для файлов кэша, относительно [корня проекта](../guide/routing#root-and-source-directory). См. также: [cacheDir](https://vite.dev/config/shared-options.html#cachedir).
Каталог для файлов кэша, относительно [корня проекта](../guide/routing#root-and-source-directory). См. также: [cacheDir](https://vite-docs.ru/config/shared-options.html#cachedir).
```ts
export default {
@ -560,7 +560,7 @@ export default {
- Тип: `import('vite').UserConfig`
Передаёт необработанную [конфигурацию Vite](https://vite.dev/config/) внутреннему серверу разработки / сборщику Vite.
Передаёт необработанную [конфигурацию Vite](https://vite-docs.ru/config/) внутреннему серверу разработки / сборщику Vite.
Bugo
3 weeks ago
committed by
GitHub