Web content must be presented in HTML format. Many online publishing tools (such as blogging software and CMSs) convert your content (text, images, and so on) to HTML. But there are many situations where you want to write HTML content yourself … and tagging the content with HTML tags manually is tedious and not really profitable. Enter Markdown.

Markdown is an easy, seamless way to write content for the web and the perfect way for developers to create documentation. It allows you to easily parse and format documents using simple, text-based annotations that are then converted to HTML for you – all in your favorite text editor.

If you are not yet using Markdown, now may be the time to get started. You can learn the basics in minutes, and with constant use, syntax becomes another character. In this article, we encourage you to get started simply and show you how to use Markdown for several common tasks in creating content.

Let’s dive in!

What is a Markdown?

Markdown is a light markup language created by John Gruber in 2004. It is easy to write, easy to read and can be easily converted to HTML. It is designed primarily for writing on the web.

Its popularity has grown rapidly and is now used in situations never designed by its creator. But it is not perfect. It has limitations, especially when it excludes formatting from many HTML elements that you may need to use (such as tables). It can also be a little vague.

As a result, a number of variations have been created to solve these problems:

  • CommonMark attempts to standardize Markdown and make it less ambiguous, which contradicts some of the original syntaxes of the process.
  • GitHub’s seasoned markdown (GFM) extends CommonMark and is used to create GitHub documentation.
  • MultiMarkdown added new syntax for tables, footnotes, references, and more.
  • Pandoc extends Markdown to multiple output formats (not just HTML) and supports document metadata, footnotes, tables, superscripts, subscripts, and more.

Some web services and Markdown editors support some of these variations 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 to simply get started. Select a use case, and then start creating a blog post, improving your documentation, or just adding some formatting to your notes. Raise the syntax piece by piece as needed.

You can use your favorite text editor or choose one of the many applications designed to work with Markdown. Markdown editors can make the learning process easier by allowing you to preview formatting directly or in a separate pane. This means that you can see at a glance whether you are using the correct syntax or not.

Personally, I use Marked 2 preview Markdown files on my Mac. It’s a commercial product, but of course you’ll find plenty of free plug-ins for the editor of your choice. You can also edit and preview Markdown files online Markdown Live preview and StackEdit.

See these articles for instructions on choosing the right Markdown editor:

Structuring documents

The Markdown feature allows you to add structural elements to a document, such as titles (h1, h2, h3 and so on.). There are a few ways to add titles in Markdown. My favorite is to add a title with a hash #, one for each heading level:

# Heading 1

## Heading 2

### Heading 3


And this is body text.

The hash rows move lower-level headings to the right, making them look like indents. If you want, you can use the same number of seals at the end of the line to close the headings:

### Heading 3 ###

There is another way, although I don’t see it used so often. You can create two header levels by highlighting H1 headers equally = symbols and H2 headings with dashes -:

Heading 1 or Title

Heading 2

Parts of a document can be separated using horizontal rules (<hr />) or lines. You can create these in Markdown using three (or more) dashes -, stars *, underline _ or is equal to = signs. Place them alone on the line, with blank lines on each side:

Brief introduction.


# Chapter 1

Lots of text.


# Chapter 2

Some more text


Lists are another important structural element. Unorganized lists (<ul>) is created by starting the line with an asterisk *, plus + symbol or dash -followed by a space or tab and then text:

* this
* is
* an
* unordered
* list

+ this
+ is
+ too

- and
- so
- is
- this

Select the desired symbol. You can switch between these symbols and the result is the same. I tend to use stars or dashes.

Organized lists (<ol>) are numbers followed by dots. The numbers do not have to be in order. Each of these works:

1. this
2. is
3. an
4. ordered
5. list

1. and
1. so
1. is
1. this

The markdown editors I use automatically resume the list when you press return.

If you want to start a line with a number and a dot without starting the list, you must avoid the dot with a slash :

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.

Basic text formatting

Basic text formatting includes bold and italics. The underscore is not usually used online because hyperlinks are formatted, so Markdown does not support it. If you really want to use it, just use it <u> HTML tags. (This is worth noting more generally. If Markdown does not support a particular type of HTML element, you can only use HTML markup. There is only one caveat: any Markdown syntax indoors HTML tags are not parsed.)

Words in italics are delimited by a single asterisk (*) or an underscore (_):

this is *italics*
and so is _this_

Words in bold are separated by a double asterisk (**) or an underscore (__):

this is **bold**
and so is __this__

Some people want to choose either an underscore or italics. For example, I usually use stars for both **bold** and *italics*.

Others want to distinguish between bold and italic using different symbols like this: **bold** and _italics_:

_You **can** also combine them_

Expressions and code blocks

Expressions can be created by starting a line larger than (>) symbol, just as older e-mail programs quoted previous messages:

> This is a blockquote. Single paragraphs
> can be continued like this on a second line.
> Multiple paragraphs can be quoted by using a
> line with a single greater than symbol.

The primary method is a little simpler and uses only a larger than symbol at the beginning of each quoted song. This works regardless of whether you are using an editor that wraps songs hard or soft:

> You can also blockquote a paragraph
by placing a single greater than symbol at
the beginning of each paragraph.

> Nested blockquotes are also possible
> > Like this.

Blocks of code created by indenting at least four spaces or one tab for each line:

This is a normal paragraph:

    This is a code block.

But other Markdown flavors prefer to use backtics. For example, Ulysses uses two backticks at the beginning of a line of code:

``This is a code block.

GitHub’s seasoned Markdown uses three backtics to start and end a block of code. Obsidian, Bear, and some other Markdown vendors follow the same policy:

This is a code block.

To embed that code block in a code block, I wrapped it in four backticks. In GitHub, you can add a language if you wish syntax highlighting:

This is Ruby code with syntax highlighting.

The code can be displayed in a paragraph using individual backtick delimiters:

This code `<bold>` will be displayed, not interpreted.

Links and pictures

Links and images use a combination of square brackets [] and parentheses (). For links, you enclose the anchor text in square brackets, immediately followed by the URL in parentheses:

This is a [link to a web page](https://url.com).

If you want, you can add a title to the link. It appears as a tooltip when you hover your mouse over the link. Paste the title in quotation marks after the URL and in parentheses:

This is a [link to a web page](https://url.com "This title will appear as a tooltip").

Another method of tagging links is known as linking references. These look like footnotes in a Markdown document, but they are converted to regular links when exported to HTML. The goal is to make the Markdown document more readable.

Instead of linking directly to the URL, you use the label in square brackets. Then elsewhere in the document (usually at the bottom), you paste that tag into the URL:

This is a [link to a web page][mylabel].

Then at the end of the document …

[mylabel]: https://url.com "Optional title"
[mylabel]: <https://url.com> (Optional title)

Tags are case-insensitive and can consist of letters, numbers, spaces, and punctuation.

Pictures use a similar syntax but start with an exclamation point (!):

![Alt text](https://imageurl.com)

If you want, you can add a title enclosed in quotation marks in parentheses.

![Alt text](https://imageurl.com "This is a title")

You can also use reference links to images:

![Alt text][mylabel]

[mylabel]: https://imageurl.com "This is a title"

GitHub Flavored Markdown is used by many developers and provides extra syntax to improve it. Here are some examples.

Strikethrough is an additional text formatting option achieved by double tilding (~~):

This is how you do ~~strikethrough~~.

To-do lists can be created - [ ] uninspected products and - [x] for inspected products:

- [ ] This item is unchecked
- [x] This item is checked

You can create table using tubes and dashes to draw lines. Three or more dashes --- create headers and tubes | create columns:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| some text | more here | and this  |
| some more | this too  | and this  |

This looks better when the columns are aligned, but it is not necessary. In either case, the table is created correctly when exported to HTML:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| some text | more here | and this |
| some more | this too | and this |

Creating such a table is quite tedious, especially if you need to edit the contents of the cells. Fortunately, it is online table generators which simplify the process.

Last words

Markdown isn’t for everyone, but there’s a lot to keep. Personally, I appreciate that it’s open, easy to learn, and doesn’t lock you out of using a particular program.

If you have reached the end of this article, it may be the right tool for you too. Dive in and start using it. Learn the syntax piece by piece as needed, and before you know it, it becomes another character.

Make sure you download from us free printable Markdown scam sheet. It covers kernel Markdown syntax, some extended syntax, tools for handling Markdown, and other resources.


Please enter your comment!
Please enter your name here