Markdown Support

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

Markdown only

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.

Converting a note to HTML

Markdown only

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 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:

• HTML · Markdown — works the same in .html and .md notes.
• HTML · Markdown (limited) — works in .md notes too, with a difference the section spells out.
• HTML only — not available in .md notes.
• Markdown only — 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	Not available — they’re HTML markers. /Table inserts a plain Markdown table you can edit
Lead paragraphs, fact boxes, presenting a folder	Not available
Whiteboard embeds	Available — written as ![[board.wb]]
Callouts	Available — from the slash menu, or written as > [!NOTE]
Mermaid diagrams	Available — from the slash menu, or typed as a ```mermaid fence
Formatting toolbar	Bold, italic, code, strikethrough (~~text~~), highlight (==text==, one colour), links and AI work; underline and text colour don’t exist in Markdown
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	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, @mentions	Indexed, searchable, and suggested as you type; no chip or ⌘-click
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	Always created as HTML; .md notes still feed them
Block handle: drag to reorder, Properties…, Move to note…	Not available — move a line with ⌥↑ / ⌥↓
Dividers	Available — click one to edit its ---
Encrypting one passage	Not available — encrypt the whole file
Right-to-left page toggle	Available — stored as dir: rtl in the note’s front matter
Footnotes	Written as [^1] or ^[inline] — the slash command is HTML-only
Read aloud	Works — narrates the rendered text, not the Markdown symbols
AI slash commands, Beautify, typing suggestions, Write-with-AI new files	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.