Recently, we wrote all of our slides in Markdown and used mdpress (see post here), which was my official dive into Markdown. Prior to that, my exposure had been pretty limited. Since Markdown is commonly used, I’m going to do a quick run through.
The What and Why
Markdown is both a syntax and a tool. A Markdown file, which has the extension .md, is written in Markdown syntax so the Markdown tool can convert it to HTML. The idea behind Markdown is that it’s easier and faster than writing HTML and the source file (*.md) is more human-readable than an HTML file. Personally, I tend to only run into Markdown when looking through code on GitHub – specifically the Readme and related documentation files that programmers include with their applications.
Originally written in 2004, Markdown has been gaining a smattering of followers who use it for more than just writing plain text documents. As mentioned, I recently also encountered it as a tool for writing presentation slides, but a quick search on the net will yield other applictions as well, including various blog platforms, simple to-do lists, full fledged websites, or even resumés. (Note: I haven’t used most/all of these tools, I am simply using them as examples after a quick Google search.)
Why should I care?
You may be looking at all that and thinking "HTML isn’t that hard to read… I don’t know if I really care about all this". As with many "on the job" tools, your initial exposure (and, in fact, perhaps the only reason you’re reading this post) may only be because you found yourself in need of a quick understanding and how-to for a project at work or school. Don’t feel left out! That’s how I got here 🙂
The "Meat and Potatoes"###
Markdown syntax is very, very easy. In fact so easy that you might not even feel comfortable thinking of it as "syntax". To help myself out, I only needed to remind myself of three rules:
- All roads lead to Rome
- There are multiple flavors of Markdown
- If all else fails, use HTML
All roads lead to Rome
There is always more than one way to do something and the same is true of Markdown. To get you used to this idea, let’s take a look at how to make a header in Markdown (HTML tag <h1>). You can use either of the following:
#H1 Heading
H1 Heading
==========
There are also multiple ways to make bold, italic, and bold+italic text:
*Italics*
_Also Italics_
**Bold**
__Still Bold__
***Bold and Italics***
**_You get the idea..._**
Since there are a plethora of tutorials available on the web, rather than rehash everything here I’m providing some links at the bottom of the post. You may notice that not all tutorials cover all variations of the syntax. Don’t be confused! Part of this is brevity, but another part brings me to my second point:
There are multiple flavors of Markdown
Although "the basics" of Markdown are standard, there are some variations that provide additional functionality. One example I make frequent use of with GitHub Markdown is syntax highlighting. In Markdown, you can indicate code using either of the following:
`This` word is code formatted in line. ``` This would be a block of code, two lines. ```
Now let’s say you want to document a bit of Javascript, Ruby, or even bash in your Markdown file. You can use the above, but for added readability you can also make use of the syntax highlighting feature if your flavor of Markdown supports it. When available, you would specify the language of interest after the first set of backticks:
```bash $ mkdir -p workspace/apps $ cd workspace/apps $ git clone https://github.com/cloudfoundry-community/cf-env.git Cloning into 'cf-env'... remote: Reusing existing pack: 71, done. remote: Total 71 (delta 0), reused 0 (delta 0) Unpacking objects: 100% (71/71), done. ```
This feature is especially helpful when posting long output. Again for brevity, I’m not going to rehash all the possible specialized syntax here, but the Wikipedia article does list the most common flavors. If you are using a specific flavor of Markdown, make sure to check what additional features they offer (if any). If syntax highlighting is available, make sure you also check which languages the flavor supports.
If all else fails, use HTML
I was so relieved/happy when I discovered this. You may have something that you aren’t quickly finding the syntax for or that isn’t explicitly available in Markdown. Never fear! Since Markdown converts to HTML, HTML code is left as-is. As a quick example, let me show you how to make a section of blockquoted text. Now, there is valid Markdown syntax for that:
>This is a blockquote.
But let’s say you can’t find the syntax for some reason and would just like to put in the text and move on. You can still use:
<blockquote>This is a blockquote.</blockquote>
You can also mix HTML tags and Markdown syntax. For example, if you wanted to force where the line break occurred in your blockquote, rather than let it wrap around, you could do this:
>This is a blockquote, <br /> with a second line.
One final note
Although I usually prefer command line text editors, when I am working on Markdown files I usually use Atom (available for Mac and Windows). The main reason is because it has a built-in preview pane that allows you to see how your file will render while you edit it. As an added bonus, there are also many Markdown packages that can be added to Atom to make the job even easier.
Resources you may find helpful
What and why of Markdown
Some Markdown Tutorials
- GitHub Markdown
- Markdown Cheatsheet
- Markdown Tutorial
- Markdown Project @ Daring Fireball
- Markdown Primer @ The Unofficial Apple Weblog
This post brought to you by Markdown ツ
Spread the word
