Docs

Страницы документации в этом проекте пишутся в Markdown. Каждый файл .md VitePress превращает в отдельную страницу сайта.

Официальная документация VitePress по Markdown: vitepress.dev/guide/markdown
Базовый синтаксис Markdown: markdownguide.org/basic-syntax

Ниже собраны основные варианты Markdown и VitePress Markdown Extensions. Для каждого пункта сначала показан синтаксис, затем результат. При необходимости одну страницу можно собирать из нескольких Markdown-файлов через include-механику VitePress.

Редактирование страниц через PageCMS

PageCMS (app.pagescms.org) — это сайт, где вы правите текст, а сохранённые файлы уезжают в репозиторий на GitHub. Войти можно тем же аккаунтом GitHub, что и для проекта.

Сначала всегда по порядку

Откройте админку: на сайте с документацией путь /site.ams.docs/admin/ (полный вид: https://<адрес>/<путь-к-сайту>/site.ams.docs/admin/). На своём компьютере при разработке иногда будет http://localhost:5173/site.ams.docs/admin/ — номер порта может отличаться.
В списке проектов выберите site.ams.docs.
Выберите ветку для сохранений, обычно cms-edits. Не сохраняйте правки в main — это ветка уже согласованной «готовой» версии; туда они попадают через GitHub после проверки.
Слева в Content откройте нужный язык: Документация RU или Documentation EN (у EN поля Title / Content).
Только после этого создавайте папку или страницу (ниже). Когда закончите серию правок — нажмите Create PR to main (раздел в конце этой инструкции).

Простыми словами: ветка cms-edits — это черновик; main — то, что читают все, после того как изменения примут и вольют на GitHub.

Три поля в форме (что куда писать)

Поле	Что это для читателя и для ссылки
Filename	Как файл называется в проекте и часть адреса в браузере. Без пробелов; лучше латиницей, слова через дефис: `kak-ustanovit.md`.
Заголовок / Title (может называться иначе смотря какой язык)	Как страница подписана в списках и во вкладке.
Содержимое / Content (может называться иначе смотря какой язык)	Сам текст, который люди читают на странице. Можно набрать в Editor или переключитесь в Source, если нужен «сырой» Markdown.

Когда нужна папка с разделом, а когда одна страница без папки

Нужна папка — если хотите несколько связанных страниц «внутри одной темы» (как книга «глава → подразделы»).

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

text

Пример: одна страница (Add an entry — без новой папки)
docs/ru/
  ├── …другие страницы…
  └── kak-ustanovit.md     ← один файл на текущем уровне

Пример А: раздел С вводной страницей (есть index.md у папки)
docs/ru/
  └── ustanovka/
        ├── index.md         ← текст по основному адресу раздела
        ├── trebovaniya.md
        └── zapusk/
              ├── index.md
              └── parametri.md

Пример Б: раздел БЕЗ вводной (нет index.md только у этого уровня)
docs/ru/
  └── ustanovka/
        ├── trebovaniya.md   ← только «дочерние» страницы
        └── zapusk/
              └── parametri.md

Примерно так же слова в боковом меню сайта могут видеть читатели (подписи берутся из поля title во frontmatter и из заголовков; для группы — из index.md или из имени папки и правил генерации сайда в sidebar.ts / vitepress-sidebar):

text

Боковое меню (схема)
———————————————
 … другие пункты …

• Как установить              ← одиночная страница на уровне docs/ru
                              (название из title у kak-ustanovit.md)

▼ Установка                   ← группа = папка ustanovka/
   Вступление / обзор         ← есть только если в папке лежит index.md
                               (или клик только раскрывает список, без своей страницы)
   Требования                 ← trebovaniya.md
   ▼ Запуск                   ← вложенная папка zapusk/
      … вводная из index.md или только подпункты ↓
      Параметры               ← parametri.md

Символы ▼ / ► здесь просто означают развёрнутую и свёрнутую группу; точный вид (иконки, свёрнуто по умолчанию или нет) задаёт тема и collapseDepth в конфигурации сайда.

Папка: по шагам

Нажмите значок папки с плюсом → в меню Create a folder → введите имя раздела → Create.
Чтобы добавить файл внутрь этой группы: нажмите плюс справа у строки этой папки (не у самого верхнего узла всего списка, если хотите вложить именно сюда — смотрите на отступ в дереве).
В форме укажите имя файла, заголовок, текст → Save.

Нужна ли вводная страница раздела (index.md)

Да — если хотите текст по адресу самого раздела при открытии раздела (сводка, «начните отсюда»): файл — index.md, текст в содержимом.
Нет можно — если достаточно подводки как у выпадающего списка: в папке только trebovaniya.md, zapusk/… и т.д., без index.md. В меню раздел обычно сворачивается/разворачивается, а отдельной статьи «корня» нет; по URL …/ustanovka/ страницы может не быть.
Обычная страница внутри раздела — любое имя что‑угодно.md, не путать с index.md, если не хотите сделать её главной страницей папки.

Если дерево слева не показало новое сразу — обновите страницу (F5); так иногда делает редактор.

Одна страница без новой папки

Нажмите Add an entry, заполните те же три поля, Save. Файл появится на текущем уровне списка, без новой папки.

Когда уже всё сохранено: почему на общем сайте текст «ещё старый»

Пока вы только нажимаете Save в админке, изменения живут в ветке‑черновике (например cms-edits). В main они сами не переезжают.

Что сделать после набора правок

Слева нажмите Create PR to main. На GitHub создастся или обновится заявка: «предлагаю влить черновик в main» (это называют pull request, кратко PR).
Коллеги проверяют заявку. Если нужны правки — вы снова правите в админке (ветка cms-edits), затем снова Create PR to main.
Когда всё ок — на GitHub нажимают merge в main; после сборки сайта текст станет общим для всех читателей.

Больше про ветки и защиту main — в CONTRIBUTING.md в корне репозитория.

Frontmatter

Frontmatter находится в начале файла и управляет метаданными страницы: заголовком, описанием, sidebar title и другими параметрами. В теле страницы этот блок не отображается.

Markdown

yaml

---
title: Docs
description: Пример страницы документации
---

Результат

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

Кастомные компоненты Vue в Markdown

В VitePress можно использовать свои Vue-компоненты прямо внутри .md-страницы. Для этого компонент нужно импортировать в блоке <script setup>, а затем вставить его как обычный тег.

В этом проекте есть компонент DownloadFileButton. Он принимает такие пропсы:

label - текст на кнопке
href - ссылка на файл

Markdown

<script setup>
import DownloadFileButton from '../.vitepress/theme/components/ui/DownloadFileButton.vue'
</script>

<DownloadFileButton
  label="User manual.pdf"
  href="/files/user-manual.pdf"
/>

Результат

User manual.pdf

Кастомный компонент без пропсов

Если пропсы не передавать, компонент использует свои значения по умолчанию.

Markdown

<DownloadFileButton />

Результат

instruction file.pdf

Кастомный компонент с другим текстом

Так можно переиспользовать тот же компонент с другим label.

Markdown

<DownloadFileButton label="Инструкция по установке.pdf" />

Результат

Инструкция по установке.pdf

Заголовки и якоря

У заголовков автоматически создаются якоря. Можно задать и свой собственный id.

Markdown

## Раздел второго уровня
### Раздел третьего уровня
### Кастомный якорь {#custom-anchor-demo}

Результат

Раздел второго уровня

Раздел третьего уровня

Кастомный якорь

Ссылка на кастомный якорь: #custom-anchor-demo

Параграфы

Новый абзац начинается после пустой строки.

Markdown

Это первый абзац.

Это второй абзац.

Результат

Это первый абзац.

Это второй абзац.

Выделение текста и inline code

Markdown

**Жирный текст**
*Курсив*
***Жирный курсив***
~~Зачёркнутый текст~~
`inline code`

Результат

Жирный текстКурсивЖирный курсив~~Зачёркнутый текст~~inline code

Внешняя ссылка

Markdown

[Документация VitePress](https://vitepress.dev/guide/markdown)

Результат

Документация VitePress

Внутренняя ссылка

Внутренние ссылки ведут на другие страницы документации.

Markdown

[Главная](/en/)

Результат

Главная

Изображение

Markdown

![Логотип AMS](/images/logo.svg)

Результат

GIF

GIF вставляется так же, как обычное изображение.

Markdown

![Пример GIF](/images/demo.gif)

Результат

Пример GIF

Видео

Для видео в Markdown-странице используй HTML-тег <video>.
Обычно файл кладут в docs/public/videos, а в src указывают путь от корня сайта.

Markdown

html

<video controls width="720" preload="metadata">
  <source src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4" type="video/mp4" />
  Ваш браузер не поддерживает встроенное видео.
</video>

Результат

Видео с YouTube

Для роликов YouTube используй iframe с embed-ссылкой.

Markdown

html

<iframe
  width="720"
  height="405"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowfullscreen
></iframe>

Результат

Маркированный список

Markdown

- Первый пункт
- Второй пункт
- Третий пункт

Результат

Первый пункт
Второй пункт
Третий пункт

Нумерованный список

Markdown

1. Первый шаг
2. Второй шаг
3. Третий шаг

Результат

Первый шаг
Второй шаг
Третий шаг

Чеклист

Markdown

- [x] Готово
- [ ] Нужно сделать

Результат

[x] Готово
[ ] Нужно сделать

Цитата

Markdown

> Это пример цитаты.
>
> Вторая строка в той же цитате.

Результат

Это пример цитаты.
Вторая строка в той же цитате.

Разделитель

Markdown

---

Результат

Таблица

Markdown

| Колонка A | Колонка B | Выравнивание |
| --------- | :-------: | ------------: |
| текст     |  центр    |       вправо |
| число     |    42     |           99 |

Результат

Колонка A	Колонка B	Выравнивание
текст	центр	вправо
число	42	99

Emoji

Markdown

:tada: :rocket: :+1:

Результат

🎉 🚀 👍

Блок `info`

Markdown

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

Результат

INFO

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

Блок `tip`

Markdown

::: tip
Полезная подсказка.
:::

Результат

TIP

Полезная подсказка.

Блок `warning`

Markdown

::: warning
Важное предупреждение.
:::

Результат

WARNING

Важное предупреждение.

Блок `danger`

Markdown

::: danger
Критичное предупреждение.
:::

Результат

DANGER

Критичное предупреждение.

Блок `details`

Markdown

::: details Нажми, чтобы раскрыть
Скрытый текст.

```js
console.log('inside details')
```
:::

Результат

Нажми, чтобы раскрыть

Скрытый текст.

console.log('inside details')

Блок `details` открытый по умолчанию

Markdown

::: details Открытый блок {open}
```js
console.log('opened by default')
```
:::

Результат

Открытый блок

console.log('opened by default')

Блок с кастомным заголовком

Markdown

::: danger STOP
Не продолжайте без проверки.
:::

Результат

STOP

Не продолжайте без проверки.

GitHub Alert `NOTE`

Markdown

> [!NOTE]
> Этот блок полезен для заметок.

Результат

NOTE

Этот блок полезен для заметок.

GitHub Alert `TIP`

Markdown

> [!TIP]
> Этот блок полезен для подсказок.

Результат

TIP

Этот блок полезен для подсказок.

GitHub Alert `IMPORTANT`

Markdown

> [!IMPORTANT]
> Этот блок подчёркивает обязательную информацию.

Результат

IMPORTANT

Этот блок подчёркивает обязательную информацию.

GitHub Alert `WARNING`

Markdown

> [!WARNING]
> Этот блок предупреждает о рисках.

Результат

WARNING

Этот блок предупреждает о рисках.

GitHub Alert `CAUTION`

Markdown

> [!CAUTION]
> Этот блок описывает негативные последствия.

Результат

CAUTION

Этот блок описывает негативные последствия.

Кодовый блок с подсветкой

Markdown

```ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'AMS Docs'
})
```

Результат

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'AMS Docs'
})

Подсветка строк в коде

Markdown

```ts {2,4}
const ignored = 1
const highlighted = 2
const alsoIgnored = 3
const alsoHighlighted = 4
```

Результат

const ignored = 1
const highlighted = 2
const alsoIgnored = 3
const alsoHighlighted = 4

Подсветка строки через комментарий

Markdown

```js
export default {
  data() {
    return {
      msg: 'подсвечено'
    }
  }
}
```

Результат

export default {
  data() {
    return {
      msg: 'подсвечено'
    }
  }
}

Фокус на строке

Markdown

```js
export default {
  data() {
    return {
      msg: 'в фокусе'
    }
  }
}
```

Результат

export default {
  data() {
    return {
      msg: 'в фокусе'
    }
  }
}

Diff-строки в коде

Markdown

```js
export default {
  data() {
    return {
      old: 'удалено'
      neu: 'добавлено'
    }
  }
}
```

Результат

export default {
  data() {
    return {
      old: 'удалено'
      neu: 'добавлено'
    }
  }
}

Warning и error на строках кода

Markdown

```js
export default {
  data() {
    return {
      err: 'ошибка', 
      warn: 'предупреждение'
    }
  }
}
```

Результат

export default {
  data() {
    return {
      err: 'ошибка', 
      warn: 'предупреждение'
    }
  }
}

Группа вкладок `code-group`

Markdown

::: code-group

```js [config.js]
export default {
  title: 'JS'
}
```

```ts [config.ts]
export default {
  title: 'TS' as const
}
```

:::

Результат

config.jsconfig.ts

export default {
  title: 'JS'
}

export default {
  title: 'TS' as const
}

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

Markdown

<<< ../.vitepress/config.ts{6-11}

Результат

import { defineConfig } from 'vitepress'
import { navEn, navRu, withLocalizedSidebar } from './sidebar'

const base = '/'

const localSearchOptions = {
  locales: {
    root: {
      translations: {
        button: {
          buttonText: 'Search',
          buttonAriaLabel: 'Search documentation'
        },
        modal: {
          noResultsText: 'No results found',
          resetButtonTitle: 'Reset search',
          backButtonTitle: 'Back',
          displayDetails: 'Display detailed list',
          footer: {
            selectText: 'to select',
            selectKeyAriaLabel: 'enter',
            navigateText: 'to navigate',
            navigateUpKeyAriaLabel: 'up arrow',
            navigateDownKeyAriaLabel: 'down arrow',
            closeText: 'to close',
            closeKeyAriaLabel: 'escape'
          }
        }
      }
    },
    ru: {
      translations: {
        button: {
          buttonText: 'Поиск',
          buttonAriaLabel: 'Поиск по документации'
        },
        modal: {
          noResultsText: 'Ничего не найдено',
          resetButtonTitle: 'Сбросить',
          backButtonTitle: 'Назад',
          displayDetails: 'Показать подробности',
          footer: {
            selectText: 'перейти',
            selectKeyAriaLabel: 'Enter',
            navigateText: 'навигация',
            navigateUpKeyAriaLabel: 'Стрелка вверх',
            navigateDownKeyAriaLabel: 'Стрелка вниз',
            closeText: 'закрыть',
            closeKeyAriaLabel: 'Escape'
          }
        }
      }
    }
  }
}

export default defineConfig(
  withLocalizedSidebar({
    base,
    rewrites: (id) => (id.startsWith('en/') ? id.slice(3) : id),
    head: [
      ['link', { rel: 'icon', type: 'image/png', href: `${base}favicon-512.png` }],
      ['link', { rel: 'apple-touch-icon', href: `${base}favicon-512.png` }],
      ['link', { rel: 'mask-icon', href: `${base}images/logo.svg`, color: '#d9017a' }]
    ],
    themeConfig: {
      logo: {
        light: '/images/logo.svg',
        dark: '/images/logo-dark.svg',
        alt: 'AMS Docs'
      },
      search: {
        provider: 'local',
        options: localSearchOptions
      }
    },
    locales: {
      root: {
        label: 'English',
        lang: 'en-US',
        title: 'Documentation',
        description: 'Documentation',
        themeConfig: {
          nav: navEn,
          outline: { label: 'On this page', level: [1, 6] },
          docFooter: { prev: 'Previous', next: 'Next' },
          sidebarMenuLabel: 'Menu',
          returnToTopLabel: 'Return to top',
          darkModeSwitchLabel: 'Appearance',
          lightModeSwitchTitle: 'Switch to light theme',
          darkModeSwitchTitle: 'Switch to dark theme',
          langMenuLabel: 'Change language',
          skipToContentLabel: 'Skip to content'
        }
      },
      ru: {
        label: 'Русский',
        lang: 'ru-RU',
        link: '/ru/',
        title: 'Документация',
        description: 'Документация',
        themeConfig: {
          nav: navRu,
          outline: { label: 'На этой странице', level: [1, 6] },
          docFooter: { prev: 'Назад', next: 'Далее' },
          sidebarMenuLabel: 'Меню',
          returnToTopLabel: 'Наверх',
          darkModeSwitchLabel: 'Тема оформления',
          lightModeSwitchTitle: 'Светлая тема',
          darkModeSwitchTitle: 'Тёмная тема',
          langMenuLabel: 'Язык',
          skipToContentLabel: 'Перейти к содержимому'
        }
      }
    }
  })
)

Кодовый блок без языка

Markdown

```
многострочный текст
без подсветки синтаксиса
```

Результат

многострочный текст
без подсветки синтаксиса

Номера строк

Markdown

```ts:line-numbers=2
const second = 2
const third = 3
```

Результат

const second = 2
const third = 3

Сырой HTML через `raw`

Markdown

::: raw
<div style="padding: 12px 16px; border: 1px dashed #d9017a; border-radius: 12px;">
  HTML-блок внутри Markdown.
</div>
:::

Результат

HTML-блок внутри Markdown.

Math

Формулы в текущем проекте отключены. Ниже показан синтаксис, который можно включить через markdown: { math: true } и установку markdown-it-mathjax3.

Markdown

When $a \ne 0$, there are two solutions to $ax^2 + bx + c = 0$.

Результат

В этом проекте формулы пока не рендерятся, потому что math не включён в конфиге.

Docs ​

Редактирование страниц через PageCMS ​

Сначала всегда по порядку ​

Три поля в форме (что куда писать) ​

Когда нужна папка с разделом, а когда одна страница без папки ​

Папка: по шагам ​

Одна страница без новой папки ​

Когда уже всё сохранено: почему на общем сайте текст «ещё старый» ​

Frontmatter ​

Кастомные компоненты Vue в Markdown ​

Кастомный компонент без пропсов ​

Кастомный компонент с другим текстом ​

Оглавление ​

Заголовки и якоря ​

Раздел второго уровня ​

Раздел третьего уровня ​

Кастомный якорь ​

Параграфы ​

Выделение текста и inline code ​

Внешняя ссылка ​

Внутренняя ссылка ​

Изображение ​

GIF ​

Видео ​

Видео с YouTube ​

Маркированный список ​

Нумерованный список ​

Чеклист ​

Цитата ​

Разделитель ​

Таблица ​

Emoji ​

Блок info ​

Блок tip ​

Блок warning ​

Блок danger ​

Блок details ​

Блок details открытый по умолчанию ​

Блок с кастомным заголовком ​

GitHub Alert NOTE ​

GitHub Alert TIP ​

GitHub Alert IMPORTANT ​

GitHub Alert WARNING ​

GitHub Alert CAUTION ​

Кодовый блок с подсветкой ​

Подсветка строк в коде ​

Подсветка строки через комментарий ​

Фокус на строке ​

Diff-строки в коде ​

Warning и error на строках кода ​

Группа вкладок code-group ​

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

Кодовый блок без языка ​

Номера строк ​

Сырой HTML через raw ​

Math ​

Docs

Редактирование страниц через PageCMS

Сначала всегда по порядку

Три поля в форме (что куда писать)

Когда нужна папка с разделом, а когда одна страница без папки

Папка: по шагам

Одна страница без новой папки

Когда уже всё сохранено: почему на общем сайте текст «ещё старый»

Frontmatter

Кастомные компоненты Vue в Markdown

Кастомный компонент без пропсов

Кастомный компонент с другим текстом

Оглавление

Заголовки и якоря

Раздел второго уровня

Раздел третьего уровня

Кастомный якорь

Параграфы

Выделение текста и inline code

Внешняя ссылка

Внутренняя ссылка

Изображение

GIF

Видео

Видео с YouTube

Маркированный список

Нумерованный список

Чеклист

Цитата

Разделитель

Таблица

Emoji

Блок `info`

Блок `tip`

Блок `warning`

Блок `danger`

Блок `details`

Блок `details` открытый по умолчанию

Блок с кастомным заголовком

GitHub Alert `NOTE`

GitHub Alert `TIP`

GitHub Alert `IMPORTANT`

GitHub Alert `WARNING`

GitHub Alert `CAUTION`

Кодовый блок с подсветкой

Подсветка строк в коде

Подсветка строки через комментарий

Фокус на строке

Diff-строки в коде

Warning и error на строках кода

Группа вкладок `code-group`

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

Кодовый блок без языка

Номера строк

Сырой HTML через `raw`

Math