VitePress поставляется со встроенными расширениями Markdown.
## Якоря заголовков {#header-anchors}
К заголовкам автоматически применяются якорные ссылки. Отрисовку якорей можно настроить с помощью опции `markdown.anchor`.
### Пользовательские якоря {#custom-anchors}
Чтобы указать пользовательский тег якоря для заголовка, а не использовать автоматически сгенерированный, добавьте суффикс к заголовку:
```
# Использование пользовательских якорей {#мой-якорь}
```
Это позволит вам ссылаться на заголовок как `#мой-якорь` вместо стандартного `#использование-пользовательских-якорей`.
## Ссылки {#links}
Особое внимание уделяется как внутренним, так и внешним ссылкам.
### Внутренние ссылки {#internal-links}
Внутренние ссылки преобразуются в ссылки маршрутизатора для навигации SPA. Кроме того, каждый `index.md`, содержащийся в каждом подкаталоге, будет автоматически преобразован в `index.html`, с соответствующим URL `/`.
Например, при следующей структуре каталогов:
```
.
├─ index.md
├─ foo
│ ├─ index.md
│ ├─ one.md
│ └─ two.md
└─ bar
├─ index.md
├─ three.md
└─ four.md
```
И при условии, что вы находитесь в `foo/one.md`:
```md
[Home](/) <!-- отправляет пользователя в корневой index.md -->
[foo](/foo/) <!-- отправляет пользователя на страницу index.html из каталога foo -->
[foo heading](./#heading) <!-- привязывает пользователя к заголовку в индексном файле foo -->
[bar - three](../bar/three) <!-- вы можете опустить расширение -->
[bar - three](../bar/three.md) <!-- вы можете добавить .md -->
[bar - four](../bar/four.html) <!-- или вы можете добавить .html -->
```
### Суффикс страницы {#page-suffix}
Страницы и внутренние ссылки по умолчанию генерируются с суффиксом `.html`.
### Внешние ссылки {#external-links}
Исходящие ссылки автоматически получают значение `target="_blank" rel="noreferrer"`:
- [vuejs.org](https://vuejs.org)
- [VitePress on GitHub](https://github.com/vuejs/vitepress)
## Метаданные {#frontmatter}
[Метаданные YAML](https://jekyllrb.com/docs/front-matter/) поддерживаются из коробки:
```yaml
---
title: Веду блог как хакер
lang: ru-RU
---
```
Эти данные будут доступны остальной части страницы, а также всем пользовательским и тематическим компонентам.
Более подробную информацию можно найти в главе [Метаданные](../reference/frontmatter-config).
Пользовательские контейнеры можно определить по их типам, заголовкам и содержимому.
### Заголовок по умолчанию {#default-title}
**Разметка**
```md
::: info
Это информация.
:::
::: tip
Это совет.
:::
::: warning
Это предупреждение.
:::
::: danger
Это сигнал об опасности.
:::
::: details
Это блок-спойлер.
:::
```
**Результат**
::: info
Это информация.
:::
::: tip
Это совет.
:::
::: warning
Это предупреждение.
:::
::: danger
Это сигнал об опасности.
:::
::: details
Это блок-спойлер.
:::
### Пользовательский заголовок {#custom-title}
Вы можете задать собственный заголовок, добавив текст сразу после «типа» контейнера.
**Разметка**
````md
::: danger СТОП
Опасная зона, остановитесь
:::
::: details Нажмите на меня, чтобы просмотреть код
```js
console.log('Привет, VitePress!')
```
:::
````
**Результат**
::: danger СТОП
Опасная зона, остановитесь
:::
::: details Нажмите на меня, чтобы просмотреть код
```js
console.log('Привет, VitePress!')
```
:::
Кроме того, вы можете установить пользовательские заголовки глобально, добавив следующее содержимое в конфигурацию сайта, полезное, если вы пишете не на английском языке:
```ts
// config.ts
export default defineConfig({
// ...
markdown: {
container: {
tipLabel: 'СОВЕТ',
warningLabel: 'ПРЕДУПРЕЖДЕНИЕ',
dangerLabel: 'ОПАСНОСТЬ',
infoLabel: 'ИНФОРМАЦИЯ',
detailsLabel: 'Подробная информация'
}
}
// ...
})
```
### `raw` {#raw}
Это специальный контейнер, который можно использовать для предотвращения конфликтов стилей и маршрутизаторов с VitePress. Это особенно полезно при документировании библиотек компонентов. Вы также можете посмотреть [whyframe](https://whyframe.dev/docs/integrations/vitepress) для лучшей изоляции.
**Syntax**
```md
::: raw
Заворачивается в <divclass="vp-raw">
:::
```
Класс `vp-raw` можно использовать и непосредственно на элементах. Изоляция стиля в настоящее время осуществляется по желанию:
- Установите `postcss`с помощью предпочитаемого менеджера пакетов:
```sh
$ npm add -D postcss
```
- Создайте файл с именем `docs/postcss.config.mjs` и добавьте в него следующее:
```js
import { postcssIsolateStyles } from 'vitepress'
export default {
plugins: [postcssIsolateStyles()]
}
```
Он использует [`postcss-prefix-selector`](https://github.com/postcss/postcss-load-config) под капотом. Вы можете передать ему параметры следующим образом:
```js
postcssIsolateStyles({
includeFiles: [/vp-doc\.css/] // по умолчанию /base\.css/
})
```
## Оповещения в стиле 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).
```md
> [!NOTE]
> Выделяет информацию, на которую пользователи должны обратить внимание, даже при беглом просмотре.
> [!TIP]
> Дополнительная информация, которая поможет пользователю добиться большего успеха.
> [!IMPORTANT]
> Важнейшая информация, необходимая пользователям для достижения успеха.
> [!WARNING]
> Критический контент, требующий немедленного внимания пользователей из-за потенциальных рисков.
> [!CAUTION]
> Негативные потенциальные последствия того или иного действия.
```
> [!NOTE]
> Выделяет информацию, на которую пользователи должны обратить внимание, даже при беглом просмотре.
> [!TIP]
> Дополнительная информация, которая поможет пользователю добиться большего успеха.
> [!IMPORTANT]
> Важнейшая информация, необходимая пользователям для достижения успеха.
> [!WARNING]
> Критический контент, требующий немедленного внимания пользователей из-за потенциальных рисков.
> [!CAUTION]
> Негативные потенциальные последствия того или иного действия.
## Подсветка синтаксиса в блоках кода {#syntax-highlighting-in-code-blocks}
VitePress использует [Shiki](https://github.com/shikijs/shiki) для выделения синтаксиса языка в блоках кода Markdown с помощью цветного текста. Shiki поддерживает широкий спектр языков программирования. Всё, что вам нужно сделать, это добавить правильный псевдоним языка к начальным значкам блока кода:
**Разметка**
````
```js
export default {
name: 'MyComponent',
// ...
}
```
````
````
```html
<ul>
<liv-for="todo in todos":key="todo.id">
{{ todo.text }}
</li>
</ul>
```
````
**Результат**
```js
export default {
name: 'MyComponent'
// ...
}
```
```html
<ul>
<liv-for="todo in todos":key="todo.id">{{ todo.text }}</li>
</ul>
```
[Список всех поддерживаемых языков](https://shiki.style/languages).
Вы также можете настроить тему подсветки синтаксиса в конфигурации приложения. Более подробную информацию см. в секции [`markdown`](../reference/site-config#markdown).
## Выделение строк в блоках кода {#line-highlighting-in-code-blocks}
**Разметка**
````
```js{4}
export default {
data () {
return {
msg: 'Подсвечено!'
}
}
}
```
````
**Результат**
```js{4}
export default {
data () {
return {
msg: 'Подсвечено!'
}
}
}
```
Помимо одной строки, вы можете указать несколько отдельных строк, диапазонов или и то, и другое:
- Диапазоны строк и отдельные строки, например: `{4,7-13,16,23-27,40}`
**Разметка**
````
```js{1,4,6-8}
export default { // Подсвечено
data () {
return {
msg: `Подсвечено!
Эта строка не выделена,
но эта и две следующих - да.`,
motd: 'VitePress - это потрясающе',
lorem: 'ipsum'
}
}
}
```
````
**Результат**
```js{1,4,6-8}
export default { // Подсвечено
data () {
return {
msg: `Подсвечено!
Эта строка не выделена,
но эта и две следующих - да.`,
motd: 'VitePress - это потрясающе',
lorem: 'ipsum',
}
}
}
```
Кроме того, можно выделять непосредственно в строке, используя комментарий `// [!code highlight]`.
**Разметка**
````
```js
export default {
data () {
return {
msg: 'Подсвечено!' // [!!code highlight]
}
}
}
```
````
**Результат**
```js
export default {
data() {
return {
msg: 'Подсвечено!' // [!code highlight]
}
}
}
```
## Фокус в блоках кода {#focus-in-code-blocks}
Добавление комментария `// [!code focus]` к строке сфокусирует её и размоет остальные части кода.
Кроме того, вы можете задать количество строк для фокусировки с помощью `// [!code focus:<lines>]`.
**Разметка**
````
```js
export default {
data () {
return {
msg: 'Фокус!' // [!!code focus]
}
}
}
```
````
**Результат**
```js
export default {
data() {
return {
msg: 'Фокус!' // [!code focus]
}
}
}
```
## Подсветка различий в блоках кода {#colored-diffs-in-code-blocks}
Добавление в строку комментариев `// [!code --]` или `// [!code ++]` создаст diff этой строки, сохраняя цвета блока кода.
**Разметка**
````
```js
export default {
data () {
return {
msg: 'Удалено' // [!!code --]
msg: 'Добавлено' // [!!code ++]
}
}
}
```
````
**Результат**
```js
export default {
data () {
return {
msg: 'Удалено' // [!code --]
msg: 'Добавлено' // [!code ++]
}
}
}
```
## Ошибки и предупреждения в блоках кода {#errors-and-warnings-in-code-blocks}
Добавление в строку комментариев `// [!code warning]` или `// [!code error]` окрасит её соответствующим образом.
**Разметка**
````
```js
export default {
data () {
return {
msg: 'Ошибка', // [!!code error]
msg: 'Предупреждение' // [!!code warning]
}
}
}
```
````
**Результат**
```js
export default {
data() {
return {
msg: 'Ошибка', // [!code error]
msg: 'Предупреждение' // [!code warning]
}
}
}
```
## Номера строк {#line-numbers}
Вы можете включить нумерацию строк для каждого блока кода в конфигурации:
```js
export default {
markdown: {
lineNumbers: true
}
}
```
Более подробную информацию см. в секции [`markdown`](../reference/site-config#markdown).
Вы можете добавить метки `:line-numbers` / `:no-line-numbers` в ваши ограждённые блоки кода, чтобы переопределить значение, установленное в конфиге.
Вы также можете настроить номер начальной строки, добавив `=` после `:line-numbers`. Например, `:line-numbers=2` означает, что номера строк в блоках кода будут начинаться с`2`.
**Разметка**
````md
```ts {1}
// опция line-numbers по умолчанию отключена
const line2 = 'Строка 2'
const line3 = 'Строка 3'
```
```ts:line-numbers {1}
// опция line-numbers включена
const line2 = 'Строка 2'
const line3 = 'Строка 3'
```
```ts:line-numbers=2 {1}
// опция line-numbers включена, нумерация начинается с 2
const line3 = 'Строка 3'
const line4 = 'Строка 4'
```
````
**Результат**
```ts {1}
// опция line-numbers по умолчанию отключена
const line2 = 'Строка 2'
const line3 = 'Строка 3'
```
```ts:line-numbers {1}
// опция line-numbers включена
const line2 = 'Строка 2'
const line3 = 'Строка 3'
```
```ts:line-numbers=2 {1}
// опция line-numbers включена, нумерация начинается с 2
const line3 = 'Строка 3'
const line4 = 'Строка 4'
```
## Импорт фрагментов кода {#import-code-snippets}
Вы можете импортировать фрагменты кода из существующих файлов, используя следующий синтаксис:
```md
<<<@/filepath
```
[Выделение строк](#line-highlighting-in-code-blocks) тоже поддерживается:
```md
<<<@/filepath{highlightLines}
```
**Разметка**
```md
<<<@/snippets/snippet.js{2}
```
**Файл с кодом**
<<<@/snippets/snippet.js
**Результат**
<<<@/snippets/snippet.js{2}
::: tip СОВЕТ
Значение `@` соответствует корню источника. По умолчанию это корень проекта VitePress, если не настроен `srcDir`. Альтернативно вы также можете импортировать из относительных путей:
```md
<<<../snippets/snippet.js
```
:::
Вы также можете использовать [регион VS Code](https://code.visualstudio.com/docs/editor/codebasics#_folding), чтобы включить только соответствующую часть файла кода. Имя пользовательского региона начинается с`#` после пути к файлу:
**Разметка**
```md
<<<@/snippets/snippet-with-region.js#snippet{1}
```
**Файл с кодом**
<<<@/snippets/snippet-with-region.js
**Результат**
<<<@/snippets/snippet-with-region.js#snippet{1}
Вы также можете указать язык внутри фигурных скобок (`{}`) следующим образом:
```md
<<<@/snippets/snippet.cs{c#}
<!--с подсветкой строк: -->
<<<@/snippets/snippet.cs{1,2,4-6c#}
<!--с номерами строк: -->
<<<@/snippets/snippet.cs{1,2,4-6c#:line-numbers}
```
Это полезно, если исходный язык нельзя определить по расширению вашего файла.
## Группы кодов {#code-groups}
Вы можете сгруппировать несколько блоков кода следующим образом:
**Разметка**
````md
::: code-group
```js [config.js]
/**
*@type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
```
```ts [config.ts]
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
```
:::
````
**Результат**
::: code-group
```js [config.js]
/**
*@type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default config
```
```ts [config.ts]
import type { UserConfig } from 'vitepress'
const config: UserConfig = {
// ...
}
export default config
```
:::
Вы также можете [импортировать фрагменты](#import-code-snippets) в группы кода:
**Разметка**
```md
::: code-group
<!-- по умолчанию в качестве заголовка используется имя файла -->
<<<@/snippets/snippet.js
<!-- но можно предоставить и индивидуальный вариант -->
Вы также можете добавить в префикс пути к Markdown символ `@`, он будет выступать в качестве корня источника. По умолчанию это корень проекта VitePress, если не настроена опция `srcDir`.
Например, вы можете включить относительный файл Markdown следующим образом:
**Разметка**
```md
# Документация
## Основы
<!--@include: ./parts/basics.md-->
```
**Файл части** (`parts/basics.md`)
```md
Некоторые вещи для начала.
### Конфигурация
Может быть создана с помощью `.foorc.json`.
```
**Эквивалентный код**
```md
# Документация
## Основы
Некоторые вещи для начала.
### Конфигурация
Может быть создана с помощью `.foorc.json`.
```
Он также поддерживает выбор диапазона строк:
**Разметка**
```md
# Документация
## Основы
<!--@include: ./parts/basics.md{3,}-->
```
**Файл части** (`parts/basics.md`)
```md
Некоторые вещи для начала.
### Конфигурация
Может быть создана с помощью `.foorc.json`.
```
**Эквивалентный код**
```md
# Документация
## Основы
### Конфигурация
Может быть создана с помощью `.foorc.json`.
```
Формат выбранного диапазона строк может быть следующим: `{3,}`, `{,10}`, `{1,10}`
::: warning ПРЕДУПРЕЖДЕНИЕ
Обратите внимание, что это не приводит к ошибкам, если ваш файл отсутствует. Поэтому при использовании этой функции убедитесь, что содержимое отображается так, как ожидается.
:::
## Математические уравнения {#math-equations}
В настоящее время эта фича предоставляется по желанию. Чтобы включить её, вам нужно установить `markdown-it-mathjax3` и установить значение `true` для опции `markdown.math` в вашем файле конфигурации:
```sh
npm add -D markdown-it-mathjax3
```
```ts
// .vitepress/config.ts
export default {
markdown: {
math: true
}
}
```
**Разметка**
```md
Когда $a \ne 0$, существует два решения $(ax^2 + bx + c = 0)$:
Вы можете включить ленивую загрузку для каждого изображения, добавленного через markdown, установив значение `true` для опции `lazyLoading` в вашем файле конфигурации:
```js
export default {
markdown: {
image: {
// ленивая загрузка изображений отключена по умолчанию
VitePress использует [markdown-it](https://github.com/markdown-it/markdown-it) для отрисовки Markdown. Многие из вышеперечисленных расширений реализованы с помощью пользовательских плагинов. Вы можете дополнительно настроить экземпляр `markdown-it`с помощью опции `markdown` в файле `.vitepress/config.js`:
