noted.do
The Tech Guy

The Case for Writing Everything in Markdown

Notes, drafts, documentation, to-do lists, meeting notes, this blog post. Basically anything I write that isn't a quick text message starts as a Markdown file. I'd recommend it to almost anyone, and not because it's trendy with programmers.

If you haven't run into it, Markdown is just plain text with a few conventions for formatting. A pound sign at the start of a line makes a heading. Asterisks around a word make it italic, two of them make it bold. A dash at the start of a line is a bullet. Square brackets and parentheses make a link. That covers most of what anyone ever needs, and you can learn it in the time it takes to drink a coffee.

The magic is that a Markdown file is readable whether or not anything renders it. Open it in the plainest text editor on the oldest computer you can find and it still makes sense. The headings look like headings, the list looks like a list. Compare that to a word processor file, which is a pile of structured data that needs the right software (and sometimes the right version of the right software) to open properly.

That's the main reason I like it. It's durable. Text files have been readable for as long as computers have existed and they'll stay readable long after whatever app is popular this year is gone. I've watched note-taking apps come and go, and the worry every time is "how do I get my stuff out?" With Markdown, your stuff was never really in. It's a folder of files. You can switch apps by pointing a new one at the folder.

It's also portable in the other direction. The same file can become a web page, a PDF, a slide deck, a printed document or an email with the right tool. Pandoc in particular will convert Markdown into just about anything. GitHub renders it, a lot of blogging platforms take it directly, chat apps understand most of it, and plenty of note apps (Obsidian, Standard Notes, iA Writer, Typora, and others) are built around it.

There's a writing benefit I didn't expect, too. Because you can't fiddle with fonts, colors and margins, you just write. Formatting becomes a structural decision (is this a heading or not?) rather than a visual rabbit hole. I find I finish things faster.

And it plays well with everything else in a technical workflow. Plain text works with search tools, with sync tools, with backups. It works with Git, so you can track every change to a document and see exactly what changed, which is wonderful for documentation and surprisingly handy for things like a long-running personal journal.

To be fair about the downsides: Markdown isn't great for complex layouts. Tables are clunky to write by hand. There are several slightly different flavors (CommonMark, GitHub Flavored Markdown and others), so a footnote or checkbox that works in one place might not render in another. And if you need tracked changes with comments for a non-technical team, a regular document editor is still the better tool. I don't write contracts in Markdown.

But for the everyday stuff, the notes and drafts and docs that make up most of what people write, it's hard to beat a format that's simple, readable, and will outlive every app you use to edit it. Start with one folder and a text editor. That's honestly all you need.

Comments

Be kind. See the rules.