Como escrever docs

Toda página é um .mdx em apps/docs/content/docs/<raiz>/. Os componentes desta página funcionam em qualquer .mdx sem import: estão no mapa de src/components/mdx.tsx. Os plugins de remark e rehype ficam em source.config.ts.

FrontmatterCopy Anchor Link

Além de title e description, toda página aceita três campos opcionais. O build valida o frontmatter (src/lib/frontmatter.ts): um status com erro de digitação para o build e aponta o arquivo.

---
title: Minha página
description: Uma frase que diz o que a página resolve.
owner: João
status: review
tags: [sse, pareamento]
---

owner, status e tags aparecem numa linha embaixo da descrição, como no topo desta página.

Onde fica cada coisaCopy Anchor Link

Um bloco de código com a linguagem files vira uma árvore (plugin remarkMdxFiles). Pastas terminam em /:

A mesma árvore em JSX, quando precisa abrir uma pasta ou trocar um ícone:

<Files>
  <Folder name="content" defaultOpen>
    <Folder name="docs" defaultOpen>
      <File name="meta.json" />
      <File name="index.mdx" />
    </Folder>
  </Folder>
  <File name="source.config.ts" />
</Files>

Uma página nova entra no menu pelo meta.json da pasta (pages). Sem isso, ela vai pro fim da lista.

DiagramasCopy Anchor Link

Escreva um bloco mermaid. O plugin remarkMdxMermaid o transforma em <Mermaid chart="…" />, que desenha no navegador com as cores dos tokens e acompanha o tema claro e escuro. No servidor e sem JavaScript, aparece o código do diagrama.

FluxoCopy Anchor Link

flowchart LR
  A["Mudança de estado"] --> B[("Tabela events")]
  B --> C["XADD events:account:id"]
  C --> D["SSE pro app"]

SequênciaCopy Anchor Link

sequenceDiagram
  participant App as app
  participant API as api
  App->>API: POST /accounts/{uid}/events/ticket
  API-->>App: 201 { ticket, url }
  App->>API: GET url (EventSource, em até 60 s)
  API-->>App: event: event
  API-->>App: event: ping (a cada 5 s sem dados)

EstadosCopy Anchor Link

Use stateDiagram-v2. O diagrama completo do pareamento está em Pareamento.

stateDiagram-v2
  direction LR
  [*] --> open
  open --> resolved: resolver
  open --> dismissed: não é risco
  resolved --> open: reabrir em até 7 dias
  dismissed --> open: reabrir em até 7 dias

Entidades e relaçõesCopy Anchor Link

Um erDiagram com as tabelas de alerta da migração 0044_risk_alerts:

erDiagram
  seats ||--o{ risk_alerts : "tem"
  risk_alerts |o--o{ risk_findings : "agrupa (alert_id)"
  risk_alerts ||--o{ risk_alert_events : "histórico"
  risk_alerts |o--o| risk_alerts : "previous_alert_id"
  risk_alerts {
    uuid uid
    text kind
    text severity
    text group_key
    text status
    timestamptz superseded_at
  }
  risk_alert_events {
    text type
    bigint member_user_id
    jsonb detail
    timestamptz at
  }

Os diagramas reais dos guias: estados em Pareamento, o ciclo do alerta em Alertas e o caminho de um evento em Webhooks e eventos.

Tabelas de tipoCopy Anchor Link

Direto do TypeScriptCopy Anchor Link

<AutoTypeTable> lê o tipo exportado do arquivo na hora do build (fumadocs-typescript), com os comentários de documentação. O path é relativo a apps/docs.

<AutoTypeTable
  path="../../backend/src/domains/protection/dtos/protection.dto.ts"
  name="ProtectionState"
/>

Pra mostrar só parte de um tipo grande (props que estendem um elemento HTML, por exemplo), passe um type no mesmo contexto do arquivo:

<AutoTypeTable
  path="../../packages/ui/src/feedback/badge.tsx"
  name="BadgeLook"
  type="Pick<BadgeProps, 'tone' | 'size' | 'icon' | 'render'>"
/>

Escrita à mãoCopy Anchor Link

<TypeTable> quando o tipo não existe em TypeScript, como o frontmatter acima ou o corpo de um webhook:

<TypeTable
  type={{
    status: {
      type: '"draft" | "review" | "stable" | "deprecated"',
      description: "Vira um selo embaixo da descrição.",
    },
  }}
/>

GráficosCopy Anchor Link

<Chart> desenha linha (line), barra (bar) ou área (area) do mesmo jeito que os gráficos do backoffice: SVG na largura real, grade discreta, legenda a partir de duas séries, tooltip ao passar o mouse e uma tabela com os dados pra leitores de tela. As cores das séries são --docs-chart-1 a --docs-chart-5 (theme.css).

Dados de um JSONCopy Anchor Link

Importe o arquivo no topo da página e espalhe as props. Os JSONs ficam em content/data/ (fora de content/docs/, onde todo .json é lido como meta.json).

import rateLimits from "../../data/rate-limits.json";

<Chart {...rateLimits} />

Dados na própria páginaCopy Anchor Link

<Chart
  type="bar"
  title="Janela de análise ao vivo: o que fecha a janela"
  caption="ANALYSIS_QUIET_SECONDS e ANALYSIS_MAX_WINDOW_SECONDS em backend/src/config/env.ts."
  x="regra"
  unit=" min"
  series={[{ key: "minutos", label: "Minutos" }]}
  data={[
    { regra: "Conversa quieta", minutos: 2 },
    { regra: "Idade máxima", minutos: 15 },
  ]}
/>

CódigoCopy Anchor Link

Blocos de código têm título, abas, destaque de linha e números de linha (Shiki, pelo rehypeCode).

await rateLimit(`minha-rota:link:${hashToken(token)}`, {
  limit: 10,
  windowSeconds: 600, 
});
await rateLimit(`minha-rota:ip:${clientIp(c)}`, {
  limit: 30, 
  limit: 60, 
  windowSeconds: 600,
});

Blocos seguidos com tab viram um grupo de abas:

{
  "success": true,
  "data": { "ticket": "eyJ…", "url": "/accounts/…/events?ticket=eyJ…" }
}

Código inline também ganha cor: termine o trecho com {:ts} (ou outra linguagem) dentro dos acentos graves, como em rateLimit(key, { limit: 10 }).

PassosCopy Anchor Link

Títulos com [step] viram passos (plugin remarkSteps):

Outros componentesCopy Anchor Link

CalloutCopy Anchor Link

BannerCopy Anchor Link

Um aviso de largura total dentro da página (<Banner>):

AccordionCopy Anchor Link

CardsCopy Anchor Link

Imagem com zoomCopy Anchor Link

Toda imagem em Markdown abre ampliada ao clicar. Caminhos relativos viram import (o build sabe o tamanho):

![Lockup da Superdinda](../../../../platform/public/brand/lockup-violet.png)

Índice no corpoCopy Anchor Link

<InlineTOC items={toc} /> mostra os títulos da página, como no começo desta. toc já existe em todo .mdx.

FontesCopy Anchor Link

• apps/docs/source.config.ts, src/lib/source.ts, src/lib/frontmatter.ts
• apps/docs/src/components/mdx.tsx, src/components/mdx/mermaid.tsx, src/components/mdx/chart.tsx, src/components/page-meta.tsx
• apps/backoffice/src/components/charts/* (o desenho que o <Chart> segue)
• Fumadocs: Mermaid, Markdown, Collections, Macro API, Global options, Auto Type Table