Markdown or rich text: which should you actually write in

By Lior Rabanian · · 5 min read
  • Notes
  • Writing
  • Buying advice

People arrive at this question expecting a philosophical answer and usually need a practical one. So, up front: for most people, most of the time, the choice between Markdown and rich text is far less consequential than the thing they are actually worried about, which is whether their writing is trapped.

Those are different questions, and separating them makes both easy.

What each one actually is

Markdown is plain text with conventions. # Heading, bold, - item. The file on disk is exactly what you typed, readable in any text editor on any machine, forever. It was designed in 2004 to be readable as text — the syntax is meant to look like what people already did in emails.

Rich text is text with structure stored separately from its appearance. You press ⌘B, the word goes bold, and somewhere there is a record saying "characters 4 to 8 are bold". The file might be .rtf, .docx, a database row, or structured JSON.

The usual framing is that Markdown is portable and rich text is not. That was true once. It is now roughly half true, and the half that survives is the half worth thinking about.

Where the difference has genuinely disappeared

Most good editors now accept Markdown as input regardless of how they store the result. Type ## at the start of a line and you get a heading. Type - and you get a list. Wrap a word in asterisks and it goes italic as you close the second one.

So the daily experience — hands on the keyboard, no reaching for a toolbar — is available in both. If you like typing # for a heading, that is a preference an editor can satisfy without storing your document as a text file. Cyanote does exactly this: you can type Markdown, and it can import Markdown files and export them again, while what it stores is structured.

Which means the question "do I want to type Markdown?" and the question "do I want my notes stored as Markdown files?" have come apart, and most people asking the first are answered by any decent editor.

A note being written with headings, lists, a table and a code block, the structure applied as you type
The syntax you type and the format on disk stopped being the same decision some years ago.

What Markdown genuinely wins

Diffs and version control. If you want git log on your notes, or to see what changed between two versions line by line, plain text is the only sane answer. Nothing else diffs cleanly.

Scripting. grep, sed, a Python script to pull every line starting with TODO. When your notes are text files, every tool you already own works on them without an integration.

A guarantee about the far future. A folder of .md files is readable in 2050 by definition, because reading them requires nothing except the ability to read text.

Working with developers. Documentation, READMEs, issue trackers, static sites — the entire toolchain speaks Markdown natively.

If two or more of those describe you, write in Markdown and store Markdown. It is the right answer and you can stop reading.

What rich text genuinely wins

Tables. Markdown tables are painful to write and worse to edit — realigning pipes by hand for a table you have added a column to is a genuine cost, paid every time.

Images. In rich text you paste a screenshot and it is in the note. In Markdown you paste a screenshot and something has to decide where the file goes and what path to write. Editors handle this, with varying grace, and it is always a machine somewhere holding a file the text refers to.

Things Markdown has no words for. Callouts, toggles, coloured highlights, checkboxes with state, a linked note that renders as its title. Each of these exists in Markdown only as an extension somebody invented, which means the file is portable and its meaning is not.

Not thinking about it. For a lot of people, syntax visible in the middle of a sentence is a small tax on attention, paid all day.

The question that actually settles it

Here it is: can you get your work out, in a form you can read without this app?

That is the question people are really asking when they ask about Markdown. Markdown is one way to guarantee it — the file is the readable form, so there is nothing to trust. But it is not the only way. An app that stores structure and exports clean Markdown gives you the same guarantee, one step removed, provided the export is real.

So test the export rather than reading the format's name. Take your most complicated note and see what comes out — that is fifteen minutes and it answers the question no amount of debating file formats will.

The failure mode to avoid is not rich text. It is opaque storage with no export: a format nobody has documented, in a service you cannot copy, with a download button that produces something only that service can read. That is the actual trap, and it is entirely possible to build it out of Markdown too.

Where storage is worth caring about anyway

One thing that survives the argument: how a rich-text app stores things affects what it can do.

Structured storage is what makes a link between two notes a real reference rather than a piece of text that resembles one, and it is what lets an app rename a note and fix every mention of it. In a folder of Markdown files, that same rename is a search and replace, with all the failure modes that implies.

That is the trade in one sentence. Markdown gives you a file that any tool can read; structure gives the app knowledge about the relationships in your notes. Different things, both real, and which you want depends on whether your notes are mostly documents or mostly a network.

A recommendation, since that is what you came for

  • You write code, use Git, or live in a terminal → Markdown files, in a folder you control.
  • You write prose and want it to still open in thirty years → Markdown, or rich text with an export you have personally tested.
  • You want tables, screenshots, checkboxes and links between notes without ceremony → rich text, and be strict about the export.
  • You are choosing between two apps and this is the deciding factor → it probably is not the deciding factor. Try a week in each and see which one you actually open.

The people I know who are happiest with their notes did not resolve this question. They picked a tool that lets them type without ceremony, checked once that they could leave, and got on with writing.