What is markdown?¶
Markdown is a lightweight markup language. Unlike other markup languages like HTML or XML, Markdown was designed for readability.
Designed for easy authoring¶
For example, compare the syntax for these common formatting tasks:
Desired Output
Bold
Italics
Unordered list:
- Internet access
- Computer
- Coffee
Ordered list:
- wake up
- drink coffee
- whistle while you work
Required syntax
<strong>Bold</strong>
<em>Italics</em>
<p>Unordered list:</p>
<ul>
<li>Internet access</li>
<li>Computer</li>
<li>Coffee</li>
</ul>
<p>Ordered list:</p>
<ol>
<li>wake up</li>
<li>drink coffee</li>
<li>whistle while you work</li>
</ol>
**Bold**
*Italics*
Unordered list:
* Internet access
* Computer
* Coffee
Numbered list:
1. wake up
2. drink coffee
3. whistle while you work
Although Markdown is arguably much easier to write, read, and edit than HTML, it doesn't replace HTML. Instead, Markdown is usually computationally converted to another format (often HTML) before it reaches its end reader, just as we might convert a word document to PDF. In fact, this web page was written in markdown before I used a static site generator called MkDocs to convert it to the HTML your browser is currently rendering. If you are curious, you can compare this page with the raw markdown that was used to generate it.
"HTML is a publishing format, Markdown is a writing format"
-- John Gruber, Markdown co-creator
As a result, the exact appearance of the resulting HTML is determined by CSS, not the Markdown itself.
Comes in many flavors¶
Since the release of the first iteration in 2004, many variations of Markdown have been developed for a variety of different use cases. Notable examples include Reddit-flavored Markdown and Github-flavored Markdown (GFM), each with unique conventions or additional features that are useful when writing content on Reddit and Github respectively.
Tools for trying Markdown¶
Markdown files are simply plain text, so you can create them in any text editor. I personally use the same text editor I use for everything else, but some editors have additional features that supposedly make writing in Markdown more enjoyable. A quick google will produce plenty of lists like this one: 4 open source Markdown editors.
If you want an editor specialized for Markdown, here are a couple of options:
Or, if you want to try out the syntax right now without leaving your browser, here are some in-browser Markdown editors:
Finally, if you want to a quick, interactive tutorial on the basic syntax, I like this one at markdowntutorial.com.
Learn more about Markdown¶
Here are but a few fantastics resources, many by scholars and practioners in technical communication!
History/Background¶
- Markdown co-creator John Gruber's discussion of the philosophy behind markdown
- The Markdown Movement | Aaron Beveridge
Applications in technical communication¶
- Exploring Markdown Authoring to Publishing Workflows | Tom Johnson, I'd Rather Be Writing
- Why you should and should not use markdown | Peter Conrad via Medium
- The Ins and Outs of Using Markdown for Technical Writing