---
title: "Documentation components"
description: "Ring MDX component library — Callout, Mermaid, Tabs, Cards, Steps, Code, and authoring rules for hub pages and tutorials"
locale: "en"
---
# Documentation components

Ring docs are **MDX files** rendered by `next-mdx-remote/rsc` with a shared component map in `components/docs/mdx-docs-shared.tsx`. Use these building blocks to write pages that work for **developers** (precise paths, code) and **executives** (outcomes, one diagram, clear navigation).

> **Info**
> **Canonical paths:** Content lives at `docs/{locale}/{section}/{page}.mdx` or `docs/{locale}/{section}/index.mdx` for hubs. Public URLs: `/docs/...` (locale prefix per `next-intl` `as-needed`). Resolver tries `{slug}.mdx` then `{slug}/index.mdx` at any depth. Malformed `.mdx` URLs and trailing `/index` segments normalize via `next.config.mjs`.

## Render pipeline

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

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

| Stage | Location | Role |
|-------|----------|------|
| Content | `docs/{locale}/` | `title`, `description`, MDX body |
| Resolver | `lib/docs/docs-path.ts` | Slug → `docs/{locale}/**`; hub (`foo/index.mdx`) and leaf (`foo.mdx`); `buildDocsHref()`, `scanDocsStaticParams()` |
| Components | `components/docs/mdx-docs-shared.tsx` | Registers all JSX tags below |
| Syntax | Shiki (`nord` / `tokyo-night`) | Server-side highlighting in `` |

## Component quick reference

| Component | Best for | Client / server |
|-----------|----------|-----------------|
| **Callout** | Executive summary, warnings (`DB_BACKEND_MODE`, legal) | Client |
| **Mermaid** | One system map + one sequence diagram per hub (avoid sprawl) | Client |
| **Tabs / Tab** | Developer vs Operator (or CEO) views on the same page | Client |
| **Cards / Card** | Hub navigation to all child articles | Server-friendly |
| **Steps / Step** | Install and deploy walkthroughs | Server-friendly |
| **Code** | Shiki-highlighted config snippets | Server (async) |
| **MindMap** | Concept trees — use sparingly on hubs | Client |
| **Timeline** | Release / migration history | Client |
| **RingMatcherOrchestration** | Docs hub default — lightweight AI matcher loop (SVG, locale-aware) | Client |
| **RingAISynapseFlow** | Legacy heavy demo (Three.js) — preserved, avoid on reference pages | Client |
| **RingIntegrationPlanesHub** | Integration planes orb (identity / payments / comms / mail / external) | Client |
| **RingApiTree** | Vertical 9:14 API family tree — selectable `/api` leaves + methods panel (`/docs/api`) | Client |
| **CodeSandbox** | Runnable examples in `/examples` | Client |
| **Math / MathBlock** | Scientific editor, tokenomics equations | Client |

Fenced markdown code (\`\`\`typescript) and fenced mermaid (\`\`\`mermaid) are rewritten at build time to `` and `

```mermaid
` via rehype plugins.

## Callout

Types: `info` | `tip` | `success` | `warning` | `error` | `development` | `financing`. Optional `title`. Unknown types fall back to `info`. **Live gallery:** [Doc System](/docs/features/doc-system.md).

  APIs and UI described in preview docs may change before release — pair with a GitHub issue or implementation log link when possible.

  Use for grants, treasury programs, vendor funding, or affiliate revenue mechanics — link Wallet and opportunities docs.

  Lead hub pages with a one-paragraph outcome for operators and CEOs, then tables and a single system diagram.

```mdx

  Never commit `WAYFORPAY_SECRET_KEY` to the repository.

```

## Mermaid

Prefer **one** architecture map and **one** sequence diagram on hub pages. Additional diagrams belong on child articles.

{`sequenceDiagram
  participant A as Author
  participant B as MDX
  participant C as Browser
  A->>B: Write Mermaid in template literal
  B->>C: Client hydrate + render SVG`}
```

```mdx

```mermaid
sequenceDiagram
  User->>Ring: Checkout
  Ring->>WayForPay: Create session
```

```

Or a fenced block (converted automatically):

```mermaid
flowchart LR
  A[Draft] --> B[Review] --> C[Publish]
```

## Tabs and Tab

Split audiences without duplicating entire pages. Pass `items` or rely on child `` labels.

- Point to file paths (`lib/database/DatabaseService.ts`)
- Show Server Action and API contracts
- Link to canonical EN deep dives

- Env var checklists and `DB_BACKEND_MODE`
- Deploy order, secrets, monitoring signals
- No implementation detail unless troubleshooting

```mdx

Content for engineers.

Content for deployers and CEOs.

```

## Cards and Card

Required pattern for **section hub** pages (`index.mdx`). Each card links to a child page from that section's `meta.json`.

  
- **[Architecture hub](/docs/architecture.md)** — System map, Tabs, and links to all architecture children

  
- **[Backend modes](/docs/architecture/backend-modes-and-databases.md)** — Canonical `DB_BACKEND_MODE` reference

```mdx

  
- **[Page title](/docs/section/page.md)** — Short description for the card body.

```

Use href `/docs/...` without the `library` segment. Locale prefix is applied by the app router.

## Steps and Step

  **Blank lines are required** before `
`, before each `
`, after each `

`, and after `
`. Omitting them causes MDX parse errors.

Install dependencies:

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

Add the page to `docs/en/{section}/meta.json` `pages[]` and mirror UK/RU `meta.json` when translating.

Verify at `http://localhost:3000/docs/{section}/{page}`.

## Code

Server-rendered Shiki blocks. Prefer the `code` prop or template literal children:

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

```mdx

{`npm run dev`}

```

Inline code uses the markdown backtick form: `DatabaseService`, `auth()`.

## MindMap

Alias for Mermaid `mindmap` syntax. Use for concept hierarchies — **not** five mindmaps on one hub page.

{`mindmap
  root((Hub page))
    Callout summary
    One Mermaid map
    Tabs audiences
    Cards children`}

## Timeline

Client-only (`react-chrono`). Use for migration timelines and release notes.

```mdx
{/* Timeline expects items prop — use in dedicated client wrapper or examples */}
```

Document release history in prose + table if `Timeline` props are awkward in pure MDX; prefer Timeline on marketing or roadmap pages.

## RingMatcherOrchestration

Symbolic AI-matcher hub for docs welcome pages: users orbit the matcher with **offer-type badges** (same taxonomy as the legacy synapse viz), a request icon flies in, the matcher routes to a provider via a **joint line**, the line **straightens**, then **DM bubbles** exchange. Props: `locale` (`en` | `uk` | `ru`), `autoPlay`, optional `title` / `subtitle`. Respects `prefers-reduced-motion`.

```mdx

```

## RingAISynapseFlow (legacy)

Heavy animated AI-matching visualization (Three.js logo, quantum lasers). **Preserved** in `components/docs/ring-ai-synapse-flow.tsx` but removed from docs index pages in favor of `RingMatcherOrchestration`. Do not embed on dense reference pages.

## CodeSandbox and Math

| Component | When |
|-----------|------|
| **CodeSandbox** | `/examples` — Sandpack `react-ts` (or custom `files`) with live preview |
| **Math** | Inline KaTeX: `{`E = mc^2`}` |
| **MathBlock** | Display equations in scientific / tokenomics docs |

## Hub page checklist

Use this when rewriting section indexes (e.g. [Architecture](/docs/architecture.md)):

**Executive Callout** — who the page is for and the deployment default (Postgres-primary, PaymentConductor, etc.).

**Capability table** — stack row per concern (data, auth, payments, realtime).

**One system Mermaid** — logical layers, not emoji sprawl.

**Tabs** — Developers vs Operators (or CEO vs engineering).

**Cards** — every entry in section `meta.json` `pages[]` except `index`.

**Cross-links** — customization, deployment env, LOCALE-GAPS policy for UK/RU.

## Authoring rules

| Rule | Why |
|------|-----|
| EN canonical unless LOCALE-GAPS marks UK/RU summary | Avoid drift on env tables and API bodies |
| Frontmatter `title` + `description` required | SEO and docs sidebar |
| No `fumadocs-ui` imports | Migrated to Ring `components/docs/` |
| Test `npm run dev` after new MDX | Catch Steps blank-line and Mermaid typos early |
| Grep stale strings after stack bumps | e.g. `Next.js 16` in UK/RU backlog |

## Related

- [Contributing](/docs/development/contributing.md) — PR and content guidelines
- [Code structure](/docs/development/code-structure.md) — app layout vs `features/`
- [Architecture hub](/docs/architecture.md) — reference hub using these components
- Truth lens: `AI-LEGIOX/legiox-truth-lens/ring-docs-specialist.nodus.json`

> **Info**
> After adding or restructuring docs, update `scripts/LOCALE-GAPS.md` and run `legiox-context-update` when AI-CONTEXT should reflect new patterns.