Authoring
MDX page conventions, components, and glossary rules for the documentation portal.
Frontmatter
Every page needs title and description in YAML frontmatter — sentence-quality, not labels.
Components
Prefer existing portal components over custom markup:
Cards,Card,Callout,Steps,Tabs— Fumadocs defaultsProjectHeader,SourceLink,Term,DomainCards,ProjectCards,Mermaid— portal-specificContractBadge,LifecycleBadge— API contract vocabulary
Import source is configured in frontend/docs-app/src/mdx.tsx.
Glossary
Definitions live only in frontend/docs-app/src/glossary.ts. Use
<Term id="transactional-outbox" /> at the first meaningful mention, then plain text.
Links
- Portal routes:
/docs/projects/services/template - Repository files:
<SourceLink path="services/template/README.md" />
One canonical home
A fact has one home. Link elsewhere instead of copying commands, config keys, or topology.
Styling
Tailwind utilities and portal components only — no one-off CSS. Typography uses Poppins (body) and
Roughwell (headings) via next/font in the root layout.
Cursor rule: .cursor/rules/docs-content.mdc.