---
title: "Doc System"
description: "Ring-docs MDX component library — Callout, Steps, Mermaid, Tabs, Cards, Code, and visual authoring patterns for ring-platform.org documentation"
locale: "en"
---
# Doc System

**Ring-docs** is the MDX component layer behind every page at `/docs/*`. Authors write `.mdx` under `docs/{locale}/`; the app renders them with `next-mdx-remote/rsc` and the shared map in `components/docs/mdx-docs-shared.tsx`.

Technical writers, feature owners, and contributors who publish Ring Platform documentation with consistent visuals — without importing third-party doc UI kits.

## Render pipeline

```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
```

| Piece | Path | Role |
|-------|------|------|
| Content | `docs/{locale}/**/*.mdx` | Frontmatter + MDX body |
| Resolver | `lib/docs/docs-path.ts` | Slug → file; `buildDocsHref()` |
| Components | `components/docs/mdx-docs-shared.tsx` | Registers all JSX tags below |
| Highlighting | Shiki (`nord` / `tokyo-night`) | Server `` blocks |

New diagram types and sandbox presets are added incrementally. If a component is marked development in product docs, use this callout so readers know APIs may change before the next release.

---

## Callout

Highlighted prose for executives, warnings, tips, and product status. **Seven types** — unknown types fall back to `info`.

| `type` | Use when |
|--------|----------|
| `info` | Context, paths, policy |
| `tip` | Best practice, positioning |
| `success` | Validation passed, outcome summary |
| `warning` | Security, irreversible ops |
| `error` | Broken config, hard failure |
| `development` | Feature in flux, preview APIs |
| `financing` | Grants, RING treasury, vendor funding |

### Live gallery

Canonical EN paths live under `docs/en/`. UK/RU summaries follow `scripts/LOCALE-GAPS.md` unless a page is fully translated.

Hub pages work best with **one** architecture diagram and **Cards** linking every child in `meta.json`.

Your doc page renders when `npm run dev` serves `/docs/features/doc-system` without MDX parse errors.

Never commit production secrets (`WAYFORPAY_SECRET_KEY`, `AUTH_SECRET`) into MDX or code blocks.

Missing Callout `type` values crash render — stick to the seven types above or omit `type` (defaults to `info`).

Scientific editor collaboration CRDT and multi-replica tunnel hubs are evolving — check feature flags and implementation logs before shipping dependent docs.

Ring-powered marketplaces can surface **vendor growth** and **cooperative funding** programs — link opportunities and wallet docs when describing token or grant mechanics for sellers.

```mdx

  Describe grants, revenue share, or treasury programs here.

```

---

## Steps and Step

Numbered walkthroughs for install, onboarding, and checklists.

Leave **blank lines** before `
`, before each `
`, after each `

`, and after `
` — otherwise MDX parsing fails.

Add the page slug to `docs/en/{section}/meta.json` → `pages[]`.

Author content with components from this page.

Verify at `http://localhost:3000/docs/features/your-page`.

---

## Tabs and Tab

Split audiences on the same URL — developers vs operators, or Do vs Avoid.

- Use `value` on each `` (not `title`)
- Optional `items={['A','B']}` on `` for trigger order

- Scan Callout summaries first
- Follow Cards to deep dives
- Use Steps for procedural pages

---

## Cards and Card

Hub navigation — every child page in a section `meta.json` should have a card on that section's `index.mdx`.

  
- **[Vendor Guide](/docs/vendor-guide.md)** — Seller-first marketplace onboarding on ring-platform.org.

  
- **[Multi-Vendor Store](/docs/features/store.md)** — Payments, trust tiers, and catalog architecture.

  
- **[Development components](/docs/development/docs-components.md)** — Authoring rules, hub checklist, and contributor workflow.

---

## Mermaid

Client-rendered diagrams. Pass diagram source as a **template literal child**:

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

Fenced blocks also work — rehype converts ` ```mermaid ` to `` automatically.

---

## MindMap

Mermaid `mindmap` syntax via the `MindMap` alias — use **once per hub**, not on every page.

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

---

## Code

Server-rendered Shiki highlighting. Use `language` and optional `title`:

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

Inline code uses single backticks: `docsMdxComponents`, `resolveDocFilePath()`.

---

## Timeline

Client-only (`react-chrono`). Ideal for roadmaps and migration history.

---

## UiCard (shadcn)

Layout cards inside MDX — distinct from doc navigation `Card`. Use for grouped settings or API panels:

  
    Example panel
    UiCard* components mirror shadcn Card for dense reference blocks.
  
  
    Prefer Callout for alerts and Card for navigation links.
  

---

## Math and MathBlock

KaTeX for tokenomics and scientific editor docs.

Inline: commission rate {`r = 0.20 - 0.02 \times tier`} (example).

Display:

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

---

## Heavy / specialized components

| Component | When to use | Embed on dense reference pages? |
|-----------|-------------|----------------------------------|
| **CodeSandbox** | `/examples` — live Sandpack previews | Sparingly |
| **RingAISynapseFlow** | AI matching marketing visuals | No — large bundle |
| **Image** (via `img`) | Screenshots with border radius | Yes |

Documentation that explains **marketplace revenue**, **affiliate programs**, or **treasury participation** should cross-link [Wallet](/docs/features/wallet.md) and [Affiliate enablement](/docs/features/affiliate-enablement.md) using the financing callout where funding mechanics matter.

---

## GFM markdown (automatic)

These elements need no JSX — `remark-gfm` styles them via the MDX map:

| Element | Styled behavior |
|---------|-----------------|
| Headings `##` | Scroll margin, border on `h2` |
| Tables | Bordered rows, hover |
| Lists | Disc / decimal with spacing |
| Blockquote | Primary left border |
| Links | Primary color underline |

---

## Component quick reference

| Component | Import map key | Client? |
|-----------|----------------|---------|
| Callout | `Callout` | Yes |
| Steps / Step | `Steps`, `Step` | Yes |
| Tabs / Tab | `Tabs`, `Tab` | Yes |
| Cards / Card | `Cards`, `Card` | Server-friendly |
| Mermaid | `Mermaid` | Yes |
| MindMap | `MindMap` | Yes |
| Code | `Code` | Server async |
| Timeline | `Timeline` | Yes |
| Math / MathBlock | `Math`, `MathBlock` | Yes |
| UiCard* | `UiCard`, … | Server-friendly |
| CodeSandbox | `CodeSandbox` | Yes |
| RingAISynapseFlow | `RingAISynapseFlow` | Yes |

---

## Related

  
- **[Docs components (Development)](/docs/development/docs-components.md)** — Hub checklist, authoring rules, and contributor workflow.

  
- **[Contributing](/docs/development/contributing.md)** — PR guidelines and review expectations for docs changes.

  
- **[Architecture hub](/docs/architecture.md)** — Reference layout using these same primitives.