# Diagrams, Callouts & Code

> The block types you can drop into a page with the slash menu, plus Markdown callout syntax.

Source: https://docs.docgraph.app/editing/blocks/

Type `/` anywhere in an HTML page to open the block menu. It's the single entry point for everything you can insert — this page covers the ones that aren't documented elsewhere.

## The slash menu [!partial]

*[Screenshot: The slash menu open at the end of a paragraph, listing Template, Today's note, Reference page, Data table, Query and HTML table.]*

| Where it sits | What you can insert |
|---|---|
| **Blocks** (a headed section) | Callout (Note, Tip, Info, Warning, Danger), Lead paragraph, Fact box, Quote, Speaker notes, Bulleted list, Numbered list, To-do list, Code block, Divider, [Image](https://docs.docgraph.app/editing/images/) |
| Top of the menu, no heading | [Data table](https://docs.docgraph.app/tables-charts/overview/), [Query](https://docs.docgraph.app/tables-charts/overview/), [Insert chart](https://docs.docgraph.app/tables-charts/overview/), HTML table, [Whiteboard](https://docs.docgraph.app/whiteboards/basics/) |
| Top of the menu, no heading | Template, Today's note, Reference page, Embed note, Footnote, Math (TeX), Insert diagram (Mermaid) |
| **AI** (a headed section) | [Write with AI, Ask AI, Beautify page, Summarize, Continue writing](https://docs.docgraph.app/ai/in-your-documents/) |

Type to filter — the menu matches names and keywords, so `/box` finds **Fact box** and `/lede` finds **Lead paragraph**.

Only **Blocks** and **AI** render as headed sections; everything else sits in an unlabelled group at the top of the menu.

Markdown files get a smaller menu: Template, Today's note, Reference page, Table (a plain Markdown table), Bulleted list, Numbered list, To-do list, Code block, Quote, Divider, the five callouts, Math (TeX) and Insert diagram (Mermaid). The AI group, the data blocks and the emphasis blocks don't appear there. Embeds and footnotes are typed as Markdown instead (`![[Note]]`, `^[note]`).

## Diagrams [!both]

**Insert diagram (Mermaid)** adds a [Mermaid](https://mermaid.js.org/) diagram — flowcharts, sequence diagrams, class and state diagrams, all written as text and rendered live in the page.

How it's stored depends on the file. In a Markdown note it is a ` ```mermaid ` fenced code block, so **it works in Markdown files too** — one of the few rich blocks that does. In an HTML page it is a `<pre data-docgraph-mermaid>` element holding the diagram text.

### Editing a diagram [!html]

In an HTML page, hover a rendered diagram and an **✎ Edit** button appears in its top-right corner. It opens an **Edit diagram** window with the diagram source on the left and a live preview on the right, which re-renders as you type. A syntax error shows in the preview pane instead of the picture. **Save** writes the new source into the page and reloads it; **Cancel** discards the change. A diagram that fails to render shows the same button, so you can fix it. In a Markdown note, click into the fence and edit the text.

## Callouts [!both]

A callout is a tinted, titled box with an icon. There are two ways to make one, and which one you get depends on the file you're in.

**From the slash menu** in either kind of file. Five kinds are offered: Note, Tip, Info, Warning and Danger. Type `/callout` to see them all.

**In a Markdown file** you can also write one the way Obsidian does — a block quote whose first line names the type in brackets:

```markdown
> [!QUESTION]
> How does the index decide what to re-read?
```

The bracket syntax is Markdown-only. Typing it in an HTML page leaves the brackets as literal text, because an HTML page isn't Markdown. 

### Callout types

Fourteen types are recognised in Markdown, each with its own colour and icon. Several accept aliases, so a note written for Obsidian or GitHub renders the same here.

| Type | Also accepts |
|---|---|
| `note` | |
| `abstract` | `summary`, `tldr` |
| `info` | |
| `todo` | |
| `tip` | `hint` |
| `important` | |
| `success` | `check`, `done` |
| `question` | `help`, `faq` |
| `warning` | `caution`, `attention` |
| `failure` | `fail`, `missing` |
| `danger` | `error` |
| `bug` | |
| `example` | |
| `quote` | `cite` |

The type is case-insensitive, so `[!note]` and `[!NOTE]` are the same thing. An unrecognised type still makes a callout: it's titled with whatever word you wrote and styled as a plain note, rather than being dropped.

One deliberate difference from Obsidian: `important` keeps its own purple styling instead of being folded into `tip`.

### Titles and folding

Text after the type replaces the default title:

```markdown
> [!TIP] Try this first
> Restart the indexer before digging deeper.
```

Add `-` or `+` after the bracket to make the callout foldable. A `-` starts it collapsed, a `+` starts it expanded:

```markdown
> [!EXAMPLE]- A worked example
> Hidden until you click the title.
```

A foldable callout becomes a real disclosure element, so the open and closed state is the reader's, not something stored in the file.

### Editing a callout

A callout is a block quote on disk, so it behaves like one. Enter at the end of a line continues the callout. Enter in the middle of a line keeps both halves inside the box. Backspace at the start of a line drops its quote marker and moves that line out of the box.

Body text edits in place like any other Markdown prose. A body wrapped across several source lines reveals its raw source when you click into it, the same as any hard-wrapped Markdown paragraph. Click the header line to edit the whole callout's Markdown in place — that's where you change its type after the fact. On a foldable callout, only the chevron folds it.

## Emphasis blocks [!html]

Three styled prose blocks, all from the slash menu, HTML pages only:

- **Lead paragraph** — a larger intro line, for the standfirst of a note.
- **Fact box** — a boxed key statement, for a definition or a number that matters.
- **Quote** — a styled pull-quote.

These are ordinary paragraphs with a CSS class, not special widgets. That means they stay fully editable like any other text, and if you open the file outside DocGraph you get a normal `<p>` with a class on it.

## Code [!both]

**Inline code** — wrap text in backticks as you type and it becomes a `code` span. Both inline spans and fenced blocks are **fully editable in place**.

**Code block** inserts a fenced block. Inside a fence:

- Enter inserts a real newline rather than splitting the block.
- Tab inserts a tab.
- Markdown shorthand stays literal — a `# ` in a code block is a `# `, not a heading.
- Pasting keeps your text **verbatim**, with no Markdown conversion.

Typing three backticks also opens a fence. Put the cursor in a code block and its ` ```lang ` fences show, so you can change the language in place — the block re-renders, and changing it to `mermaid` turns it into a [diagram](#diagrams). A code block never merges with the blocks around it when you Backspace or Delete at its edge.

Every code block has a line-number gutter and a **Copy** button that copies its text.

Code blocks are **syntax-highlighted** when the fence names its language (` ```js `, ` ```python `, ` ```rust `, ` ```sql `…): keywords, strings, numbers and comments get their own colours. A fence with no language gets strings, numbers and comments only. The colouring is painted over the text, never written into it.

## Dividers [!both]

**Divider** in the slash menu, or `---` / `***` typed on a line of its own, draws a horizontal rule.

To change or remove one, click it — or arrow onto it with `↑` / `↓` — and it turns into an editable line showing its Markdown, `---` (in a `.md` note, the rule's own spelling, such as `***`):

- Move away with the text still a rule and the divider stays.
- Delete the text and the divider is removed; **Backspace** on the emptied line removes it and puts the cursor at the end of the line above.
- Type anything else and the line becomes that text.
- **Esc** puts the divider back as it was; **Enter** leaves the line.

The right-click menu's **Remove divider** deletes one directly.

## Math [!both]

**Math (TeX)** inserts a formula; in a Markdown file you can also type `$E=mc^2$` inline or a `$$ … $$` block. It's rendered from TeX with KaTeX. Edit the TeX in `<>Source` (HTML) or by clicking into the block (Markdown). A price like `$5 and $10` is left alone.

## Footnotes [!partial]

**Footnote** (HTML) inserts a numbered reference with the note written right there in the source; DocGraph numbers the references in order and lists the notes at the end of the page, so adding or removing one never renumbers anything by hand. Hover a number to read its note; edit the text in `<>Source`. In Markdown, write `[^1]` with a `[^1]: …` definition, or `^[the note]` inline.

## Embedding a note [!both]

**Embed note** (HTML) or `![[Note]]` (Markdown) shows another note's content in place, read-only, with a link to open it. `![[Note#Heading]]` embeds just that section, `![[Note#^id]]` just that block. Embeds go one level deep, scripts in the embedded note never run, and an encrypted note shows as locked rather than its text. In Markdown, `![[image.png]]` embeds an image and `![[board.wb]]` a whiteboard preview. An embedded note counts as a link: the embedding note appears in its backlinks, and in the graph and AI search the two are connected.

## Collapsible sections [!both]

Headings can fold. With **Collapsible headers** on — it's on by default, under **Settings → General → Appearance → Vault behaviour** — each heading is wrapped in a section you can click to collapse, so a long note becomes an outline you expand as you read. The toolbar's **Collapse all sections** / **Expand all sections** button folds or unfolds every section at once; it doesn't switch the feature on, and with the setting off there is nothing to fold.

Collapsing is a *view* — the file on disk is unchanged, and a collapsed section still contains its text for search and the AI.

## Tasks [!both]

**To-do list** inserts a checkbox item; typing `[ ] `, `[] ` or `[x] ` (optionally after `- `) at the start of a line does the same, checked when it's `x`. Enter continues the checklist. Tick a box in the page — or press `⌘Enter` with the cursor in the to-do — and it's written to the file. Done items are struck through.

Task checkboxes collect into the vault-wide [Todo panel](https://docs.docgraph.app/panels/todo/), from Markdown and HTML notes alike. They can also carry an assignee, a due date and a start date, written in the task's own text — see [Todos & Task Properties](https://docs.docgraph.app/panels/todo/).

## Reference pages [!both]

**Reference page** inserts a link to another note, with a picker. In an HTML page, if no note has the name you typed, **Create "name"** makes a new page next to this one and links it. Typing `[[` does the same thing inline — start typing a note's name and pick it from the list. See [Links & Tags](https://docs.docgraph.app/editing/links-and-tags/).