Как добавлять документацию

Сайт собирается из обычных Markdown-файлов в каталоге docs/. Каждый .md-файл — отдельная страница.

Структура каталогов

docs/
├── .vitepress/config.ts   # конфигурация: навбар, сайдбар, локали
├── public/                # статика: картинки (images/), видео (videos/), логотипы
├── index.md               # «Вводная» — главная страница сайта
├── guide/                 # страницы руководства
│   ├── network-account.md
│   ├── triggers.md
│   └── ...
└── en/                    # английская локаль (зеркалит структуру корня)
    ├── index.md
    └── guide/...

• Русская версия — в корне docs/, английская — в docs/en/ с той же структурой путей.
• URL страницы повторяет путь файла: docs/guide/triggers.md → /docs/guide/triggers (расширение .html не нужно, включён cleanUrls; сайт живёт в подпапке /docs, префикс задан через base).
• docs/index.md («Вводная») — главная страница сайта, открывается прямо на cpapony.ru/docs.

Добавление новой страницы

1. Создайте файл, например docs/guide/triggers.md:

# Триггеры

Описание работы триггеров...

## Условия

Текст раздела — заголовки `##` автоматически попадут в оглавление справа.

2. Добавьте страницу в сайдбар — откройте docs/.vitepress/config.ts, найдите locales.root.themeConfig.sidebar и допишите пункт:

sidebar: {
  '/': [
    {
      text: 'Автоматизация',
      items: [
        { text: 'Сценарии', link: '/guide/workflows' },
        { text: 'Триггеры', link: '/guide/triggers' },   // новая страница
      ],
    },
  ],
},

3. Для английской версии создайте зеркальный файл docs/en/guide/triggers.md и добавьте его в locales.en.themeConfig.sidebar (link: '/en/guide/triggers').

Новый раздел (не «Руководство»)

1. Создайте каталог, например docs/api/ с index.md внутри.
2. В config.ts добавьте ссылку в nav и отдельный ключ в sidebar:

nav: [
  { text: 'Руководство', link: '/' },
  { text: 'API', link: '/api/' },
],
sidebar: {
  '/': [ /* ... */ ],
  '/api/': [
    { text: 'API', items: [{ text: 'Обзор', link: '/api/' }] },
  ],
},

Картинки и файлы

• Кладите их в docs/public/ и ссылайтесь от корня: ![Схема](/images/trigger-flow.png) (файл при этом лежит в docs/public/images/trigger-flow.png).
• Либо кладите рядом с .md и ссылайтесь относительно: ![Схема](./trigger-flow.png).

Полезные возможности Markdown в VitePress

Подсветка синтаксиса с указанием языка и выделением строк:

```python{2}
def evaluate(trigger):
    return trigger.check_conditions()  # эта строка будет подсвечена
```

Контейнеры-подсказки:

::: tip Совет
Полезная информация.
:::

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

::: danger Осторожно
Критичная информация.
:::

Группы табов для примеров кода:

::: code-group
```bash [curl]
curl https://api.cpapony.com/api/v1/campaigns
```
```python [Python]
requests.get("https://api.cpapony.com/api/v1/campaigns")
```
:::

Полный справочник — vitepress.dev/guide/markdown.

Проверка и публикация

# локальная разработка с горячей перезагрузкой — http://localhost:5173
npm run docs:dev

# продакшен-сборка (упадёт с ошибкой при битых ссылках) и её просмотр
npm run docs:build
npm run docs:preview

Публикация на cpapony.ru/docs / cpapony.com/docs:

cd deploy
./docker-build.sh --patch     # соберёт мультиарх-образ, запушит в registry, поднимет VERSION

Затем на сервере: ./update-services.sh (или точечно docker compose -f doc-compose.yml pull && docker compose -f doc-compose.yml up -d).

Подробнее о деплое — в README.md репозитория.