What Is Markdown Formatting?

The simple language used all over the web

Markdown Text (at Right) Results in Formatted Output (at Left)

Markdown is a way to quickly and easily write up content for the Internet, while at the same time avoiding all the messy HTML code browsers require. You can also markdown formatting to create other documents. But how does it work, and how do you start using it?

Why Use Markdown Formatting?

The main benefit of Markdown is its a plain text format, meaning you can use just about any program to write your document, from simple text editors like Windows Notepad and TextEdit on macOS, to any of a number of options on Linux. Mobile operating systems like Android and iOS also have plenty of free apps that will handle plain text as well.

It also means you can take the file you created on any one of those apps and use it anywhere else without much issue. You won't need to worry about formatting incompatibilities, because the "formats" you apply to your writing are just plain text themselves. Plain text files are also small compared to most formats like word processors, so that space on your phone or thumb drive will go a lot further.

The above applies to a number of plain text "lightweight markup languages," but Markdown in particular also has a number of advantages, including:

  • Simplicity: The core of Markdown is very simplistic by nature, and doesn't have a lot of syntax to remember.
  • Features: If you do need some more advanced features (footnotes, for example), there are extended versions of it like GitHub-flavored Markdown and Multi-Markdown.
  • Platform support: It's very well supported in applications such as text editors (which will show you a live preview of the formatted text, for example) and content management systems, where you can type Markdown directly into e.g. blog posts.

What Is Markdown?

Markdown is a play on the term "markup," referring specifically to HTML. A "markup" language uses text codes to indicate divisions of content, visual decorations, and embedded objects like images. For example, even an extremely simple web page with a header, an area with a sentence of text, and an image becomes extremely burdensome to write by hand:

Raw HTML Text Displayed in a Plain Text Editor

This represents a long block of code to literally present a sentence to the user, and not in a very attractive way. But it's the HTML tags like <div>, <strong>, and <img> that really kill your productivity. Not only do they encompass the majority of the text, if you happened to type one of them wrong, your page won't display correctly.

So rather than applying "markup" to your text, you should instead apply the opposite: markdown. Markdown is an attempt to use something similar to markup tags, but in a much more compact and writer-friendly way. As an example, the above represented in Markdown would look like this:

A Simple Web Page Written in Markdown.

See how much cleaner it is? One of the principles of Markdown is to be "human readable in source form." And looking at the above, it's pretty clear what's what. The hash mark at the beginning designates a heading, and the asterisks mean emphasis (specifically bold). This is something many people do in text messaging anyway, so it's easy to interpret. Even the image, which requires something a little more technical, is easier to understand than the HTML.

A Quick Markdown Formatting Primer

When writing for the web, you can get away with understanding just a few main bits of Markdown:

With a Small Subset of Markdown, You Can Still Be Very Efficient.
  • Headings: As mentioned above, starting a line with a hash mark and a space indicates a heading. One hash means a "Level 1" heading, two hashes a "Level 2," and so forth. Markdown supports up to five levels of headings.
  • Bold: Surround some text with **double asterisks** to make it bold.
  • Italics: Surround some text with *single asterisks* to make it italic.
  • Lists: Lists are easy. Use dashes or asterisks plus a space for bulleted lists, otherwise use numbers with a period and a space. You don't even need to order your numbers correctly, Markdown will take care of it on conversion.
  • Links: these use the formula: [link address](the text to be linked). The hardest part is remembering which one gets which type of brackets.
  • Images: The trickiest of the bunch, images start with an exclamation mark, then hold the image's alt-text in parentheses, with a path to the image in square brackets bringing up the rear. You can see this in the Markdown sample in the previous section.

With this tiny bit of Markdown syntax, you actually have all you need to write an article just like this one.

Using Markdown to Create Other Documents

The Markdown project provides a command-line tool to work with Markdown documents. However, this is a command-line utility, so it's not the most convenient, and it's written in the somewhat outdated Perl language, too.

ReText, the Markdown Editor, Showing Live Preview and Export Options.

Fortunately, there are two other types of apps out there that are a bit more capable when dealing with Markdown input.

  • Pandoc: Among command-line utilities, Pandoc stands out as a virtual Swiss army knife for document conversion. It's well worth spending the time to learn. With it, you can easily output your Markdown files in Word (.DOCX), OpenDocument Text (.ODT), or PDF formats.
  • ReText: You can use any humble text editor to work in Markdown, but ReText will allow you to work in Markdown a little more easily. It's a no-nonsense editor with multiple document tabs and a live preview of your Markdown. It won't export directly to Word format, but you can open an .ODT file in Word and save it appropriately.

Markdown is a Portable Format That's Easy to Work With

Markdown is a way to capture your writing wherever you are, regardless of the device you're on, and be confident you can use it to create a formatted document later.

The plain text format is small with respect to file size, portable, and gets you out of the habit of fiddling with fonts until it's time to actually publish it somewhere. By learning its easy syntax, you'll be equipped to write in content management systems for the web, convert school assignments into attractive PDFs, and everything in between.