IT wiki ru

Appearance

Расширения Markdown ​

VitePress включает в себя встроенные расширения Markdown.

Якоря заголовков ​

Заголовки автоматически получают якорные ссылки. Настройка отображения якорей может быть сконфигурирована с помощью опции markdown.anchor.

Пользовательские якоря ​

Чтобы указать пользовательский якорь для заголовка вместо автоматически созданного, добавьте суффикс к заголовку:

# Использование пользовательских якорей

Это позволяет ссылаться на заголовок как #my-anchor вместо стандартного #using-custom-anchors.

Ссылки ​

Как внутренние, так и внешние ссылки получают специальную обработку.

Внутренние ссылки ​

Внутренние ссылки преобразуются в ссылки маршрутизатора для навигации 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
[Домой](/) <!-- отправляет пользователя на корневой index.md -->
[foo](/foo/) <!-- отправляет пользователя на index.html каталога foo -->
[заголовок foo](./#heading) <!-- якорь пользователя к заголовку в файле индекса foo -->
[bar - three](../bar/three) <!-- можно опустить расширение -->
[bar - three](../bar/three.md) <!-- можно добавить .md -->
[bar - four](../bar/four.html) <!-- или можно добавить .html -->

Суффикс страницы ​

Страницы и внутренние ссылки по умолчанию генерируются с суффиксом .html.

Внешние ссылки ​

Исходящие ссылки автоматически получают target="_blank" rel="noreferrer":

Frontmatter ​

YAML frontmatter поддерживается из коробки:

yaml
---
title: Блоггинг как хакер
lang: ru-RU
---

Эти данные будут доступны на остальной части страницы, вместе со всеми пользовательскими и тематическими компонентами.

Для получения дополнительной информации смотрите Frontmatter.

Таблицы в стиле GitHub ​

Ввод

md
| Таблицы       |      Есть     |  Круто |
| ------------- | :-----------: | -----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

Вывод

ТаблицыЕстьКруто
col 3 isright-aligned$1600
col 2 iscentered$12
zebra stripesare neat$1

Эмодзи 🎉 ​

Ввод

:tada: :100:

Вывод

🎉 💯

Список всех эмодзи доступен.

Оглавление ​

Ввод

[[toc]]

Вывод

Настройка отображения оглавления может быть сконфигурирована с помощью опции markdown.toc.

Контейнеры по умолчанию ​

Ввод

md
::: info
Это информационный блок.
:::

::: tip
Это совет.
:::

::: warning
Это предупреждение.
:::

::: danger
Это опасное предупреждение.
:::

::: details
Это блок с деталями.
:::

Вывод

INFO

Это информационный блок.

TIP

Это совет.

WARNING

Это предупреждение.

DANGER

Это опасное предупреждение.

Details

Это блок с деталями.

Пользовательские заголовки

Вы можете установить пользовательский заголовок, добавив текст сразу после "типа" контейнера.

Ввод

md
::: danger ОСТАНОВИТЕСЬ
Зона опасности, не продолжайте
:::

::: details Нажмите здесь, чтобы увидеть код
```js
console.log('Привет, VitePress!')
```
:::

Вывод

ОСТАНОВИТЕСЬ

Зона опасности, не продолжайте

Нажмите здесь, чтобы увидеть код
js
console.log('Привет, VitePress!')

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

ts
// config.ts
export default defineConfig({
  // ...
  markdown: {
    container: {
      tipLabel: 'Совет',
      warningLabel: 'Предупреждение',
      dangerLabel: 'Опасность',
      infoLabel: 'Информация',
      detailsLabel: 'Подробности'
    }
  }
  // ...
})

raw

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

Синтаксис

md
::: raw
Заключает в <div class="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 под капотом. Вы можете передать его опции следующим образом:

    js
    postcssIsolateStyles({
  includeFiles: [/vp-doc\.css/] // по умолчанию /base\.css/
})

Извините за путаницу. Вот продолжение перевода с учетом ваших указаний:

Оповещения в стиле GitHub ​

VitePress поддерживает оповещения в стиле GitHub для отображения в виде всплывающих подсказок. Они будут отображаться так же, как пользовательские контейнеры.

md
> [!NOTE]
> Подчеркивает информацию, на которую пользователи должны обратить внимание, даже при беглом просмотре.

> [!TIP]
> Дополнительная информация, чтобы помочь пользователю добиться большего успеха.

> [!IMPORTANT]
> Критически важная информация, необходимая для успеха пользователей.

> [!WARNING]
> Критическое содержание, требующее немедленного внимания пользователя из-за потенциальных рисков.

> [!CAUTION]
> Отрицательные потенциальные последствия действия.

Подсветка синтаксиса в блоках кода ​

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

Ввод

```js
export default {
  name: 'MyComponent',
  // ...
}
```
```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

Вывод

js
export default {
  name: 'MyComponent',
  // ...
}
html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

Список допустимых языков доступен на сайте Shiki.

Вы также можете настроить тему подсветки синтаксиса в конфигурации приложения. Пожалуйста, смотрите опции markdown для получения дополнительной информации.

Подсветка строк в блоках кода ​

Ввод

```js{4}
export default {
  data () {
    return {
      msg: 'Выделено!'
    }
  }
}
```

Вывод

js
export default {
  data () {
    return {
      msg: 'Выделено!'
    }
  }
}

Помимо одной строки, вы также можете указать несколько отдельных строк, диапазоны или и то, и другое:

  • Диапазоны строк: например, {5-8}, {3-10}, {10-17}
  • Несколько отдельных строк: например, {4,7,9}
  • Диапазоны строк и отдельные строки: например, {4,7-13,16,23-27,40}

Ввод

```js{1,4,6-8}
export default { // Выделено
  data () {
    return {
      msg: `Выделено!
      Эта строка не выделена,
      но эта и следующие 2 выделены.`,
      motd: 'VitePress - это здорово',
      lorem: 'ipsum'
    }
  }
}
```

Вывод

js
export default { // Выделено
  data () {
    return {
      msg: `Выделено!
      Эта строка не выделена,
      но эта и следующие 2 выделены.`,
      motd: 'VitePress - это здорово',
      lorem: 'ipsum',
    }
  }
}

Кроме того, возможно выделить строки непосредственно в строке, используя комментарий // [!code highlight].

Ввод

```js
export default {
  data () {
    return {
      msg: 'Выделено!' // [!!code highlight]
    }
  }
}
```

Вывод

js
export default {
  data() {
    return {
      msg: 'Выделено!'
    }
  }
}

Фокус в блоках кода ​

Добавление комментария // [!code focus] на строке сфокусирует её и размоет остальные части кода.

Кроме того, вы можете определить количество строк для фокусировки, используя // [!code focus:<lines>].

Ввод

```js
export default {
  data () {
    return {
      msg: 'Сфокусировано!' // [!!code focus]
    }
  }
}
```

Вывод

js
export default {
  data() {
    return {
      msg: 'Сфокусировано!'
    }
  }
}

Цветные различия в блоках кода ​

Добавление комментариев // [!code --] или // [!code ++] на строке создаст различие этой строки, сохраняя при этом цвета блока кода.

Ввод

```js
export default {
  data () {
    return {
      msg: 'Удалено' // [!!code --]
     

 msg: 'Добавлено' // [!!code ++]
    }
  }
}
```

Вывод

js
export default {
  data () {
    return {
      msg: 'Удалено'
      msg: 'Добавлено'
    }
  }
}

Ошибки и предупреждения в блоках кода ​

Добавление комментариев // [!code warning] или // [!code error] на строке окрасит её соответственно.

Ввод

```js
export default {
  data () {
    return {
      msg: 'Ошибка', // [!!code error]
      msg: 'Предупреждение' // [!!code warning]
    }
  }
}
```

Вывод

js
export default {
  data() {
    return {
      msg: 'Ошибка', 
      msg: 'Предупреждение'
    }
  }
}

Нумерация строк в блоках кода ​

Вы можете включить нумерацию строк для каждого блока кода через конфигурацию:

js
export default {
  markdown: {
    lineNumbers: true
  }
}

Пожалуйста, смотрите опции markdown для получения дополнительной информации.

Вы можете добавить :line-numbers / :no-line-numbers в свои блоки кода, чтобы переопределить значение, установленное в конфигурации.

Также вы можете настроить начальный номер строки, добавив = после :line-numbers. Например, :line-numbers=2 означает, что нумерация строк в блоках кода начнется с 2.

Ввод

md
```ts {1}
// нумерация строк отключена по умолчанию
const line2 = 'Это строка 2'
const line3 = 'Это строка 3'
```

```ts:line-numbers {1}
// нумерация строк включена
const line2 = 'Это строка 2'
const line3 = 'Это строка 3'
```

```ts:line-numbers=2 {1}
// нумерация строк включена и начинается с 2
const line3 = 'Это строка 3'
const line4 = 'Это строка 4'
```

Вывод

ts
// нумерация строк отключена по умолчанию
const line2 = 'Это строка 2'
const line3 = 'Это строка 3'
ts
// нумерация строк включена
const line2 = 'Это строка 2'
const line3 = 'Это строка 3'
ts
// нумерация строк включена и начинается с 2
const line3 = 'Это строка 3'
const line4 = 'Это строка 4'

Импорт фрагментов кода ​

Вы можете импортировать фрагменты кода из существующих файлов с помощью следующего синтаксиса:

md
<<< @/filepath

Это также поддерживает подсветку строк:

md
<<< @/filepath{highlightLines}

Ввод

md
<<< @/snippets/snippet.js{2}

Файл кода

js
export default function () {
  // ..
}

Вывод

js
export default function () {
  // ..
}

TIP

Значение @ соответствует корню исходного кода. По умолчанию это корень проекта VitePress, если не настроен srcDir. Кроме того, вы также можете импортировать из относительных путей:

md
<<< ../snippets/snippet.js

Вы также можете использовать регион VS Code для включения только соответствующей части файла кода. Вы можете указать пользовательское имя региона после #, следующего за путем к файлу:

Ввод

md
<<< @/snippets/snippet-with-region.js#snippet{1}

Файл кода

js
// #region snippet
function foo() {
  // ..
}
// #endregion snippet

export default foo

Вывод

js
function foo() {
  // ..
}

Вы можете также указать язык внутри скобок ({}), например:

md
<<< @/snippets/snippet.cs{c#}

<!-- с подсветкой строк: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#}

<!-- с нумерацией строк: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers}

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

Группы кода ​

Вы можете группировать несколько блоков кода следующим образом:

Ввод

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
```

:::

Вывод

js
/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config
ts
import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config

Вы также можете импортировать фрагменты в группы кода:

Ввод

md
::: code-group

<!-- имя файла используется в качестве заголовка по умолчанию -->

<<< @/snippets/snippet.js

<!-- вы также можете указать собственный заголовок -->

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [фрагмент с регионом]

:::

Вывод

js
export default function () {
  // ..
}
ts
function foo() {
  // ..
}

Включение файлов Markdown ​

Вы можете включить файл Markdown в другой файл Markdown, даже вложенный.

TIP

Вы также можете использовать префикс @ перед путем к файлу 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

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

Математические уравнения ​

В настоящее время это опционально. Чтобы включить его, вам нужно установить markdown-it-mathjax3 и установить markdown.math в true в вашем конфигурационном файле:

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)$, и они
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Уравнения Максвелла:**

| уравнение                                                                                                                                                                  | описание                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | дивергенция $\vec{\mathbf{B}}$ равна нулю                                               |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | ротор $\vec{\mathbf{E}}$ пропорционален скорости изменения $\vec{\mathbf{B}}$ |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _что?_                                                                                 |

Вывод

Когда a≠0, существует два решения для (ax2+bx+c=0), и они

x=−b±b2−4ac2a

Уравнения Максвелла:

уравнениеописание
∇⋅B→=0дивергенция B→ равна нулю
∇×E→+1c∂B→∂t=0→ротор E→ пропорционален скорости изменения B→
∇×B→−1c∂E→∂t=4πcj→∇⋅E→=4πρчто?

Ленивая загрузка изображений ​

Вы можете включить ленивую загрузку для каждого изображения, добавленного через markdown, установив lazyLoading в true в вашем конфигурационном файле:

js
export default {
  markdown: {
    image: {
      // ленивая загрузка изображений отключена по умолчанию
      lazyLoading: true
    }
  }
}

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

VitePress использует markdown-it в качестве рендерера Markdown. Многие из вышеупомянутых расширений реализованы через пользовательские плагины. Вы можете дополнительно настроить экземпляр markdown-it, используя опцию markdown в .vitepress/config.js:

js
import { defineConfig } from 'vitepress'
import markdownItAnchor from 'markdown-it-anchor'
import markdownItFoo from 'markdown-it-foo'

export default defineConfig({
  markdown: {
    // опции для markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: markdownItAnchor.permalink.headerLink()
    },

    // опции для @mdit-vue/plugin-toc
    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
    toc: { level: [1, 2] },

    config: (md) => {
      // используйте больше плагинов markdown-it!
      md.use(markdownItFoo)
    }
  }
})

Смотрите полный список настраиваемых свойств в Справочнике по конфигурации: Конфигурация приложения.

Содержание доступно по лицензии MIT

2023-2024 IT wiki ru community, разработано на платформе VitePress 1.0.0-rc.42