Rich Markdown

Monofile renders a small set of designed blocks in the editor, in shared folders, on share links, and on this docs site. They are plain markdown. A file's raw .md contains nothing but CommonMark, so agents can write and edit them like any other text, and any other markdown reader still shows something sensible.

Use them for guides such as READMEs, runbooks, setup docs and how-tos. Plain notes do not need them.

Code blocks with a header

Add options after the language on the fence line.

```bash title="Terminal"
npm i -g @monofile/cli
```

```json path=".cursor/mcp.json"
{ "mcpServers": {} }
```

```text nocopy
Output nobody would paste.
```

Tabs for variants

Consecutive fences tagged tab="…" become one block with tabs. Use them when one action is spelled differently per package manager, shell or operating system.

```bash tab="npm"
npm i -g @monofile/cli
```
```bash tab="pnpm"
pnpm add -g @monofile/cli
```
```bash tab="bun"
bun add -g @monofile/cli
```

Callouts

This is GitHub's syntax. The first line of a quote names the kind.

> [!NOTE]
> The CLI stores one credential per server.

> [!WARNING]
> Always the www host. The apex redirects, and a redirect drops the Authorization header.

There are five kinds: NOTE, TIP, IMPORTANT, WARNING, CAUTION. For a custom title use the container form, :::tip Shortcut … :::. Use callouts sparingly. If every section has one, none of them stands out.

Details

For something long but optional, such as a prompt to paste, a long output, or the reasoning behind a step.

:::details Agent prompt
Set up Monofile for me. Read https://www.monofile.ai/skill.md and follow it.
:::

The title becomes the summary line. The body stays collapsed until the reader opens it.

Steps

One procedure, one :::steps block, one ### per step. Steps render numbered with a connector line. The headings keep their anchors and still appear in the page outline.

:::steps
### Mint a key
Open the API keys page and create a key.

### Add the server
```json path=".cursor/mcp.json"
{ "mcpServers": { "monofile": { "url": "https://www.monofile.ai/api/mcp" } } }
```

### Check it
```bash title="Terminal"
npx -y @monofile/mcp --list
```
:::

Five to seven steps read well. Beyond that, split the guide.

Cards

A list of links becomes a grid of cards. Use it on hub pages and at the end of a section. The link is the card title and the rest of the line is the description.

:::cards
- [[Quickstart]] — Your first file in five minutes.
- [[Agent Quickstart]] — A key and a first tool call.
- [[Connecting MCP Clients]] — Cursor, Claude, Codex and a dozen more.
:::

Tabs for prose

When you explain the same thing for two audiences, put each in a tab.

:::tabs
:::tab Human
Open the API keys page and click Create.
:::
:::tab Agent
`POST /api/keys` with the scopes you need.
:::
:::

Prompt

Text the reader hands to an agent. It renders with a copy button, Open in Claude and Open in ChatGPT. Long prompts start collapsed.

:::prompt Set up Monofile
Set up Monofile for me. Read https://www.monofile.ai/skill.md and follow it: register or use my key, write a first file, and tell me the share link.
:::

Endpoints

An http fence whose first line is the method and path renders a method badge and the path as a header; the rest is the body.

```http
POST /api/tools/write
{"path": "/notes/today.md", "content": "# Today"}
```

Figures, footnotes, keys, emphasised lines

• An image with a title is a figure with a caption: ![The editor](/img/editor.png "The editor, light theme").

• Footnotes are standard: a claim.[^1] in the text and [^1]: The source. at the end.

• Keyboard keys: <kbd>Ctrl</kbd> + <kbd>P</kbd>, the one piece of HTML in the vocabulary.

• Point at lines in a code block with {2,4-6} after the language; the other lines dim.

Rules of thumb

• Title every command block and path every file block. A bare fence is for inline examples.

• Containers nest. An unknown :::name renders as a paragraph, so a typo does not hide content.

• Do not wrap content in HTML or invent other syntax. The vocabulary above is complete.

• Every page also gets a Copy page button that copies the markdown, opens the raw .md, or hands the page to Claude or ChatGPT. It needs no markup from you.

For agents

The same vocabulary is in skill.md under "Rich markdown", and the built-in assistant's design skill has a chapter on writing guides with it. Create one with an ordinary write and change one with an ordinary edit by exact string.

Next steps