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

Документація 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`.