The Pilcrow

Regenerative self-leadership and principles in productivity, life and business

An ode to markdown

If you don’t know markdown yet, I highly suggest you should learn it. It’s a small investment that can give a large payoff over time.

Origins of markdown

Originally the thought child of John Gruber, Markdown was created in 2004. He wanted to have an easy-to-read and easy-to-write plain text format that he easily could convert to HTML (or XHTML which was the HTML of the times).

He took inspiration of how people used to write in plain text emails. You know, back in the time before you could use bold and italics in emails people used _underscores_ and **asterisks** to emphasise words.

Markdown describes the structure of a piece of text while still being readable and understandable to humans. Unlike HTML, which is the language that web pages are written in. HTML describes the structure of a piece of text so web browsers, machines and various assistive technologies can make sense of it, but it’s hardly something easy to read. Or write for that matter.

It’s not a programmers fetish any more

Today, there are more benefits to writing in markdown than to prepare for writing and publishing on the web. It is no longer the nerdy programmer’s secret, but is spreading as its versatility becomes more and more known and appreciated.

Common rich text editors like Microsoft Word mix the text with hidden information about the formatting, looks and so on. That makes it more difficult to move text that started out in the word format to other places. You risk losing the formatting altogether if you copy and paste, and converting a word document to other formats is an error prone process.

Markdown on the other hand can easily be converted into a word document with formatting intact, but just as easily into a PDF or an epub for publishing as well. Writers of all flavours are joining the ranks of the markdown fans, simply because it lets them focus on the words alone and stop fiddling with looks and styles while writing.

Plain text and markdown is the ultimate portability. It’s easy to sync between devices and any program can open it and read it. It’s future proof, fast, takes up very little space and is easy to convert into beautiful documents or published in different media.

Support is spreading beyond text editors

If you have a website that runs on WordPress you might not know that the block editor recognises and supports some markdown, as a shortcut when you write. No need to click around in order to convert your current block from a paragraph to a heading, just start with the characters ## and it will automatically transform to the heading level of choice. Use ### for heading level 3, #### for heading level 4 etc. Or start with a dash (-) and the paragraph will be turned into a list block.

Current versions of WordPress can even handle pasting raw markdown straight into the editor and it will automatically turn into properly formatted text ready to publish.

Many web apps have added support for markdown. The popular forum software Discourse uses it for example. So if you are part of communities that has a standalone discussion forum, the probability is high that you can write markdown there. Trello also uses markdown to format the text on their cards. I can even use it in Todoist, which is my todo app of choice.

And not only on the web, more and more applications start to add support for it. If you participate in different chat applications, like Microsoft Teams or Slack, they support writing markdown too in your messages. You can even use markdown shortcuts in Whatsapp!

The good, the bad and the ugly

Now you know about the good things about markdown. It’s simple, easy to write once you’ve memorised it, and portable across platforms, time and publishing places.

The bad thing? The exact syntax can vary between applications.

Nobody agrees on the definite version

The different versions of markdown are called flavours. They exist simply because what Gruber initially outlined had some gaps in it, and it has been extended in different directions to support more features.

The basics are the same across all flavours, stuff like lists, headings, links, images and so on. But additional features differ. Two of the most common are:

Github Flavoured Markdown. Naturally used and developed by github, it enables you to create tables, add task lists with checkboxes, and code blocks where you can specify the language of the code to get syntax highlighting. These extensions became so popular that GFM is used in many places outside of github too.

Multimarkdown adds support for tables and fenced code blocks just like github. But also adds table of contents, footnotes and citations, subscipt and superscript, and math support among other things. Very useful for writers of longer manuscripts, or academic writing and research.

But there are way more than I can list here. Commonmark has gathered a list of no less than 36 different flavours of markdown(!).

The good news is that the differences are very small and once you learn the basics you will seldom need to worry about the exact markdown engine your current application uses. This will only be important if you need to take advantage of any of the more advanced features, like footnotes or tables.

Dilemma: collaborative writing

I love markdown. I’m so used to it that it is my default way of writing. Even in places like Evernote, who don’t support markdown at all but offers WYSIWYG formatting tools, I still write my text markdown-style.

The only place where I’ve been forced away from it is when working collaboratively together with others. I’ve seen articles who describe using markdown and source code tools like git between collaborators, but that is reserved for tech savvy people.

For the majority, few things beat the simplicity of Google Docs. Alas, Google Docs is like regressing to Microsoft Word – but online. All the drawbacks of word docs apply to Google Docs as well.

I recently came across StackEdit which could be my solution to this problem. It would support me to write in markdown and then sync to Google Drive where I could invite collaborators just like normal. I’m going to check it out the next time I need to work together with someone on a document.

Where to start

Depending on your platform, there are a plethora of markdown text editors to go around. A markdown editor often has a preview pane where you can see a pretty rendered document based on the text you write, and adds keyboard shortcuts for adding markup and so on.

These days, there are complete note-taking apps using markdown as it base. Apps like Ulysses, Bear and Obsidian are designed for keeping all of your notes and thoughts in markdown. But you don’t have to make that jump from the start. You can just dip your toes in the water first.

Pick an editor that works with your gadget of choice:

Start writing in plain text and try it out. Here’s a handy cheat sheet with the syntax. It’s really easy and not difficult at all.

If you save your text document in a folder that is synced to a cloud provider – Dropbox, iCloud, Google Drive, One Drive etc – you can open and read the file on your phone too.

Once you’ve gotten over the learning curve and get used to writing in markdown, you have just upgraded your writing superpowers a bit.

I’m curious to see what you will make of it.

Next Post

Previous Post

© 2021 The Pilcrow

Theme by Anders Norén