---
title: "Компоненты документации"
description: "Библиотека MDX Ring — Callout, Mermaid, Tabs, Cards, Steps, Code и правила оформления хабов и туториалов"
locale: "ru"
---
# Компоненты документации

Документация Ring — **MDX-файлы**, рендеримые `next-mdx-remote/rsc` с общей картой компонентов в `components/docs/mdx-docs-shared.tsx`. Используйте эти блоки для страниц, понятных **разработчикам** (пути, код) и **руководителям** (результат, одна диаграмма, ясная навигация).

> **Info**
> **Канонические пути:** контент в `docs/{locale}/{section}/{page}.mdx`. Публичные URL: `/docs/...` (префикс локали по `next-intl` `as-needed`).

## Конвейер рендеринга

```mermaid
flowchart LR
  MDX["MDX + frontmatter"]
  RSC["next-mdx-remote/rsc"]
  GFM["remark-gfm"]
  Rehype["rehype: Code + Mermaid"]
  Map["docsMdxComponents"]
  Page["/{locale}/docs/..."]

  MDX --> RSC
  GFM --> RSC
  Rehype --> RSC
  RSC --> Map --> Page
```

| Этап | Расположение | Роль |
|------|--------------|------|
| Контент | `docs/{locale}/` | `title`, `description`, тело MDX |
| Resolver | `lib/docs/docs-path.ts` | Slug → `docs/{locale}/**`; hub (`foo/index.mdx`) и leaf (`foo.mdx`); `buildDocsHref()`, `scanDocsStaticParams()` |
| Компоненты | `components/docs/mdx-docs-shared.tsx` | Регистрация JSX-тегов |
| Подсветка | Shiki (`nord` / `tokyo-night`) | Серверный `` |

## Быстрый справочник компонентов

| Компонент | Лучше всего для | Client / server |
|-----------|-----------------|-----------------|
| **Callout** | Резюме для руководителей, предупреждения (`DB_BACKEND_MODE`, legal) | Client |
| **Mermaid** | Одна системная карта + одна sequence на хаб (без разрастания) | Client |
| **Tabs / Tab** | Разработчик vs Оператор (или CEO) на одной странице | Client |
| **Cards / Card** | Навигация хаба к дочерним статьям | Server-friendly |
| **Steps / Step** | Установка и деплой по шагам | Server-friendly |
| **Code** | Конфиг с Shiki | Server (async) |
| **MindMap** | Деревья понятий — осторожно на хабах | Client |
| **Timeline** | История релизов / миграций | Client |
| **RingAISynapseFlow** | Маркетинг / AI-демо — тяжёлый бандл | Client |
| **CodeSandbox** | Живые примеры в `/examples` | Client |
| **Math / MathBlock** | Научный редактор, токеномика | Client |

Огороженные блоки \`\`\`typescript и \`\`\`mermaid преобразуются в `` и `

```mermaid
` через rehype.

## Callout

Типы: `info` | `warning` | `error` | `success`. Опционально `title`.

  Начинайте хабы с одного абзаца результата для операторов и CEO, затем таблица и одна системная диаграмма.

## Mermaid

На хабах — **одна** архитектурная карта и **одна** sequence. Остальное — на дочерних страницах.

{`sequenceDiagram
  participant A as Автор
  participant B as MDX
  participant C as Браузер
  A->>B: Mermaid в template literal
  B->>C: Client hydrate + SVG`}
```

## Tabs и Tab

- Пути к файлам (`lib/database/DatabaseService.ts`)
- Контракты Server Actions и API
- Ссылки на каноничные EN deep dives

- Чеклисты env и `DB_BACKEND_MODE`
- Порядок деплоя, секреты, мониторинг
- Минимум деталей реализации

## Cards и Card

Обязательный паттерн для **хабов секций** (`index.mdx`). Каждая карточка — дочерняя страница из `meta.json`.

  
- **[Хаб архитектуры](/docs/architecture.md)** — Системная карта, Tabs, ссылки на все дочерние статьи

  
- **[Режимы бэкенда](/docs/architecture/backend-modes-and-databases.md)** — Канонический справочник `DB_BACKEND_MODE`

Href: `/docs/...` без сегмента `library`.

## Steps и Step

  **Нужны пустые строки** перед `
`, перед каждым `
`, после `

` и после `
`.

Установите зависимости:

{`cd ring-platform.org
npm install`}

Добавьте страницу в `meta.json` секции и синхронизируйте UK/RU по `LOCALE-GAPS.md`.

Проверьте `http://localhost:3000/docs/{section}/{page}`.

## Code

{`DB_BACKEND_MODE=k8s-postgres-fcm
POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY`}

Инлайн-код: `DatabaseService`, `auth()`.

## MindMap

{`mindmap
  root((Хаб))
    Callout резюме
    Одна Mermaid карта
    Tabs аудитории
    Cards дети`}

## Timeline, RingAISynapseFlow, CodeSandbox, Math

| Компонент | Когда |
|-----------|-------|
| **Timeline** | Миграции, roadmap (`react-chrono`, client-only) |
| **RingAISynapseFlow** | Только маркетинг — не на справочных страницах |
| **CodeSandbox** | Раздел `/examples`, Sandpack |
| **Math / MathBlock** | Формулы в научных / tokenomics статьях |

## Чеклист хаб-страницы

**Callout** для руководителей — кому страница и дефолт деплоя.

**Таблица возможностей** — данные, auth, платежи, realtime.

**Одна системная Mermaid** — логические слои.

**Tabs** — Разработчики vs Операторы.

**Cards** — все `pages[]` из `meta.json`, кроме `index`.

## Правила авторинга

| Правило | Почему |
|---------|--------|
| EN каноничен, UK/RU по LOCALE-GAPS | Без расхождений в env/API |
| Frontmatter `title` + `description` | SEO и сайдбар |
| Без `fumadocs-ui` | Только `components/docs/` |
| `npm run dev` после нового MDX | Ловить ошибки Steps/Mermaid |

## Связанное

- [Contributing](/docs/development/contributing.md)
- [Структура кода](/docs/development/code-structure.md)
- [Хаб архитектуры](/docs/architecture.md)
- Truth lens: `ring-docs-specialist.nodus.json`

> **Info**
> После изменений обновляйте `scripts/LOCALE-GAPS.md`.