Skip to content

Writing a page as Markdown ​

Any page can be written as Markdown instead of in the block editor: the text itself, as you would type it in a code editor, Obsidian or Typora. The choice is per page, and it changes how the page is edited, not what it is.

A Markdown page is still blocks underneath. History and restore, the timeline, placing a block on a day, search, links and backlinks, comments, export and published sites all work on it unchanged. A page stored as one long text would make every edit "characters 4,210 to 4,290 changed", and the timeline would lose what it exists to know: when each piece was written.

Switching a page ​

The format button in the page header says how the page is written — Written as rich text or Written as Markdown. Before anything changes, it shows what switching would change: Markdown cannot hold everything a rich page can, so a callout becomes a quote and a database view becomes a table of its rows. A page that loses nothing says so.

Switching back is the same button. Nothing about the page's history moves either way.

Live preview and Source ​

A Markdown page opens in live preview: headings at their size, emphasis without its asterisks, quotes, bullets and to-do boxes, tables, rules, links that show their words, and references drawn in place. Whatever the caret is on is shown as written, so it all stays text you edit. Ticking a to-do box writes [x] into the text, as typing would.

Source shows the plain Markdown with highlighting. The choice is remembered per page on this device; it is how you look at the page, not something about it, so nobody else sees it.

Drop or paste a file onto a Markdown page and it is stored as an attachment and linked into the text on a line of its own.

How typing becomes blocks ​

Typing is read back into blocks on a pause, and blocks you did not touch keep their identity — so the timeline, provenance and comments on them are undisturbed. A single newline stays a newline, not a space.

Some Markdown cannot be held as written — footnotes, reference-style links, raw HTML. Those are underlined in the editor before anything is lost, rather than quietly rewritten.

Two people on one Markdown page ​

Writing a block takes a lease on it. Anybody else on the page sees that block tinted and labelled with who is editing it, cannot type into it, and writes the rest of the page alongside. Ten seconds of quiet, moving away from the block, or closing the tab lets it go.

Two people typing into the same block in the same instant: whoever the server answered first writes, and the other's edit is filed as a proposal. Nobody's words are lost, and nobody's are overwritten. Last-writer-wins was ruled out from the start.

A dropped connection keeps its lease for 30 seconds, so a blip does not hand the block to somebody else.

Offline ​

A Markdown page edits without a network like any other page you have opened before. Writing done offline is kept on the device and checked block by block on reconnecting:

  • a block nobody else changed meanwhile is written — almost always;
  • a block somebody else changed meanwhile is filed as a proposal for review, never written over them. The save indicator says how many need review;
  • a new block never conflicts.

The writing is dated to when it was typed, as on every page. See working offline.

Keeping your formatting ​

By default a Markdown page writes its own tidy style: - bullets, ** bold, # headings. Turn on Keep my formatting exactly as typed in the format panel and each block is written back — and exported — exactly as you typed it: * bullets, __bold__, a list that starts at 3.

It keeps your text wherever that text still says what the block does. A block changed from somewhere else, or one linking to a page that has since been renamed, is written tidily instead, so the kept form is never stale. Reverting a page restores the bytes too.

References, names and regions ​

Markdown pages use Obsidian's syntax, so the file means the same thing there:

WrittenMeans
![[Weekly review#^decision-q3]]embed that named block or region, drawn read-only under the line
[[Weekly review#^decision-q3]]link to it
![[Weekly review#Risks]]embed a heading's section: the heading and everything under it
^decision-q3 at the end of a linename this block
<!-- region: pricing --> … <!-- /region -->name every block between the markers

A reference is stored by the block's identity, and written from its page's current title and its current name — so renaming the page changes nothing stored. See block references.

What a Markdown page does not offer ​

  • Callouts and database views. They are not Markdown; their export form is a quote plus an HTML comment, which is not something to edit as text.
  • Editing an embedded block in place. Embeds are read-only here; edit the block on its own page, or from a rich page.
  • The block menu, drag handles and (( — block-shaped gestures for a block-shaped editor.
  • Maths and diagrams drawn in live preview. The fences are kept and exported; the rich editor is where they are drawn.

A page's properties stay in the properties panel rather than becoming YAML in the text: a property's type is chosen, never guessed from what was typed.

The full design is recorded in ADR 0015.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.