The Hiltmon

On walkabout in life and technology

The Markdown Mindset

Over the last year, I have moved all my non-code writing to Markdown format. I don’t even have Microsoft Word installed on my laptop anymore. Here’s why:

It’s just plain text

I have been using personal computers of some kind or another since 1981 (my first being a Sinclair ZX81). One of the problems I have faced time and time again as I have jumped to newer computers, different operating systems, and different tools is that I have been unable to convert my documents from the old to the new. In many cases, I could have done it, but now it’s too late. Nothing these days reads some of the old proprietary file formats I still have. Which means the data is probably lost.

Markdown is text, just plain text. Its the one format that has not changed over all the years. Oh sure, we’ve gone from a 7-bit ascii code to UTF-8, but all text editors happily handle the old text formats. And when they stop, a small C program will fix it.

Plain text, and therefore Markdown, are as future-proof as you can get in computing.

It’s all about the writing

The big problem with many tools used for writing (ok, mostly word processors) is that there are too many things you could be doing instead of writing. You could be playing with fonts or styles, futzing for ages trying to make the document look right, work the number styles, headers and footers and resizing the margining.

Or you could be writing.

With Markdown, the font, style, margin and other stuff all comes later. All you have is the text, the basic structure and the options for bold, italic, lists and tables. That’s it! There’s nothing else, so the writer is encouraged to write.

It’s also easy to read. As I write, I often go back and read what I just wrote, to check flow, spelling, grammar and content. Since the markup in Markdown is unobtrusive, it’s easy to read. And since the markup does not change the style, you focus on the content instead.

It’s tool-agnostic

Plain text, and therefore Markdown, is tool-agnostic. One can edit it in a myriad of tools. On a myriad of platforms. In whatever way the writer likes.

What I actually do is to use different tools to help me get into the mindset for what I am doing in Markdown. When I am blogging or writing short articles, I’m writing Markdown in Byword, previewing in Marked. When I am doing a manual or a bunch of related documents, I work with Markdown in Scrivener. When I am taking notes, logging my programming work or creating release notes, I use Markdown in BBEdit. Programming readme files, Markdown in TextMate. I could use any of these tools for any of these tasks if I choose, and I can move the files from one to another without any loss of fidelity.

It just gets better with sharing. When I share these files, those shared with can use any tool of their choice to modify the document. They don’t have to have or use the same stuff as I do. As long as it stays a plain text Markdown document, they can use what they want and I can still merge in their changes. They may want to use vim or gedit on linux, Notepad or UltraEdit on Windows or pretty much anything on the Mac. But the file remains the same across all.

It transforms into any format

The initial use of Markdown was to create HTML content. These days, with tools like Marked and Scrivener, and the MultiMarkdown scripts, the Markdown plain text can become PDF’s, Word Documents, RTF Documents, even Latex files (See MultiMarkdown Features) without any effort. One simple source format for many delivery formats.

Which also makes each file reusable. The same source file can be used in the web site knowledge base, in the manual and in an email.

And a whole bunch more

Being plain text is great.

  • Plain text is searchable, some of the proprietary formats are not.
  • Plain text works on all platforms, not all formats can be read on them.
  • Plain text files are small. Plain text is fast to read and write to disk. It makes for small mail attachments.

Daily uses of Markdown

Here are some of the things I do almost every day in Markdown:

  • Update my DayOne journal in Markdown
  • Write my software development and project notes in Markdown using BBEdit
  • Write a blog post in Markdown using Byword
  • Add to the KifuApp Knowledgebase using Scrivener in Markdown
  • Maintain the documentation for my projects in Markdown in TextMate

And one thing I never expected to do in Markdown:

  • Log all messages from my “Import to Kifu” process in Markdown, so that the import log can be sent prettily formatted to clients

Getting started in Markdown

It’s easy. Start with your favorite text editor next time you need to write something instead of using whatever you usually use. Learn the markup as you go and need things. That’s all there is to it.

Just write.

You’ll be surprised how productive you will be.

Markdown references

Follow the author as @hiltmon on Twitter or @hiltmon on App.Net.