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. ````markdown ```bash title="Terminal" npm i -g @monofile/cli ``` ```json path=".cursor/mcp.json" { "mcpServers": {} } ``` ```text nocopy Output nobody would paste. ``` ```` | Option | Header shows | Use for | |---|---|---| | `title="Terminal"` | `›_ Terminal` with a copy button | commands the reader runs | | `path=".cursor/mcp.json"` | the file name | files the reader creates or edits | | `nocopy` | no copy button | output, logs, things nobody pastes | ## 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. ````markdown ```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. ````markdown > [!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. ````markdown :::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. ````markdown :::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. ````markdown :::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. ````markdown :::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. ````markdown :::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. ````markdown ```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: `Ctrl` + `P`, 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 Files|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 :::cards - [[Markdown Reference]] — Every markdown feature Monofile renders, with examples. - [[Wiki-Links]] — Links between files: autocomplete, aliases, and links that survive renames. - [[The Markdown Editor]] — Live WYSIWYG editing, slash commands, and how saving works. - [[Skill Files]] — The machine-readable onboarding set agents can fetch and follow. :::