Markdown for Muggles

This post goes out to all the creative critters toiling in the depths of the information web-way known as the Internet. Yes, I’m talking to you aspiring writers, critics, bloggers and word smiths. Talk to me about your tool of the trade. What do you use to do your craft? What tool to you employ to record your thoughts in the form of character strings written into computer memory? How do you put your minds toil into silicone repository trapped inside your external thinking box people call a computer, but which long ago became a part of your brain?

You use Microsoft Word, don’t you? Not only that, you hate the damn thing.

How do I know? Well, this is a two part question. How do I know you use Microsoft Word? Because that’s what everyone uses. It’s what everyone knows how to use. And not because it is a good tool for the task. Microsoft word’s popularity is in large part due to memetic inception. I’m not talking about an internet meme in the form of an image with macro text. I’m talking about meme as a concept that predates the internet – a brain bug, a virally spreading datum that infects minds and takes hold. Every marketing specialist out there is currently working to create one of these – and if they are not, or don’t know about memes then they are simply horrible at their jobs.

Let me give you an example of a marketing meme: have you heard that Macs are better for graphic design? I’m sure you did. Can you explain to me how they are better? I’m sure you can’t. No one can. Hell, I own both Mac and PC machines and I’m fairly interested in how they work, how they differ and how they can be tweaked, and I could not tell you how the hell my MacBook Pro would be any better at running Photoshop than my Windows PC. There is just no empirical difference in how these machines handle visual editing software – mac has neither a hardware edge, nor does it have exclusive software that could make it a better platform. They are just about the same. But people still assume… No, they know – they are convinced – that Macs are better at graphics. It is a meme. It is a brain bug. It is a thing that people repeat, without understanding and reinforce via repetition.

Microsoft has launched a similar meme at some point in the past. They somehow convinced everyone that you can’t write anything without Microsoft word. Students need it for homeworks and creative people need it to write their stuff. But, just like the mac fable, this is also not true. Just think about it. How much of the text you consume on a daily basis is in Microsoft Word format? Everything you read on the web is HTML – a variety of plain text. Most documents you download from the web are in PDF. If you publish anything for the web, you know that most bloging or content management systems actually dislike word, and prefer you to type into (or paste into) a plain text input box.

As a internet society, as an electronic mind share we are collectively moving away from Word as the main data carrier format. And yet, the meme persists. A lot of people still assume that you need Word. That storing plain text files on your hard drive is somehow not kosher, that it is somehow not correct. So even if their notes contain no formatting, and nothing but plain text, they still wrap them in a proprietary .DOCX package, just to be safe. Why? Because that’s what you do. That’s what everyone does. That’s the way. There is no reason behind it. No logic. No deeper understanding. You just word it up, because you do.

How do I know you hate it? Well, everyone does. There is not a single person in the world that loves Microsoft Office. There are people out there that tolerate it – who are willing to put up with it and forgive it’s flaws. But they don’t love it. There is not a single person in this universe who loves Word the way some folks out there love Vim or Emacs. All you have to do to verify this is to hang out around forums and communities devoted to these particular programs. Just not the tone of most of the posts. In Microsoft Office forums the general tone is more or less:

“Guys, I need help to make this POS software do what I need it to do before I chuck this computer out the window.”

The general tone of most posts on Vim/Emacs forum is more along the lines of:

“OMG, look what I just figured out! This is like the best thing ever! I’ll be so productive with this. This editor rules!”

Attitude towards Word range between seething hate, and begrudging tolerance. There is no love there though. Not by a long shot. If you think you love word, you are mistaken. Do you love it as much as you would love a favorite pet? Do you truly enjoy working in it? Has it never failed you, never frustrated you and never let you down? Cause that’s my personal relationship with Vim – it’s lime my own personal Rick Astley. I know it’s never gonna let me down.

So now that we established that you hate your main work tool, let’s talk about a better way. Yes, there is a better way. There is a light at the end of the tunnel. I mentioned this in my self publishing article: ditch Word, learn Markdown.

Markdown is astonishingly simple to learn. I could teach it to you in five minutes. Hell, I will teach it to you now. Ready?

This is a heading

This is how you **bold** and *italicize* text.

This is how you make lists:

	- Item the first
	- Item the second
		1. Enumerated item
		1. Another item
	- Item the third

Smaller heading

Quoting is easy:

> To be or not to be...

And here is how you [make links][1]. You put all the links at the end.


Woha, you just learned Markdown faster than Keanu Reves learned Kung-Fu in that one movie. There is a little bit more to it, but not much. The rules are so simple, and so intuitive you pretty much can’t mess it up.

Next, you ditch that bulky, sluggish and finicky old MS Word and pick a plain text editor you like. You are writer and not a geek, so I will not push Vim or Emacs on you. There is this new fad amongst your people though – writers, creatives and the like: distraction free writing environments. There are dozens full screen editors out there that can deliver a powerful dose of creative zen to your cranium. Just to name a few:

  1. Dark Room
  2. Write Monkey
  3. Crea Writer

Or you could go for something more traditional – like for example Sublime Text. At the end of the day, it doesn’t matter. Once you wean yourself of MS Word you will discover a new found freedom: your writing and your data will no longer depend on one editor from a single software vendor. Your writing will be liberated from the oppressive tyranny of Microsoft. This means you will be able to experiment with a lot of different editors, and pick your favorite one. Or change them every other day. Or have an editor rotation. Or whatever. Freedom is great, you should try it.

You will now save your documents as .txt or .mkd or .markdown – it doesn’t really matter. They will be neat, human readable and perfectly suitable for conversion to other formats. By default markdown was designed to be converted to HTML, but fear not – there are tools that let you turn your files into word documents of PDF files just as easily. You basically need just one tool:

Grab it, install it. I’ll wait.

What is that? Why are you crying? Stop being a little bitch. I said I will hook you up, what is the problem now?

“But Luke, this panda thing is all command line and shit! I thought it will have a GUI. Command line is scary, ugly and it smells. I’m gonna go back to Word now. This is stupid!”

Fine, go back to Word which you hate. Crawl back to the thing that hurt you and beg it to take you back. Command line scares you that much? Fine. I will make it go away. But we are keeping Pandoc.

Pandoc is a really great tool, sadly it’s not what I would call User Friendly. It was made by geeks and for geeks so you have to excuse the lack of UI. We generally don’t have any use for such thing. But I know that in the land of the End User, GUI is king. So I will make you one:

Download that zip file, extract it and double click on the .reg file inside. In case you are interested how it works, here is the contents of that file:

Windows Registry Editor Version 5.00

@="\"C:\\Program Files (x86)\\Pandoc\\bin\\pandoc.exe\" -s -S \"%1\" -o \"%1.docx\""

@="\"C:\\Program Files (x86)\\Pandoc\\bin\\pandoc.exe\" \"%1\" -o \"%1.pdf\""

If you can’t read Windows Registry merge files, here is what it will do: it will add two new items to your right click context menu. From now on, when you right click on a file, you will see something like this:

Markdown Menus

Markdown Menus

These buttons do exactly what you suspect they will do:

  • mkd2doc will convert the file to a Word doc
  • mkd2pdf will convert the file to a PDF

The new file will be placed in the same directory like this:

Markdown to Doc

Markdown to Doc

The registry script assumes two things:

  1. That you have PanDoc installed
  2. That you are running a 64 bit Vista or Win7

Other than that, it should work. I chose DOC and PDF because those are the two most popular, most requested file formats that your editor and/or publisher may want to see your files in. PanDoc can convert Markdown to dozens of other formats but I did not want to clutter your context menu with too much garbage you will never use. I figured Doc and PDF were safe choices.

Now, dear creative soul you should be armed with enough knowledge and enough software tools to wean yourself away from Word. I highly recommend you try it. Download Pandoc, install my registry script and join the ranks of plain text enthusiasts. Mark it down like a pro.

This entry was posted in Uncategorized. Bookmark the permalink.

19 Responses to Markdown for Muggles

  1. Alphast UNITED KINGDOM Mozilla Firefox Windows Terminalist says:

    I write loads of stuff, and I am not a true geek, so I wouldn’t be able to handle Vim or Emacs, even if my life depended on it. Believe me, I tried, I am that dumb. However, I remember a time when there was no real WYSIWYG text editor (on my Atari STF computer, for instance). So I am used to markup systems. I endured Word for quite a while, first as a student, then a young professional. As an analyst (not the software type, the actual analyst guy who analyzes economic intelligence, writes reports and the like), I soon became convinced that Word was not the way to go. I tried different things for a while (including peppering my PC with text notes in .txt format). I wrote a lot of things in HTML for various websites. I participated in forums where various markup systems were used. So it is almost naturally that I abandoned Word.

    Nowadays, I write pretty much everything in browsers, using plain text or simple markup. Everything I write goes into some kind of Wiki (which uses markup), blogs (which use markup), PhP based forums (which use markup) and basic text files. The only thing I still use Word for are my CV (it is less clicks to update a bullet point every second year or so than update a text file and then export it to Word) and my monthly report to my boss (because he wants a word document).

    Reply  |  Quote
  2. Alphast UNITED KINGDOM Mozilla Firefox Windows Terminalist says:

    By the way, the fact that your Markdown menu is only for Vista 64 bits makes me a sad panda… ;)

    Reply  |  Quote
  3. Greg UNITED STATES Netscape Navigator Mac OS says:

    Okay, but here’s what would convince me to abandon Word: can you write in markdown a reasonably complicated document (say, with enumerated lists several layers deep, section headings, and citations to the sections) and then use pandoc to flawlessly conver that document to LaTex for output quality and to Word for sharing with others?

    Reply  |  Quote
  4. vukodlak SERBIA AND MONTENEGRO Google Chrome Mac OS says:

    For personal, creative writing, I could see how this might work. *If* I had the time and patience to learn… However, I can’t imagine for a second that I could ditch Word for work-related items. Apart from the fact that everyone else at the uni has word, and that we collaborate on documents all the time, our students are required to submit their work as a doc file (NB not .docx) and I am required to leave comments using word’s track changes feature.

    So, I could learn to use a text editor for my personal writing but would have to go back to word for work writing. I think you can see where the stumbling block might be…

    Reply  |  Quote
  5. Morghan UNITED STATES Safari Linux says:

    @ vukodlak:
    I feel your pain on the collaboration. I have the same problem at uni. For everything I don’t need to trade back and forth I use LyX, but people are so stuck on Microsoft they won’t even use Google Docs since the school recommended the MS cloud collaboration which I can’t recall the name of.

    I’ve given up trying to use anything else for school, and Excel, Powerpoint, etc. are just as ingrained in their psyche.

    Reply  |  Quote
  6. Luke Maciak UNITED STATES Mozilla Firefox Windows Terminalist says:

    @ Alphast:

    Here is the XP version:

    Windows Registry Editor Version 5.00
    @="\"C:\\Program Files\\Pandoc\\bin\\pandoc.exe\" -s -S \"%1\" -o \"%1.docx\""
    @="\"C:\\Program Files\\Pandoc\\bin\\pandoc.exe\" \"%1\" -o \"%1.pdf\""

    Didn’t have XP handy to test, and I assumed Vista and 7 work the same way. Laziness. :P

    Greg wrote:

    can you write in markdown a reasonably complicated document (say, with enumerated lists several layers deep, section headings

    Yes, nested lists are easy – it’s all about indentation. Quite easy to maintain. Lists in word are a nightmare.

    Greg wrote:

    and citations to the sections

    No, markdown has no support for citations. For academic work I’d recommend Lyx. WYSIWIM editor, which generates LaTex and gives you full access to the underlying source. Lets you generate fancy bibtext bibliographies and what not. I might need to revisit it now that they released version 2.0. :)

    @ vukodlak:

    Pandoc can convert Markdown documents to .docx files. Seems to work pretty well. But yeah, I know what you mean. I do have to deal with some MS Office at work too because of macro driven documents. My favorites are “hey, fill out this questionnaire in Excel” type things. Ugh…

    I subvert this by writing documentation as plain text whenever I can. Most of the time people can’t say shit because my files are nicely formatted, readable, well written and well organized and etc. :P

    @ Morghan:

    That sucks. Reminds me of my own time at the uni when I would be like “guys, I set up an SVN repository (this was before git existed mind you) so we can use it for our programming project…” and my group mates were like “LOL, what is ESPN repository?” Fun times.

    What major are you if you don’t mind me asking?

    Reply  |  Quote
  7. road UNITED STATES Google Chrome Windows says:

    Microsoft Word and Excel are both essential for my work, and I think they’re both solid pieces of software. I still use the versions from Office 2003, because I think they’ve been getting worse since then… but I can’t quite imagine life without them. Things I use Word for that I haven’t seen good alternatives to:

    # scientific citation management using plugin software like EndNote
    # Robust track-changes features. I don’t ever write anything alone, it usually has to pass through several rounds of revisions with multiple authors, and the track-changes features, while a bit clunky, do exactly what’s needed

    As for Excel, I just haven’t seen an alternative that comes close. Google spreadsheets is nice for collaborating/sharing, but it’s a toy compared to Excel.

    For what it’s worth, I do lots of coding and data-manipulation with emacs, perl, and R. I LOVE emacs and perl. I’m not afraid of the command line or incapable of using powerful tools. But there’s a time and a place for WYSIWYG, and I haven’t found better tools for collaborative writing of large, complex scientific documents. I wouldn’t want to write code in Word and I wouldn’t want to write my thesis in emacs.

    I think that’s why MSFT is still successful: they write business software that works, even though it’s sometimes ugly and kludgy. It might not be cool or new or attractive, but it meets the needs of professionals. The reason why a lot of the nice lightweight/open-source alternatives don’t do this is probably because writing software that plays nice with business environments and legacy plugins is really boring.

    Anyway, if you don’t need it don’t use it. But it has it’s place, IMHO, and it’s not just marketing.

    Reply  |  Quote
  8. Morghan Safari Linux says:

    @ Luke Maciak:

    Forestry, everyone I know thinks I’m nuts for not going in to computers, but I really couldn’t see myself stuck in an office showing people how Exchange *shudders* works for the fifth time that week.

    I’ve always liked computers, but not so much users or clueless managers. Still, not entierly giving them up professionally, there’s still remote sensing and GIS.

    Reply  |  Quote
  9. SheriffFatman UNITED KINGDOM Google Chrome Windows says:

    Hallelujah! This post has probably given me more joy than anything else on the Internet ever.

    Couple of nits:

    – pdflatex is a dependency for PDF output;

    – @Greg, @Luke: pandoc’s implementation of Markdown includes an extension for citations.

    Reply  |  Quote
  10. Hugo Paceli Google Chrome Windows says:

    I am actually quite used to writing on the Windows Notepad. But I think I’ll try this markdown thing. Thing is, I write mostly poems, and I do not use bold or italicized words on them. Perhaps I should.

    Reply  |  Quote
  11. ST/op DENMARK Google Chrome Windows Terminalist says:

    @ Greg:
    You may want to try reStructuredText or MultiMarkdown for more advanced markup, like footnotes, citations, etc.
    The reText editor has support for (basic) Markdown and reStructuredText.

    Reply  |  Quote
  12. Kris UNITED STATES Google Chrome Mac OS says:

    I’ve been considering MultiMarkdown for a large 400 page document but like @Greg I also have concerns with the numerous sections and chapters the document has. How are complex documents usually handled with markdown. What about ToCs?

    I was thinking maybe tracking revisions with a git repo?

    Reply  |  Quote
  13. Dirk Mozilla Firefox Ubuntu Linux says:

    @ST/op, @Kris:
    Pandoc can read several formats: Markdown, RST, Textile and subsets of HTML and
    LaTeX. It can write many more formats than it can read. Actually the .doc
    that it writes looks like stripped-down HTML but it seems that MS-Word is happy
    with it. In between sits what is called “native format”: everything goes
    input-native-output. More readers and writers get added every now and then.

    Pandoc’s Markdown has been extended so that almost anything that native format
    can accommodate can be represented in Pandoc-Markdown, but the way I test
    whether my favourite feature is present is to use the export-to-HTML option of
    Word (or whatever) shove that through Pandoc with HTML output, and compare the
    two HTML versions in my browser. In many cases the HTML output can also make
    an acceptable PDF, especially if you have installed wkhtmltopdf.

    But for really nice PDFs, whether via TeX or via HTML, you will need a style
    file (.sty for LaTeX, .css for HTML) that you have customized to your own

    Reply  |  Quote
  14. might be interesting for some here…
    i wrote me some small bash-script that displays markdown via html
    i use it to monitor output in one dtvm-pane, while i write with vim in another

    Reply  |  Quote
  15. hahaha so many nice things here (as usual). Scrivener is a good ‘un for bare bones wording. Although I just had a look at the latest version and there seem to be buttons up there(!). I’m a Mac person so I use Pages (it’s not great) for work/ Uni as it works well with Endnote. Totally agree with you on people sticking with Word (and everything else associated with that thing-i.e. Office) for no other reason but laziness.. So many other cool things I wanted to discuss (including stuff in the comments but it’s late now so I’m off).

    Reply  |  Quote
  16. sky_y JAPAN Google Chrome Mac OS says:

    Sorry for my dirty comment.
    Here is the link to my MarkdownMenu.
    GitHub: sky-y/MarkdownMenu

    Reply  |  Quote
  17. Elena UNITED KINGDOM Safari Mac OS says:

    Actually you don’t need to convert .md files into .doc format to be able to open it in Word. You can install a Writage plugin for MS Word and open and edit .md files as any other document.

    Also you could save any Word document which you receive from you colleague as Markdown file and continue to work with your favorite Markdown tool

    Reply  |  Quote
  18. Irwin UNITED STATES Mozilla Firefox Windows says:

    @ Elena: I installed Pandoc using its installer and installed the Writage plugin for Word. When I try to save a document as an MD file, writage complains that Pandoc is not installed. I have tried rebooting, moving pandoc.exe to another directory and installing a shortcut in the Start menu (Win 7).

    Is there some magic I am missing?

    Reply  |  Quote

Leave a Reply

Your email address will not be published. Required fields are marked *