Learn markdown in 10 minutes!¶
Markdown is a simple markup language that allows you to write formatted text using a plain-text editor. It is a popular choice for writing documentation, blog posts, forum posts, and other content that is published online. If you don't know markdown already, this tutorial will teach you the basics.
Markdown files end with
.markdown extension, and are rendered with a markdown processor. The most popular markdown processor is CommonMark.
A brief history of markdown¶
Markdown was initially developed by John Gruber (with help from Aaron Swartz) in 2004. It was designed to be as readable and easy-to-write as possible, while being able to be converted to valid HTML.
Markdown is now one of the most popular markup languages, and is used by many websites, including GitHub, Reddit, Stack Overflow, and more.
This guide will cover the basic markdown syntax which is supported by most markdown processors. I will use CommonMark specification as the reference. Let's get started!
Surround the text with
_ to emphasize the text. This is the syntax:
It's pretty straightforward. Here are some more examples:
||Markdown is fun!|
||Dumbledore said calmly.|
For the best compatibility, use
* instead of
_ for emphasis.
Paragraphs are separated by a blank line. For example:
Adding a line break
You can add a line break by adding two spaces or a backslash
\ at the end of the line. For example:
Headings begin with a
# and a space. You can use multiple
# to change the level of the heading. The more the
#, the smaller the heading. The level of heading corresponds to the HTML heading element as follows:
You can also alternatively use this syntax to represent h1 and h2 headings:
You can use formatting (emphasis, links, etc.) in headings, too.
Add a line before and after headings to make them readable.
Blockquotes are used to quote text from another source. Use
> at the beginning of the line to create a blockquote. You can also nest blockquotes by adding additional
This is a blockquote. It can span multiple lines.
It can span multiple paragraphs, too.
This is a nested blockquote!
The space after
> is not required, but it makes the markdown more readable.
Unordered lists can be created by using
+ at the beginning of the line. For example:
A space is required after the list marker.
We can also nest lists. Nesting can be done by indenting the list marker. For example:
- name of the friendly ghost
- name of the Guru of Time in Chrono Trigger
Ordered lists can be created by using numbers followed by a period
. or a right parenthesis
) at the beginning of the line. For example:
If you start the list with a number other than 1, the numbers will be incremented accordingly. Also, you don't have to write the numbers in order, only the first number matters.
Links can be created by using this syntax:
[link text](url). For example:
Adding a title to links
Link title is displayed when you hover over the link.
Adding a title is as easy as adding a space after the URL and enclosing the title in quotes. For example:
You can also use reference-style links. This is useful when you want to link to the same URL multiple times. This is how it works:
homepage is the link reference. It can consist of letters, numbers, spaces and punctuation. It's not case-sensitive.
The last line is the link definition. It consists of the link reference, followed by a colon
:, followed by the URL. The optional title can be added by adding a space and enclosing the title in quotes.
The link definition can be placed anywhere after a blank line, but it's usually placed at the end of the document.
Images are similar to links, but they start with an exclamation mark
!. Its syntax is
![alt text](url). For example:
What is alt text?
Alt text is used to describe the image. It is displayed when the image fails to load. It is also used by screen readers to describe the image to visually impaired users.
Adding a title to images
Adding a title to images is similar to adding a title to links. Add a space after the URL and enclose the title in quotes. For example:
Just like links, you can also use reference-style images. Just add a
! at the beginning of the link reference. Nothing else changes.
Inline code can be created by surrounding the text with backticks
`. For example:
printf() function is used to print text. This function is imported from the
stdio.h header file.
Code blocks (or fences) are used to display a block of code (duh!). Code blocks can be created by indenting the code by four spaces or one tab. For example:
import os while True: os.fork()
You can also use triple backticks
``` to create code blocks. For example:
``` import os while True: os.fork() ```
Horizontal rules can be created by placing three or more
_ on a blank line. For example:
There's a line above me! That's the horizontal rule.
Congratulations! You've covered the basics of markdown. But that's not all. Let's learn about some nice features of markdown. All of this is supported by most markdown processors.
Most inline HTML tags are supported, meaning markdown is a superset of HTML (not necessarily, though). This means you can use HTML tags in markdown, but it isn't recommended.
You cannot use markdown syntax inside HTML tags in most markdown processors.
Using a VPN will shift your trust from your ISP to your VPN provider.
For the best compatibility, avoid using HTML tags in markdown. Some markdown processors doesn't support all HTML tags.
URLs and emails can be converted to links automatically if you enclose them in angle brackets
>. For example:
<https://neal.fun/> is a cool website. Email me your favorite websites at <[email protected]>.
https://neal.fun/ is a cool website.
Email me your favorite websites at firstname.lastname@example.org.
Sometimes, you may want to use characters that are reserved by markdown. You can escape these characters by adding a backslash
\ before the character. For example:
*This is not italic*
# This is not a heading
All classes have a __init__() function in Python.
The CommonMark syntax was not enough for some people, so they extended the syntax to add more features. Let's learn about some of them.
Did you know?
This blog post is written in markdown! Check out the source code to see how it's done. Some syntax might be unfamiliar since it uses markdown extensions.
GitHub Flavored Markdown¶
GitHub Flavored Markdown (GFM) is a superset of CommonMark. It adds some features that are useful for writing documentation, like tables, task lists, strikethrough, etc. Check out the complete specification of GFM.
Markdown Extra (MDE) supports features like markdown support inside HTML blocks, footnotes, abbreviations, definition lists, fenced code blocks, etc. Learn more about it on their website.
That's about it¶
Now, you can write beautifully formatted
README.md files for your open-source repositories, write blog posts, and more!