Learn Markdown: The Writing Tool for Software Developers

If you’re a software engineer, you’ve probably spent a lot of time refining your environment to boost your productivity. You’ve got your favorite IDE. You’ve got your favorite debugger. You’ve got your favorite performance monitoring tool. But what about your tool for writing documentation, manuals, and reports? After all, writing does take a non-trivial amount of your time, doesn’t it? Indeed, it’s time to get serious about your writing tool.

And let’s remember that you are technical, so WYSIWYG editors may or may not be the best option for you. You don’t necessarily want (or even like!) navigating menus, toolbars, and ribbons to format your text.

So what if, instead, you could easily add all of your formatting styles right into the text as simple inline syntax to yield fully formatted text?

Well, in fact, you can. That’s Markdown and that’s what this tutorial is all about.

When More is Less…

Word processing software is written to satisfy an extremely wide array of users and use cases and, as such, needs to provide all sorts of functionality. But clearly, only a small subset of that functionality is likely to be relevant to each individual user. And for most users, who simply want to author a document (and don’t need to design a marketing brochure or poster), a very small subset of the many, many options available are relevant.

In fact, Microsoft clearly realized this a few years ago when they redesigned the user interface of Microsoft Word into distinct functional groupings that they called “ribbons”. Yet interestingly, most users will tell you that they found the new interface more confusing and difficult to navigate than its predecessor.

Indeed, more can sometimes be less when it comes to ease of use and productivity.

… and When Less is More

Face it, you’re a software engineer, not a graphic designer. You just want to write that manual, or technical document, or report, and be done with it. You’ll be very happy and content with some basic formatting capabilities like headings, bulleted or numbered lists, and code blocks. And, oh yeah, some font formatting (bold, italics, etc.) would be helpful too. That’s about it. (And man, if you could even just do it in vi, that would really be awesome!)

Enter Markdown.

What is Markdown?

John Gruber (with substantial contributions from from technical guru and Internet activist Aaron Swartz) created the Markdown language in 2004 with the goal of enabling people “to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid XHTML (or HTML)”.

Markdown was designed to be readable as-is, without looking like it has been marked up with tags or formatting instructions (unlike text formatted with a markup language like RTF or HTML which can be both hard to author and hard to read in its raw format).

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, that can then be converted into structurally valid HTML. So, to be entirely precise, Markdown is really two things:

1. A plain text formatting syntax
2. A software tool (the first version of which was written in Perl) that converts the plain text formatting into HTML.

Markdown incorporates a handful of simple, fairly intuitive, and easy-to-use syntax conventions. Especially for you as a software engineer – who is not put off by needing to learn and use these basic syntax conventions – Markdown can indeed be the path of least resistance between what you want to write and getting it written.

Learn Markdown: Getting Started

Markdown is easy to learn. Super easy. You can learn the basics in five minutes and it will quickly become second nature. And – just like the relationship between CSS and CSS preprocessors – you can use as little or as much as you like.

If you’re used to any kind of plain text writing conventions, then you might already be familiar with some markdown conventions, such as numbers or dashes at the beginning of a sentence to create a list, asterisks around a word for emphasis, and so on. So, for instance, if you want to display something in italics, simply wrap it in asterisks like *this* (as opposed to clunkier HTML syntax like <span style="font-style:italic;">this</span>).

Similarly, you can specify an H1 heading by simply adding a ‘#’ prefix to your line (e.g., # Section Heading, rather than <h1>Section Heading</h1>).

Another great use for learning Markdown, especially for us software engineers, is to use it for documentation on source code repositories. Most repos include a README.md file (.md is the standard extension for a Markdown file). Github, for instance, has its own “Github-flavored Markdown”, which adds additional functionality specifically for development documentation. This can certainly save time over having to write this documentation in HTML.

As a simple example, let’s say you wanted to include the following snippet in your documentation:

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Initiating Plugins</h2>

Initiate pluginName on your container using jQuery as follows:

$(function() { $('#container').pluginName(); }); Using our container’s ID, we can initiate pluginName with the jQuery method .pluginName().

Here’s a comparison of how this would be done in HTML vs. Markdown:

For further help getting started, there are many Markdown tutorials online to help get you up-to-speed including a Markdown overview by John Gruber (Markdown’s creator) as well as an online Markdown tutorial.

Markdown Parsers and Tools

Once you’ve written your article in Markdown, you’ll need a an app to parse the the syntax into HTML. There are a few great ones that are free including:

• StackEdit - browser-based Markdown editor that has a few sync options with popular services like Google Drive and Dropbox
• Online Kramdown Editor - another browser-based Markdown editor with an extremely simple interface
• Mou - the best Mac-based Markdown writer I’ve come across as a geekier option for developers; tons of features and free (while in beta) [this is what I used to write this article]
• MarkdownPad - great Markdown editor for Windows
• Texts - a nice cross-platform (Mac and Windows) editor; exports to multiple formats such as PDF, .doc and ePub

Some major platforms have already adopted (or at least allowed) Markdown use in their editors for those who wish to use it. With others, such as WordPress, Evernote, and Google Docs, native support (at the time of writing this article) is not yet baked in, but custom solutions have been introduced by third parties. These include:

• Popular new blogging platform Ghost, in pursuit of streamlining online writing, uses Markdown for its content editor.
• For WordPress, the Jetpack plugin now officially supports Markdown, which you can enable under Settings > Discussion if you use the plugin. Or you could use a plugin like WP-Markdown which will convert your post markdown content to HTML, and back to Markdown when you need to edit it.
• For Evernote, some Markdown apps such as a the online editor Markable or the Mac editor Byword allow export and publishing directly to notes. Or if you prefer to use the Evernote web app directly, you can use a browser extension called Markdown Here which converts a selected note written into Markdown to formatted text with a click of the toolbar button.
• Google Docs doesn’t natively support Markdown yet, but a few editors (such as StackEdit) will export/sync directly with Drive.

The Downsides

Of course, with great simplicity comes limitations. As I’ve already explained, Markdown was not written for complex word processing tasks requiring advanced formatting features. If that’s what you need, Markdown is not the right tool.

But for developers who need to write a user manual or technical documentation or a technical report, Markdown provides a near-perfect balance between simplicity and the features that you need.

Perhaps the biggest drawback – especially for us engineers who are change control junkies – is the inability to work collaboratively in Markdown and to track changes (one notable exception to this, though, is the StackEdit plugin for Google Docs). And of course, with a minimal amount of effort, one can simply collaborate on a Markdown doc via a git repository and thereby get all the change tracking and collaboration that one typically needs.

Conclusion

So is learning Markdown for everyone? Of course not. No one tool ever is.

But if you’re a software engineer, it could very well be precisely the writing tool you’ve been looking for. So if you haven’t given it a try yet, you really should take it for a spin.