"Markdown By Default" is a great convention for notetaking

Adopting the convention of writing notes in Markdown has been hugely helpful for me. It’s an easy-to-use, easy-to-read, easy-to-learn, format for something I do every day, and a great example of convention over configuration. It helps to capture notes and events in high fidelity, at low cost. I can listen to a conversation and write almost automatically without having to think about how to structure my notes. I don’t have to decode my notes for other readers. It Just Works.

What is Markdown?

Wikipedia says:

Markdown is a lightweight markup language…allowing people “to write using an easy-to-read, easy-to-write plain text format…then convert it to structurally valid XHTML (or HTML)…Markdown is a formatting syntax for text that can be read by humans and can be easily converted to HTML.

The syntax is pretty straightforward, and though it’s fairly deep, there’re a few major bits that I use all the time. Learn these two tricks and you’ll be 80% of the way to never having to re-invent your note-taking structure again:

The Two Main Tricks

Headings

At bare minimum, most documents have structure and content. To delineate the two, you’ll need some notion of a header. In a newspaper, examples of what HTML calls “headers” might be Headlines (“MEN WALK ON MOON”) and Subheadlines (“Astronauts Land on Plain; Collect Rocks, Plant Flag”).

Markdown has a few ways to describe headers, but I prefer “hash marks” or octothorpes. One hash for an H1, two hashes for an H2, etc.

# MEN WALK ON MOON

## Astronauts Land on Plain; Collect Rocks, Plant Flag

In HTML we might describe the top-level headline as an “H1”, the subhead as an “H2”, and we can go on from there, e.g. an “H3” (“Voice from Moon: Eagle Has Landed” and “A Powdery Surface is Closely Exposed”).

I find a use for headings on almost every document: certainly to title them, and occasionally to subtitle them. Any text-editor that is aware of markdown syntax can usually give an outline view with a single keystroke, which is very useful when editing and structuring thoughts.

View outlines with a keystroke in many text editors.

Lists

HTML has a menagerie of lists: ordered lists, unordered lists, definition lists…the list goes on. (Actually, that’s about the end of it). Markdown lists are pretty intuitive, and (probably because I’m often recording a meeting or making to-do lists) I find myself using them all the time.

To make an unordered list in Markdown, prepend every list item with a hyphen.
To make an ordered list in Markdown, which I do far less frequently, prepend every list item with a number.

Paragraphs

Ok, I lied, there’re three basic things. Here’s the last one. HTML has a paragraph tag, but in Markdown, to write a paragraph…you just type.

That’s it. Easy, right? This is why Markdown is so powerful: you really don’t have to remember much, but adopting a default convention means there’s one less thing to think about.

Extra Credit:

Headers and Lists will get you 80% of the way to making your notes understandable, but there’re a number of other fairly common markups I often apply to text.

• Emphases: surround text with * single asterisks * to make them italic, or ** double asterisks ** to make them bold.
• Citations: use an > angle bracket when you quote text:

Houston, Monday, July 21—Men have landed and walked on the moon. Two Americans, astronauts of Apollo 11, steered their fragile four-legged lunar module safely and smoothly to the historic landing yesterday at 4:17:40 P.M., Eastern daylight time. (The New York Times)

• Links: Surround the [link text] with brackets, and then follow with the link reference in (parentheses), e.g. [All the news that's fit to print](http://nytimes.com). There’re actually a few smart ways to do this; it’s worth digging in and investigating.
• Self-Linked URLs: if you’re linking to a URL, you can just put it in <angle-brackets>, e.g. <http://nytimes.com>
• Images: a bang, alt text in brackets, and then the path to the file, e.g. ![Man walks on Moon](moon.gif). This is actually something I do fairly rarely, and only in the final stages of writing and editing, mostly because thinking about code paths and where I’m storing the image usually gets in the way of recording or writing.
• Code blocks: put code blocks inside `backticks` (or indent with four spaces).

There’s a lot more syntax to dig into; find it at http://daringfireball.net/projects/markdown/syntax.

Why Markdown?

Convention over configuration might be the biggest win in choosing Markdown as a default. There’s little need to pick a new structure every time you take notes. Another big benefit of Markdown is that it works in plaintext, which means its future proof. When Microsoft Word Home Office Supreme 2016 breaks all your old .doc files, plaintext will still be alive and kicking. In fact, you can use Markdown for handwritten documents; I use it all the time to take notes on index cards. There’s another benefit: when I need to transcribe those Markdown index cards, I don’t need to guess whether I was trying to write in bold or whether my pen was leaking. Better yet, transcription becomes incredibly easy: I can transcribe without processing or editing on the first pass, and then review my work, process, edit, and do all sorts of other writerly things. This doesn’t sound that impressive, but I’ve found it to be a huge time-saver.

Hacks

In addition to the straightforward benefits of using Markdown as a default, I’ve also evolved a number of hacks:

• Use hyphens for lists, asterisks for todos: because Markdown supports a few different bullet characters, I’ve started to assign them semantic meaning. Being able to quickly scan a document and see what I need to follow up on is pretty great.
• Markdown is platform independent! I use it for notes on index cards. This is a great social hack. I can look you in the eye while we chat and write on cards or in a notebook; try doing that on a phone or tablet.
• I’ve been experimenting with photo capture: scanning batches of cards into a card-friendly scanner (I’m using a Neat scanner these days; it’s ok), then pushing them to Dropbox (it syncs to my phone!) and I’m starting to experiment with Evernote in order to group cards (“Blog Ideas”, “To-dos”), though I’m pretty frightened by the proprietary Evernote card format.
• Translating notes (e.g. getting a team together to capture an experience report of a project) into presentation decks is really streamlined if you write in Markdown and then move to Markdown-based presentation tools like MDpress, Showoff, or Keydown.

So that’s the How and Why of my Markdown habits. Do you use Markdown? Do you have a system for notes? Let’s hear about it in the comments!

About the Author

Biography