Content on the Web needs to be presented in HTML format. Many web publishing tools (such as blogging software and CMSs) convert your content (text, images and so on) into HTML for you. But there are many situations where you want to write HTML content yourself … and marking up content with HTML tags manually is laborious and not really viable. Enter Markdown.
Markdown is an easy, frictionless way of writing content for the Web and the perfect way for developers to create documentation. It lets you structure and format documents easily using simple, text-based markup, which then gets converted into HTML for you — all from within your favorite text editor.
If you’re not already using Markdown, now might be the time to begin. You can learn the basics in minutes, and with ongoing use, the syntax will become second nature. In this article, we’ll encourage you to start simply and show you how to use Markdown for a range of common tasks when creating content.
Let’s dive in!
What Is Markdown?
Table of Contents
Markdown is a lightweight markup language created by John Gruber in 2004. It’s easy to write, easy to read, and can be easily turned into HTML. It was primarily designed for writing for the Web.
It has rapidly grown in popularity and is now used in contexts never envisaged by its creator. But it’s not perfect. It has limits, especially as it leaves out formatting for a lot of HTML elements you might need to use (such as tables). It can also be a little ambiguous.
As a result, a range of variants has been created to deal with these problems:
- CommonMark attempts to standardize Markdown and make it less ambiguous, contradicting some of the original syntaxes in the process.
- GitHub Flavored Markdown (GFM) extends CommonMark and is used when creating documentation on GitHub.
- MultiMarkdown added new syntax for tables, footnotes, citations, and more.
- Pandoc extends Markdown for multiple output formats (not just HTML) and supports document metadata, footnotes, tables, superscript, subscript, and more.
Some web services and Markdown editors support the syntax of some of these variants or even use their own version of Markdown. Fortunately, they all support the original Markdown syntax, and that’s what we’ll focus on in this article.
Learning Markdown
The best way to learn Markdown is simply to start. Pick a use case and begin, whether that’s creating a blog post, working on documentation, or just adding some basic formatting to your notes. Pick up the syntax piece by piece as you need it.
You can use your favorite text editor, or choose one of the many apps designed to work with Markdown. Markdown editors can ease the learning process because they allow you to preview your formatting inline or in a separate pane. That means you can see at a glance whether or not you’re using the correct syntax.
Personally, I use Marked 2 to preview Markdown files on my Mac. It’s a commercial product, but of course you can find lots of free plugins for your editor of choice. You can also edit and preview Markdown files online using Markdown Live Preview and StackEdit.
For help choosing the right Markdown editor, refer to these roundup articles:
- The Best Markdown Editors for Mac
- The Best Markdown Editor for Windows
- The Best Markdown Editor for Linux
Structuring Documents
Markdown lets you add structural elements to your document, such as headings (h1, h2, h3 etc.). There are a few ways to add headings in Markdown . My favorite is to prefix a heading with hashes #, one for each level of heading:
# Heading 1 ## Heading 2 ### Heading 3 etc. And this is body text. The hashes move lower-level headings further to the right, so they appear indented. You can optionally use the same number of hashes at the end of the line to close the headers:
### Heading 3 ### There’s a second way, though I don’t see it used as often. You can create two levels of headings by underlining the H1 headings with equals = symbols and H2 headings with hyphens -:
Heading 1 or Title ================== Heading 2 --------- Sections of a document can be separated using horizontal rules (<hr />), or lines. You create these in Markdown using three (or more) hyphens -, asterisks *, underscores _ or equals = signs. Place them alone on a line, with blank lines on either side:
Brief introduction. === # Chapter 1 Lots of text. --- # Chapter 2 Some more text --- Lists are another important structural element. Unordered lists (<ul>) are created by beginning the line with an asterisk *, plus + symbol, or hyphen -, followed by a space or tab, then the text:
* this * is * an * unordered * list + this + is + too - and - so - is - this Choose whichever symbol suits you. You can switch between these symbols and the end result will be the same. I tend to use asterisks or hyphens.
Ordered lists (<ol>) are numbers followed by periods. The numbers don’t necessarily have to be in order. Either of these will work:
1. this 2. is 3. an 4. ordered 5. list 1. and 1. so 1. is 1. this The Markdown editors I use automatically continue a list when pressing return.
If you want to start a line with a number and a period without starting a list, you need to escape the period with a backslash :
2020. A year we'll never forget. Finally, paragraphs of normal text are separated by one or more blank lines:
This will be formatted as an HTML paragraph. And so will this. Continue reading Learn Markdown: Structure, Syntax, and Conventions on SitePoint.
