Docs conventions

How to add or edit a page in this documentation portal — the MDX file format, frontmatter, and the per-section meta.json sidebar.

This documentation portal is a Fumadocs site. Pages are MDX files under content/docs/. This page explains how to add one.

This is about the docs portal you're reading now — not the in-app documents/*.md files Cremind feeds to its agent for retrieval. The two formats are different; see the comparison at the end.

Add a page in two steps

1. Create the MDX file

Create content/docs/<section>/<slug>.mdx. Every page must start with YAML frontmatter delimited by lines of three dashes:

---
title: My Page Title
description: One sentence describing the page.
---

## First section

Body content in Markdown, starting at `##`.

title becomes the page H1. Do not add a separate # heading in the body.
description is used for the HTML <title>, the sidebar tooltip, and search.
Start body sections at ##, sub-sections at ###.

2. Add the slug to the section's meta.json

Each section folder has a meta.json that controls its sidebar title and page order:

{
  "title": "My Section",
  "pages": ["overview", "first-page", "second-page"]
}

Each entry in pages is a filename without the .mdx extension, listed in the order you want them in the sidebar. Add your new slug where it belongs. A subfolder is listed as a slug too, and the subfolder gets its own meta.json.

The root content/docs/meta.json lists the top-level sections in sidebar order; you only touch it when adding a whole new section.

MDX components

These components are injected globally — do not import them:

<Callout type="info">…</Callout> — type is info, warn, or error; optional title="…".
<Cards> with <Card title="…" href="/docs/…">desc</Card> — for link grids.
Fenced code blocks with a language tag (bash, powershell, yaml, python, json, text).
GFM tables, links like [text](/docs/section/slug), bold/italic, and lists.

MDX safety

MDX parses the body as JSX, so a few things break the build:

Never put a raw < or { in prose. Wrap code-y text in backticks or rephrase. Write the events/<event_type>/ folder as inline code, not as bare text.
Every JSX tag must be closed and balanced. Keep Callout and Cards/Card well-formed.
Use {/* … */} for comments, not HTML comments.

How this differs from in-app documents

Cremind itself can ingest Markdown documents for retrieval (the agent's knowledge files). Those are a different thing from these docs pages:

	Docs portal (this site)	In-app `documents/*.md`
Purpose	Human-readable product documentation	Knowledge the agent retrieves at runtime
Format	MDX with frontmatter + injected components	Plain Markdown
Frontmatter	`title` + `description` required	Not required for RAG
Sidebar	Ordered by `meta.json`	Not applicable

When you write for this portal, follow the rules above. When you write knowledge for the agent, plain Markdown is fine — don't reach for Callout or Cards there.

Preview locally

The docs site is a standard Fumadocs/Next.js project. From the site repo, install dependencies and run the dev server (typically npm install then npm run dev), then open the local URL it prints. Frontmatter or MDX errors surface in that dev server's output — fix them before opening a PR.