It's happening again. You stare at your screen, trying to figure out why your write-up looks like an IKEA manual, written using only the stuff that comes after the question mark in an URL. Wouldn't it be great to create content and format it seamlessly without making it less human-readable in the process?
This is where Markdown comes in. Markdown allows you to quickly write and format structured content for the web. It is easy to learn and can be used to create websites, notes, technical documentation, and even books!
Fun Fact: This entire tutorial has been designed and formatted using Markdown itself! Read till the end to find an awesome cheat sheet for this tutorial which has also been created using Markdown!
Wait...What's Markdown Again?
Markdown is a lightweight markup language used for formatting plain text documents with a simple, unobtrusive syntax. It was created by John Gruber with Aaron Swartz in 2004. From the official documentation at Daring Fireball, Markdown can be defined as,
"a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)."
Okay, let's break that down. A Markup language is a human-readable language that provides a system to annotate text inside a document. These annotations (or tags) can then be used to structure and format the document.
One of the most commonly used markup languages is the HyperText Markup Language, better known as HTML. Despite being the de facto standard for web design, HTML comes with a few downsides.
HTML relies heavily on syntax-specific tags which make the content hard to read. This problem inspired John Gruber to come up with a cleaner, more readable markup language called Markdown. In his own words,
"The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions."
(https://daringfireball.net/projects/markdown/)
Here's a small clip of Markdown in action -
Turn down Markdown For What!?
Due to its highly intuitive and portable nature, Markdown is used in a wide variety of applications. Some of its use cases are -
- Documents - While Markdown is not as powerful as Microsoft Word or similar What You See Is What You Get (WYSIWYG) editors, it is good enough for lightweight formatting
- Websites - Static site generators like Jekyll convert Markdown files into static HTML websites that can be hosted for free on platforms like GitHub Pages
-
Documentation - Markdown offers the ideal syntax for technical documentation and is widely used for writing scientific papers, articles, and even the
README.mdfiles in GitHub (like the one shown below)
How To Get Started
One of the biggest advantages of learning Markdown is that it does not require downloading a whole bunch of applications (paid or otherwise) to create Markdown-formatted documents. Simply choose from a wide array of free online Markdown editors to learn and practice the syntax or, just launch your favorite text editor and you're good to go!
Markdown Editors
To get started with Markdown, you have the following options (and more) at your disposal -
Online Markdown Editors -
Desktop Applications -
- Visual Studio Code
- Atom
- Typora
- MacDown (only available for macOS)
How to get the most out of this tutorial?
To follow along with the tutorial, choose an online editor like Dillinger and try out the syntax as you learn it. After you get accustomed to the syntax, you can switch to an offline text editor like VS Code to create fully-fledged Markdown documents. Just create a plain text file with the .md or .markdown extension, open it using your editor of choice and you're off to the races!
For this tutorial, I've used VS Code with the extension Markdown Preview Enhanced installed. You can use the Markdown previewer that comes bundled with VS Code as well. Also included at the very end, is a cheat sheet summarizing the entire tutorial. So, without any further ado, let's get started!
Basic Markdown Syntax
Almost all Markdown applications support the basic syntax outlined in John Gruber's original documentation. The most commonly used elements in the basic Markdown syntax are discussed below.
Headings
Heading elements in Markdown can be created by prepending the number symbol # to a word or phrase.
The number of hashes (#) indicates the level of the heading. One hash (#) corresponds to a level 1 heading - all the way up to six hashes (######) for a level 6 heading.
Pro-tip: Always add a space between the hash symbol and the heading name for consistent results.
# Level 1 Heading ## Level 2 Heading ### Level 3 Heading #### Level 4 Heading ##### Level 5 Heading ###### Level 6 Heading |
<h1>Level 1 Heading</h1> <h2>Level 2 Heading</h2> <h3>Level 3 Heading</h3> <h4>Level 4 Heading</h4> <h5>Level 5 Heading</h5> <h6>Level 6 Heading</h6> |
Paragraphs
To separate multiple lines of text into paragraphs, simply use one or more blank lines.
Pro-tip: To force a line break (without using the <br /> tag), end a line or paragraph with two or more spaces, and then press return (enter).
This is a paragraph. Insert a blank line to add another one! This is another paragraph. It's that simple! |
<p>This is a paragraph. Insert a blank line to add another one!</p> <br /> <p>This is another paragraph. It's that simple!</p> |
Horizontal Rules
Thematic breaks in the form of horizontal rules can be inserted by using three or more asterisks ***, hyphens ---, or underscores ___, with or without spaces in between.
*** --- ___ |
<hr /> <hr /> <hr /> |
Text Formatting - Emphasis
Text can be emphasized by making it bold or italicized.
To make the text bold, add double asterisks ** or double underscores __ before and after a word or phrase. To italicize text, wrap the word or phrase inside a pair of a single asterisk * or a single underscore _.
Pro-tip: Use asterisks instead of underscores when formatting words inside of a phrase.
__This text is in bold__ And so is this **word** _This text is italicized_ And so is this _word_ **_This text is in both bold and italics_** And so is this **_word_** |
<strong>This text is in bold</strong> And so is this <strong>word</strong> <em>This text is italicized</em> And so is this <em>word</em> <strong><em>This text is in both bold and italics</em></strong> And so is this <em><strong>word</strong></em> |
Blockquotes
Blockquotes can be created by adding the > symbol in front of a line of text.
To add blockquotes comprising of multiple paragraphs, add a > on each black line.
Pro-tip: To create nested blockquotes, add two or more > symbols depending upon the level.
>"I'm gonna make him an offer he can't refuse." > Fate whispers to the Warrior, > A storm is coming, > > > And the Warrior whispers back, > > I am the Storm. |
<blockquote>"I'm gonna make him an offer he can't refuse."</blockquote> <blockquote> Fate whispers to the Warrior, A storm is coming, <blockquote>And the Warrior whispers back, I am the Storm. </blockquote> </blockquote> |
Lists
Using Markdown, related items can be grouped in the form of unordered or ordered lists.
Unordered Lists
To create unordered (bullet) lists, prefix the list items with asterisks *, hyphens - or plus signs +.
* First list item * Second list item * Third list item - Element 1 - Element 2 - Element 3 * List item 1 * List item 2 * List item 3 |
<ul> <li>First list item</li> <li>Second list item</li> <li>Third list item</li> </ul> <ul> <li>List item 1</li> <li>List item 2</li> <li>List item 3</li> </ul> |
Ordered Lists
To create ordered lists, prefix the list items with numbers followed by periods. The labels do not even need to be in the correct numerical order - Markdown does that for you automatically!
1. First list item 1. Second list item 1. Third list item a. List item 1 b. List item 2 c. List item 3 |
<ol> <li>First list item</li> <li>Second list item</li> <li>Third list item</li> <li>List item 4</li> <li>List item 5</li> </ol> |
Pro-tip: You can also create nested lists (sublists) made up of both ordered and unordered lists by simply indenting the nested list items.
1. Parent list item 1
1. Parent list item 2
a. Child list item a
b. Child list item b
1. Parent list item 3
* Child item 1
* Child item 2
|
<ol>
<li>Parent list item 1</li>
<li>Parent list item 2</li>
<ol>
<li>Child list item a</li>
<li>Child list item b</li>
</ol>
<li>Parent list item 3</li>
<ul>
<li>Child item 1</li>
<li>Child item 2</li>
</ul>
</ol>
|
Links
Links in Markdown can be created in the following ways:
-
Inline-style links - Wrap the link text in brackets
[]followed by the link URL in parenthesis(). To add an optional tooltip, enclose the title within quotes and add it right after the URL. -
reference-style links - Instead of inserting the URL inside the parenthesis, a reference to the link can also be made. Create such a link by enclosing the reference inside square brackets
[]and linking it to the URL from anywhere in the document.
Pro-tip: To quickly add a clickable URL or email address, enclose the link inside a pair of angle brackets <>
Markdown:
[An inline-style Link](http://example.com/)
[A reference-style link][Reference]
<!-- linking -->[Reference]: http://example.com/
<http://example.com/>
Equivalent HTML:
<a href="http://example.com/">Links in HTML</a>
<a href="http://example.com/" title="Tooltip">
Links in HTML with an optional title
</a>
Images
Images can be created the same way as links - the only thing that needs to be added is an exclamation mark ! before the link syntax.
-
Inline-style images -
 -
Reference-style images -
![alt text][reference][reference]: image URL
Pro-tip: Images can also be used as links themselves. Simply enclose the Markdown syntax for the image in brackets and append the link URL in parenthesis -
[](link URL)
Markdown:
Equivalent HTML:
<img src="https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg" alt="Markdown-mark">
Extended Markdown Syntax
To overcome the unambiguous specs proposed by John Gruber's Markdown syntax, several individuals and organizations came up with specific implementations - often referred to as flavors of Markdown. These lightweight markup languages provide extended features and improve on some of the drawbacks of the original syntax. Some of these are -
Some of the elements supported by these lightweight markup languages are discussed below.
Tables
Tables are available in GitHub Flavored Markdown (GFM). To create a table, separate each column with the pipe symbol | and use three or more hyphens --- to indicate the first row (column headers).
Pro-tip: To left, right or center align text in the columns, simply add a colon : to the left, right, or both sides of the column header hyphens respectively.
Syntax:
| First Name | Last Name | Age |
| :--------- | :-------: | --: |
| John | Doe | 28 |
| Jane | Doe | 52 |
Extended Text Formatting
Extended Markdown syntax allows text to be struck-through and highlighted. To strikethrough text, wrap the word or phrase inside a pair of double tildes ~~. To highlight text, use a pair of double equality signs == before and after the word or phrase.
Syntax:
Strikethrough text ~~like this~~ using a pair of double tildes
Highlight text ==like this== using a pair of double equality signs
Task Lists
Task lists are used to provide progress indicators in the form of list items with checkboxes.
To create a task list, simply add double brackets with a space between them [ ] before the list item in an unordered or ordered list. To check off a list item, add an x inside the brackets [x].
Syntax:
1. [ ] Unchecked list item
1. [x] Checked list item
1. [ ] Another unchecked list item
- [x] Research
- [x] Compose
- [ ] Publish
Code
Although inline code and code blocks can be created using the original Markdown syntax, it is convenient to discuss all the various ways to embed code in Markdown in one place.
Inline Code
To include inline code snippets, enclose the code in a pair of backticks `.
Run `npm install` to install all dependencies
Code Blocks
To create a block of code (without using extended syntax), indent each line of code by one or more tabs (at least 4 spaces).
while (--i >= 0) {
free_page((unsigned long);
}
kfree(group_info);
return NULL;
Fenced Code Blocks
Using the extended Markdown syntax, blocks of code can be created by wrapping the code block inside a pair of triple backticks.
```
// function to add two numbers
function add(num1, num2) {
return num1 + num2
}
```
Syntax Highlighting
To add syntax highlighting to a fenced code block, append the language name after the starting backticks ``` before the code block begins.
```js
// function to add two numbers using javascript
function add(num1, num2) {
return num1 + num2
}
```
```c++
// function to add two numbers using c++
double add (double num1, double num2) {
return (num1 + num2);
}
```
Escaping Characters
In case you actually want to use certain literals like * and # without having them formatted, simply prefix a backslash \ before the character or wrap it inside a pair of backticks ` (similar to inline code).
\# Without the backslash, this would be a level 1 heading!
Cheat Sheet
A list of frequently used basic and extended Markdown syntax has been provided in the cheat sheet linked below. Go ahead, fork this gist or bookmark it and use it as a quick reference to take your Markdown skills to the next level!
Fun fact: This entire cheat sheet has been created using Markdown itself!
Markdown Cheat Sheet
Wrapping it up
Now that you know how to use Markdown to format plain text, it's your turn to play around with the syntax, build cool projects with it, and have fun along the way!
Here's a list of useful resources you can utilize to elevate your Markdown skills -
- Daring Fireball - The official Markdown guide written by John Gruber
- Markdown Tutorial - An interactive browser-based markdown tutorial
- The Markdown Guide - A free and open-source Markdown reference guide
Whenever you get stuck over a particular syntax or feel like reviewing some of the concepts, give this tutorial a shot and hold on to that cheat sheet as a handy reference.
Final pro-tip: Never hesitate to use HTML for advanced formatting, as Markdown is more or less a superset of HTML.
If there's any syntax that I missed or anything that I wasn't able to explain clearly, feel free to hit me up in the comments below. Your feedback means a lot to me.
Disclaimer: Markdown is an incredibly powerful tool meant for composing rich content for the web and hence, is widely used across a large number of platforms and applications. This guide has been written in an effort to make Markdown accessible to beginners as well as, to serve as a quick reference for experienced users.
Top comments (0)