It should come as no surprise that we Linux Voicers are big fans of open standards. For complicated documents or spreadsheets, Open Document Format (ODF, as used by LibreOffice) is the way to go. But, it's also a rather complicated beast, and for shorter or simpler texts that you may want to process using other tools, it's arguably overkill. So, what other options do you have for text-heavy content?

Well, there's HTML – which is somewhat standardized but gets a bit fiddly to write with all the tags. If you're working on a scientific paper, then LaTeX is a great choice, but it has a pretty steep learning curve. And, of course, there's always plain ASCII text, but that has its limitations as well – namely, there's no way to add formatting.

Wouldn't it be great if you could add some symbols and other bits to plain text, so that it's perfectly readable in an editor like Vim, Emacs, or Nano, but could also be processed to add formatting? Enter Markdown [1]. The name is a play on markup, as in a "markup language" like HTML, but Markdown is very different. It was originally created in 2004, and today there are various implementations and supersets (with no official standard).

Regardless of the implementation, the core features of Markdown are the same – and it's used in many places, including GitHub (look for files with .md extensions). With Markdown, you can create structured plain text files in any editor and process them to prettier HTML (or other formats) when necessary. In that sense, it's the perfect middle ground between raw ASCII text and word processor formats. In this article, we'll show how to write, edit, and process Markdown docs, all from the comfort of your favorite text editor. (See the "Dedicated Markdown Editors" box for more information.)

Getting Started

The first thing you'll need to do is install Markdown itself, which converts plain text files into prettier HTML. Search for it in your distro's package manager (most distros have it available). If you're on an Ubuntu-based distro, you can install it from the command line like so:

sudo apt install markdown

If you can't find it anywhere in your distro, you can get it from the project's website [1]. Extract the .zip file, cd into the resulting directory, and use ./Markdown.pl in place of "markdown" for the rest of the commands in this tutorial.

Now, let's try some Markdown! Using your favorite text editor, create a file called test.md with the following content:

My _first_ file in **Markdown**!

Just by looking at that, can you guess what the formatting is? The underscores surrounding "first" suggest underlining, right? The double asterisks around "Markdown" look like they're trying to make the word stand out, yes? If you follow some plain-text mailing lists, you may have seen people using these pseudo-formatting options before – especially on the Linux kernel mailing list, where Linus Torvalds uses them a lot.

Anyway, let's convert this plain text into HTML. At the command line:

markdown test.md > test.html

This simply uses the Markdown tool to process the contents of our test.md file and redirect the output to a test.html file. Now open that HTML file in a web browser, and voilà – you'll see the results, like in Figure 1, which also shows the HTML source that is generated.

Figure 1: Our first Markdown document, showing how it's rendered in Firefox (and the HTML source).

Now, you'll notice right away that the HTML formatting is slightly different to what you may have expected from the Markdown version. Specifically, the underscores haven't made the word "first" underlined, but rather in italics. This is because Markdown converts the underscores to <em> tags – for emphasis – which the browser then chooses to interpret as italics.

So, you already know how to create italics and bold with plain text. But what about combining them together? Try this:

Check out this **_word_**

Run the previous command to generate the HTML, and view it again in your browser – this time "word" is in both bold and italics. It's possible to use Markdown formatting across multiple words, like so:

_This sentence is in italics._
**And this one is bold!**

When you look at the HTML version of this, you'll notice that both sentences have been combined into the same line. Markdown is very strict about paragraph formatting; to make it clear that you want the lines to be in separate paragraphs, put a blank line between them:

_This sentence is in italics._
**And this one is bold!**

If you look at the HTML version of this, you'll see that each line is surrounded by its own <p> tags now.

Heads Up

Now that we have some basic formatting sorted out, let's turn to structure. In Markdown, you can create headings of different sizes by prefixing words with hash marks (#). Try this, for example:

# A big heading
A normal paragraph.

Note that you don't strictly need the space between the hash mark and the content, but when you're writing Markdown content, always bear in mind usability. Even if your ultimate goal is to make an HTML version of your document, the whole point of Markdown is that it should still be easy to read in plain text.

For smaller headings, add more hash marks. There are six heading sizes in total.

# Title of doc
Introductory paragraph.
## Section header
In this section we will...
### Subsection
By the way, you should...

Convert this to HTML, and you'll see the results like in Figure 2. Always keep in mind that the headings aren't just used for presentation purposes; they add structure to a document as well. As I'll show later in the tutorial, you can convert Markdown documents into many other formats, where structure is often especially important.

Figure 2: Structure is important in Markdown documents – there are different headers to denote sections and subsections.

Creating bulleted lists is easy – just prefix the items with asterisk (*) marks like so:

* One thing
* Another
* And one more

What about numbered lists? These are simple too:

1. One thing
2. Another
3. And one more

Note that you can put lists inside other lists; to do this, adjust the indentation by adding an extra space for the sublist. Here's an example:

* Outer list
 * Inner list
 * Inner list
* Outer list

For yet another level of indentation, use two spaces at the start instead of one. You can, of course, use the other formatting options we've covered beforehand, like bold and italic.

If you're writing a document and want to quote something from another source (or just make a particular paragraph really stand out, you can use block quotes. These are marked by greater-than (>) signs and work like this:

Normal paragraph
> Blockquoted para.
This is also blockquoted
Normal paragraph

Note how the line beginning with "This is also" is included in the block quote – because it follows immediately after the line beginning with >. An empty line is required to end the block quote and return to the normal paragraph style.

If you're citing something in a block quote, then you may want to provide a link to the website as well. These look a bit tricky in Markdown, but with a bit of practice you'll soon get used to them. Links are made of two parts, like in a regular HTML document: the text that's displayed for the link and the actual address to which it points.

Say we want to create a link with the text "Linux Magazine" that points to the website at http://www.linux-magazine.com. We put the text inside square brackets, and the address inside round brackets:

[Linux Magazine](http://www.linux-magazine.com)

This might look a bit ugly as raw text, but it gets the job done and when you generate an HTML version, you just see the link text (so just Linux Magazine, which will be clickable).

Suppose you're writing a long document that contains multiple links to a specific web page. Later, you need to change all of those links to point to something else. You could do a find-and-replace job in your editor for this purpose, but Markdown offers a more elegant solution in the form of reference links. These let you define a link at the end of the document, with a name, and then you can reference that name throughout the text. Here's an example:

You should go to [the LM website!][our-site]
...
[Visit our website][our-site] for more info.
[our-site]: http://www.linux-magazine.com

In this document, both "the LM website" and "Visit our website" links point to the same place, as defined by the "our-site" reference at the end. So, if we wanted to change that link to something else, we only have to edit one line and not go through the entire document. Pretty handy, right? Note that the reference link itself doesn't appear in the actual HTML that's generated.

A Picture's Worth a Thousand Words

What about images? Obviously, these are not easy to integrate into plain-text documents (unless you want to do very funky things with ASCII art), so Markdown's solution involves an exclamation point (!), alt text, and the address of the image, like so:

# NetBSD rules!
It really does. Just check out its logo:
![NetBSD logo](http://www.netbsd.org/images/NetBSD-smaller.png)

Here, the alt text is provided in square brackets – this is the tooltip text that appears in the HTML version, when you hover over the image. Using alt text on the web is good practice, as it provides extra information for search engines and visually impaired users. It's good to have useful text in Markdown as well, keeping in mind that the plain-text version should be just as useful (or close enough) as the HTML equivalent.

We then have the address of the image in rounded brackets, and the results can be seen in Figure 3.

Figure 3: Want to include an image in the converted document? That's easy, too.

If you want to include code in your documents and have it rendered in a monospace font in the HTML version, you can surround the code with three back tick (`) characters like so:

Some Python code:
```x = 1
print(x)```

As your documents get longer, it's a good idea to break them up using horizontal lines. To add these in Markdown, and get <hr> tags in the resulting HTML, use three or more dashes:

This is the end of a section.
---------
Now, onto something else...

Three dashes suffice, but I like to use more so that they're wider in the Markdown text and emphasize that they're splitting up the document.

Finally, in some circumstances, you may want to use Markdown symbols on their own, without Markdown poking its nose in and trying to convert them into something else. To do this, use backslashes before the symbol – for instance, here's how to generate the word  awesome, including the asterisks, without Markdown making it bold in the HTML version:

\*\*awesome\*\*

You'll probably never need this feature, but it's worth bearing in mind, especially if you ever end up writing a Markdown document about… writing Markdown documents!