---
title: "Система документації"
description: "Бібліотека MDX-компонентів Ring-docs — Callout, Steps, Mermaid, Tabs, Cards, Code і візуальні патерни створення документації для ring-platform.org"
locale: "uk"
---
# Система документації

**Ring-docs** — це шар MDX-компонентів, на якому працює кожна сторінка за адресою `/docs/*`. Автори пишуть `.mdx` у `docs/{locale}/`; застосунок відображає їх за допомогою `next-mdx-remote/rsc` і спільної мапи в `components/docs/mdx-docs-shared.tsx`.

Технічні автори, власники функцій і контриб’ютори, які публікують документацію Ring Platform зі сталим візуальним стилем — без імпорту сторонніх наборів UI для документації.

## Пайплайн рендерингу

```mermaid
flowchart LR
  File["docs/en/.../*.mdx"]
  Resolver["lib/docs/docs-path.ts"]
  RSC["MDXRemote + remark-gfm"]
  Rehype["Code + Mermaid fences"]
  Map["docsMdxComponents"]
  URL["/docs/..."]

  File --> Resolver --> RSC
  Rehype --> RSC --> Map --> URL
```

| Частина | Шлях | Роль |
|-------|------|------|
| Вміст | `docs/{locale}/**/*.mdx` | Frontmatter + тіло MDX |
| Resolver | `lib/docs/docs-path.ts` | Slug → файл; `buildDocsHref()` |
| Компоненти | `components/docs/mdx-docs-shared.tsx` | Реєструє всі JSX-теги нижче |
| Підсвічування | Shiki (`nord` / `tokyo-night`) | Серверні блоки `` |

Нові типи діаграм і пресети sandbox додаються поступово. Якщо в документації продукту компонент позначено як development, використовуйте цей callout, щоб читачі знали: API може змінитися до наступного релізу.

---

## Callout

Виділений текст для керівників, попереджень, підказок і статусу продукту. **Сім типів** — невідомі типи повертаються до `info`.

| `type` | Використовуйте, коли |
|--------|----------|
| `info` | Контекст, шляхи, політика |
| `tip` | Найкраща практика, позиціонування |
| `success` | Перевірку пройдено, підсумок результату |
| `warning` | Безпека, незворотні операції |
| `error` | Зламана конфігурація, критична помилка |
| `development` | Функція змінюється, API у попередньому перегляді |
| `financing` | Гранти, скарбниця RING, фінансування від постачальників |

### Жива галерея

Канонічні шляхи EN розташовані в `docs/en/`. Підсумки UK/RU відповідають `scripts/LOCALE-GAPS.md`, якщо сторінку не перекладено повністю.

Для hub-сторінок найкраще працюють **одна** архітектурна діаграма та **Cards** із посиланнями на кожну дочірню сторінку в `meta.json`.

---

## Steps і Step

Нумеровані покрокові інструкції для встановлення, онбордингу та чеклістів.

Залишайте порожні рядки перед `
`, перед кожним `
`, після `

` і після `
` — інакше розбір MDX завершиться помилкою.

Додайте slug сторінки до `docs/en/{section}/meta.json` → `pages[]`.

Створіть вміст за допомогою компонентів із цієї сторінки.

Перевірте за адресою `http://localhost:3000/docs/features/your-page`.

---

## Tabs і Tab

Розділяйте аудиторії за тією самою URL-адресою — розробники проти операторів або «Робіть» проти «Уникайте».

- Використовуйте `value` у кожному `` (не `title`)
- Необов’язковий `items={['A','B']}` у `` визначає порядок тригерів

- Спочатку перегляньте підсумки Callout
- Переходьте за Cards до детальних матеріалів
- Використовуйте Steps для процедурних сторінок

---

## Cards і Card

Навігація hub-сторінки — кожна дочірня сторінка в `meta.json` розділу повинна мати картку на `index.mdx` цього розділу.

  
- **[Посібник постачальника](/docs/vendor-guide.md)** — Онбординг продавців на ring-platform.org із фокусом на маркетплейс.

  
- **[Мультипостачальницький магазин](/docs/features/store.md)** — Платежі, рівні довіри та архітектура каталогу.

  
- **[Компоненти розробки](/docs/development/docs-components.md)** — Правила створення, чекліст hub-сторінки та робочий процес контриб’ютора.

---

## Mermaid

Діаграми, що відображаються на клієнті. Передавайте джерело діаграми як дочірній елемент template literal:

```mermaid
flowchart TB
  Callout --> Hub[Hub index.mdx]
  Mermaid --> Hub
  Cards --> Hub
  Tabs --> Article[Feature article]
  Steps --> Article
  Code --> Article
```

Блоки з огорожею також працюють — rehype автоматично перетворює Mermaid fence на ``.

---

## MindMap

Синтаксис Mermaid `mindmap` через псевдонім `MindMap` — використовуйте один раз на hub-сторінку, а не на кожній сторінці.

{`mindmap
  root((Ring-docs))
    Prose
      GFM tables
      Styled headings
    Interactive
      Callout
      Tabs
      Steps
    Visual
      Mermaid
      MindMap
      Timeline
    Code
      Code block
      Inline backticks`}

---

## Code

Підсвічування Shiki, що виконується на сервері. Використовуйте `language` і необов’язковий `title`:

{`// docs/en/features/meta.json
{
  "pages": ["index", "doc-system", "store"]
}`}

Для вбудованого коду використовуйте одиночні backticks: `docsMdxComponents`, `resolveDocFilePath()`.

---

## Timeline

Лише клієнт (`react-chrono`). Ідеально для дорожніх карт та історії міграцій.

---

## UiCard (shadcn)

Картки макета всередині MDX — відмінні від навігаційного `Card` документації. Використовуйте їх для згрупованих налаштувань або панелей API:

  
    Приклад панелі
    Компоненти UiCard* відтворюють shadcn Card для щільних довідкових блоків.
  
  
    Для сповіщень надавайте перевагу Callout, а для навігаційних посилань — Card.
  

---

## Math і MathBlock

KaTeX для документації з токеноміки та наукового редактора.

Вбудована формула: ставка комісії {`r = 0.20 - 0.02 \times tier`} (приклад).

Відображення:

{`\text{payout} = \text{gross} \times (1 - r)`}

---

## Важкі / спеціалізовані компоненти

| Компонент | Коли використовувати | Додавати на щільні довідкові сторінки? |
|-----------|-------------|----------------------------------|
| **CodeSandbox** | `/examples` — живі прев’ю Sandpack | Рідко |
| **RingAISynapseFlow** | Маркетингові візуали зіставлення ШІ | Ні — великий бандл |
| **Image** (через `img`) | Скріншоти із заокругленням кутів | Так |

Документація про дохід маркетплейсу, партнерські програми або участь у скарбниці повинна містити посилання на [Wallet](/docs/features/wallet.md) і [Affiliate enablement](/docs/features/affiliate-enablement.md), використовуючи financing callout там, де важливі механізми фінансування.

---

## GFM markdown (автоматично)

Цим елементам не потрібен JSX — `remark-gfm` стилізує їх через мапу MDX:

| Елемент | Стилізація |
|---------|-----------------|
| Заголовки `##` | Відступ для прокручування, рамка для `h2` |
| Таблиці | Рядки з рамками, ефект наведення |
| Списки | Маркери / десяткові числа з інтервалами |
| Blockquote | Основна ліва рамка |
| Посилання | Підкреслення основним кольором |

---

## Швидкий довідник компонентів

| Компонент | Ключ мапи імпорту | Клієнтський? |
|-----------|----------------|---------|
| Callout | `Callout` | Так |
| Steps / Step | `Steps`, `Step` | Так |
| Tabs / Tab | `Tabs`, `Tab` | Так |
| Cards / Card | `Cards`, `Card` | Зручний для сервера |
| Mermaid | `Mermaid` | Так |
| MindMap | `MindMap` | Так |
| Code | `Code` | Серверний async |
| Timeline | `Timeline` | Так |
| Math / MathBlock | `Math`, `MathBlock` | Так |
| UiCard* | `UiCard`, … | Зручний для сервера |
| CodeSandbox | `CodeSandbox` | Так |
| RingAISynapseFlow | `RingAISynapseFlow` | Так |

---

## Пов’язані матеріали

  
- **[Компоненти документації (розробка)](/docs/development/docs-components.md)** — Чекліст hub-сторінки, правила створення та робочий процес контриб’ютора.

  
- **[Внесок у проєкт](/docs/development/contributing.md)** — Правила PR і очікування щодо рев’ю змін документації.

  
- **[Архітектурний hub](/docs/architecture.md)** — Еталонна структура з використанням цих самих примітивів.