Reading and Writing just got easier with Markdown

Leave a reply

I need to quickly take notes and share them as part of my job. It may be keeping a log during meetings, recording field notes during an observation session, or just doing preliminary notes for a web page I’m posting. However, a lot of the existing tools on computers have limitations.

  • Plain text is easy to write and generally easy to read, but there’s a lack of formatting. You can’t identify headings, create tables, insert images, or easily create hyperlinks. You can keep that information using some kind of markup language…. like HTML.
  • HTML is standard. It’s all over the place, you can format your pages nicely, and it does a reasonably good job at separating information from presentation, especially if you stick with the vanilla tags. Everyone can view HTML on their browser as well, so it’s very potable. Unfortunately, HTML is also really verbose and difficult to write. You can’t easily add linebreaks or headings. Miss a close tag and you’re toast. You have to type a LOT. You can ease this by using a WYSIWYG editor, but then your HTML markup becomes very ugly, and you’re committed to using that editor.
  • LaTeX is also very flexible but is mostly limited to PDF output (yes, you can output to HTML, but that requires a non-trivial amount of commitment to installation and setup).
  • Microsoft Word is easy to use, but is not portable to systems without Word. It exports to HTML but also has reasonably ugly HTML output. It also takes a really long time to launch and is difficult to check into a version control system.

So what is the solution? Well, I’ve discovered Markdown a few months ago, which is a lightweight markup language that is readable as plain text, but allows easy conversion to outputs like HTML. So what this means is that you can write your documents in a plain text editor, read them in a plain text editor, but also convert them easily into a web-viewable format. I’m beginning to take notes and make initial drafts of documents in Markdown because you can easily go from Markdown to almost anything else by either copy-and-pasting it, or by converting it to your target output format.

On Mac OS X, I use a command-line tool called MultiMarkdown by Fletcher Penny which is easily installable if you have Homebrew (http://mxcl.github.com/homebrew/). Then, you can either convert your documents using the command line, or use one of many text editors set up to compile your plain text into something else, like HTML.

I personally use the TextMate bundle that’s supplied by the author of MultiMarkdown. I can easily output my text file as HTML with a keyboard command, and then I can move that onto a website or similar if needed. Just today, I set up TextMate to write a timestamp when I press “ll<tab>” (that’s two lowercase letter Ls followed by a tab) so that I can easily take notes during a user study. Now, I don’t have to watch the time and try to write it in. And, since it’s in Markdown, the time shows up as bold text underneath some nice headers. If I want, I can copy and paste my original notes into Excel, post them online, or just look at them in the plain text editor without seeing all of the ugly HTML associated with it.

I’m not sure what the Windows equivalent is, but there are a lot of Markdown text editors out there and even Javascript client-side applications that allow you to write Markdown and show you a real-time preview of the Markdown in HTML! That is pretty nifty.

There are a lot of Markdown tutorials on the web, but here’s a brief command reference just to emphasize its simplicity.

Writing Headings

# This is a Level 1 heading.

## This is a Level 2 heading.

### This is a Level 3 heading. 

You can also Underline your headings.
===============================

Creating lists

* List item
* List item
    * Nested List Item
1. Numbered item
2. Numbered item

Links

Here is some [text of the link](http://example.com "Example")

You could also use reference-style [labels][1].

[1]: http://example.com "Example"

Images

![alt text](/path/to/image.jpg "Title")

Code spans

This is a Unix command: `find . -type d -exec chmod 755 {} \;`

You can also include larger code blocks by indenting code with 4 spaces or 1 tab.

Bold/Italics

**Bold text** __Also bold text__ *Italic text* _Also Italic text_

MultiMarkdown also has syntax for tables and equations that I haven’t yet had a need for (and therefore haven’t learned), but I suspect that could come in handy as well.

In any case, I am feeling already that Markdown is going to make my life easier because it’s lightweight, you can write and read it anywhere, and it is easily transformed to useful output formats. I like to keep my thinking about formatting separate from content, and this enables me to do so in a lightweight way. While LaTeX is nice for print documents and Word is good for collaborating with others, having a simple system for quick notes is really convenient as well.

Leave a comment