# Markdown Support

> Editing .md files, and where the Markdown surface differs from HTML.

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

DocGraph supports HTML and Markdown side by side — `.md` files are first-class: they render properly, edit in place, and are indexed, linked and searched exactly like HTML notes.

## Editing Markdown

Click into a rendered Markdown document and edit it directly. Headings, lists and paragraphs behave as they do in the HTML editor — Enter splits a block, Backspace at the start merges it upward, and both settle without reloading the page.

Typing shorthand works as you'd expect: `- ` starts a list, `1. ` a numbered one, `[ ] ` a task, `> ` a quote, ```` ``` ```` a code block and `---` a divider — each renders in place as soon as you type it. Enter continues a quote, and Backspace at the start of a quote line takes it out of the quote. `⌥↑` / `⌥↓` move the line (or list item) you're on up and down. And because a `.md` file *is* Markdown, a line you turn into `# Heading` is already a heading on disk the moment it's saved — the rendered view catches up when your cursor leaves the block.

## Obsidian syntax

An Obsidian vault opens as-is. DocGraph reads the Markdown extensions such vaults are full of:

| Written | What you get |
|---|---|
| `[[Note]]`, `[[Note\|label]]`, `[[Note#Heading]]` | A real link, found by name anywhere in the vault — it shows up in backlinks, the graph and Problems like any other. A name no note has yet is dimmed; following it offers to create the note, and creating it fixes every link to that name. Renaming a note updates its `[[links]]`. |
| `[[Note#^abc123]]`, a line ending ` ^abc123` | A link to one block. **Copy link to block** in the right-click menu adds the ` ^id` for you. Following a heading or block link opens the note scrolled to it; `[[#Heading]]` jumps within the page. |
| `![[image.png]]`, `![[image.png\|300]]` | The image, at that width. |
| `![[board.wb]]` | A whiteboard preview. |
| `![[Note]]`, `![[Note#Heading]]`, `![[Note#^id]]` | That note — or that section, or that block — shown in place, read-only. One level deep: an embed inside an embed stays a link. |
| `==highlighted==` | Highlighted text. |
| `^[a note]` | A footnote. |
| `$E=mc^2$`, `$$ … $$` | Math. |
| `%%a comment%%` | Hidden in the page, kept in the file. |
| `tags:` / `aliases:` in front matter | Indexed tags, and other names for the note — `[[links]]` resolve them, and the `[[` picker and ⌘K find the note by them. |
| `dir: rtl` in front matter | A right-to-left page (the reading popover's toggle writes it for you). |

## Live Preview

Markdown that carries formatting — a bold word, a link, a heading marker — shows as *rendered* text until you click into it, at which point that block reveals its raw source so you can edit the markup directly. Click away and it renders again. Escape leaves a block without changing it.

The same reveal-at-the-cursor behaviour applies to HTML notes, where DocGraph synthesizes the Markdown-style syntax for a bold or linked span.

### Turning Live Preview off

Switch off **Reveal syntax at the caret** in **Settings → General → Editor → Live Preview** (it's on by default), then reopen the file. Formatted text then stays rendered when the cursor enters it; edit the markup itself in **`<>Source`**.

## Source view

Toggle **`<>Source`** to edit the raw text in a full code editor with syntax highlighting. This is also the escape hatch for anything the inline editor won't touch.

## Markdown tables [!md]

**Table** in the slash menu inserts a plain GitHub-style Markdown table, and any `| a | b |` table you already have is editable the same way. Click a cell to type in it. Hover the table for a grip that adds, deletes and reorders rows and columns.

Cells keep their **bold**, *italic*, ~~strikethrough~~, `code` and links — `⌘B`, `⌘I` and `⌘L` format text while you edit a cell — and cells you don't touch are written back exactly as they were, wikilinks and escapes included.

For tables with typed columns, queries and charts, use an HTML note — see [Tables & Charts](https://docs.docgraph.app/tables-charts/overview/).

## Converting a note to HTML [!md]

Some features — block properties, data tables — need an HTML page. To move a Markdown note over, right-click it in the file tree and choose **Convert to HTML page…**, or run **Convert to HTML page** from `⌘K`. A confirmation says how many other notes link to it, then DocGraph:

- writes the page next to the original with the same name and an `.html` extension — or the first free `-2`, `-3`… name if one already exists — and opens it;
- rewrites the links in other notes so they point at the new page;
- carries over the note's tags, aliases and page properties;
- moves the original `.md` file to the OS trash, which is where to restore it from.

A few things have no place in HTML and are reported afterwards in a message ("Not carried into the HTML page: …"): raw HTML fragments, `%%inline comments%%`, and the open or closed state of a foldable callout. An [encrypted](https://docs.docgraph.app/privacy/encryption/) note is refused, because converting it would write its text out in the clear. A note with unsaved changes in `<>Source` asks you to save or discard them first.

## Where Markdown differs from HTML

Throughout these docs, a badge under a page title or a section heading tells you which note format that feature works in:

- <span class="fmt-badge fmt-both">HTML · Markdown</span> — works the same in `.html` and `.md` notes.
- <span class="fmt-badge fmt-partial">HTML · Markdown (limited)</span> — works in `.md` notes too, with a difference the section spells out.
- <span class="fmt-badge fmt-html">HTML only</span> — not available in `.md` notes.
- <span class="fmt-badge fmt-md">Markdown only</span> — specific to `.md` notes.

Features that don't depend on a note's format — search, the graph, whiteboards themselves, AI chat, version history, settings — carry no badge.

Most gaps come from the format itself: a `.md` file is rendered with raw HTML switched off, so anything DocGraph stores as an HTML marker or attribute has nowhere to live in it.

| | In a `.md` note |
|---|---|
| [Data tables, saved queries, charts](https://docs.docgraph.app/tables-charts/overview/) | Not available — they're HTML markers. `/Table` inserts a plain [Markdown table](#markdown-tables) you can edit |
| [Lead paragraphs, fact boxes](https://docs.docgraph.app/editing/blocks/#emphasis-blocks), [presenting a folder](https://docs.docgraph.app/editing/presenting/) | Not available |
| [Whiteboard embeds](https://docs.docgraph.app/whiteboards/basics/#embed-a-board-preview-in-a-note) | **Available** — written as `![[board.wb]]` |
| [Callouts](https://docs.docgraph.app/editing/blocks/#callouts) | **Available** — from the slash menu, or written as `> [!NOTE]` |
| [Mermaid diagrams](https://docs.docgraph.app/editing/blocks/#diagrams) | **Available** — from the slash menu, or typed as a ` ```mermaid ` fence |
| [Formatting toolbar](https://docs.docgraph.app/editing/documents/#formatting) | Bold, italic, code, strikethrough (`~~text~~`), highlight (`==text==`, one colour), links and AI work; underline and text colour don't exist in Markdown |
| [Images](https://docs.docgraph.app/editing/images/) | Paste and drop work and write ``; click an image to select it and Backspace deletes it. No resize handles or zoom — Markdown has no width syntax to write (`![[image\|300]]` is read, though) |
| [Typed links](https://docs.docgraph.app/editing/links-and-tags/#typed-relationships) | **Available** — written as `[[Page]]{rel=depends-on}` after a link, or as a relation key in front matter (`depends-on: [[Page]]`); the link prompt's **Link type** field and the `[[` picker's **Tab** write it for you |
| Contradictions (a `contradicts` link type) | **Available** — written as `{rel=contradicts}` after a link; the pair shows in Problems |
| [`#tags`](https://docs.docgraph.app/editing/links-and-tags/#tags), [`@mentions`](https://docs.docgraph.app/editing/links-and-tags/#mentions) | Indexed, searchable, and suggested as you type; no chip or ⌘-click |
| [Task tokens](https://docs.docgraph.app/panels/task-tokens/) | Read and filtered the same; `@`, `due:` and `start:` menus work, without the time-of-day rows or the date picker. No chips, and no automatic creation time |
| [Person pages and 1:1s](https://docs.docgraph.app/panels/mentions/) | Always created as HTML; `.md` notes still feed them |
| [Block handle: drag to reorder, Properties…, Move to note…](https://docs.docgraph.app/editing/documents/#moving-and-deleting-blocks) | Not available — move a line with `⌥↑` / `⌥↓` |
| [Dividers](https://docs.docgraph.app/editing/blocks/#dividers) | **Available** — click one to edit its `---` |
| [Encrypting one passage](https://docs.docgraph.app/privacy/encryption/#encrypt-one-passage) | Not available — encrypt the whole file |
| [Right-to-left page toggle](https://docs.docgraph.app/editing/reading/#right-to-left-text) | **Available** — stored as `dir: rtl` in the note's front matter |
| [Footnotes](https://docs.docgraph.app/editing/blocks/#footnotes) | Written as `[^1]` or `^[inline]` — the slash command is HTML-only |
| [Read aloud](https://docs.docgraph.app/voice/overview/#have-a-page-read-aloud) | Works — narrates the rendered text, not the Markdown symbols |
| [AI slash commands, Beautify, typing suggestions, Write-with-AI new files](https://docs.docgraph.app/ai/in-your-documents/) | Not available |
| Toolbar Summarize and Check spelling, selection AI, dictation | Work |
| Links, backlinks, graph, search, outline, undo, right-click menu | Work |

Markdown editing can be turned off with **Single-host caret (Markdown)** in **Settings → General → Editor → Experimental**. With it off, prose in `.md` files is read-only in Inline mode — tasks, tables and collapse stay usable — and you edit text through **`<>Source`**.