Introduction to Markdown

Image from: upload.wikimedia.org

What is Markdown?

Markdown is a lightweight markup language with plain-text-formatting syntax. Its design allows it to be converted to many output formats, the most common being HTML.

Markdown is widely used for styling text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like '#' or '*'. The great thing about Markdown is that it is easy to learn and easy to read even in its raw form.

There are many flavors and extentions for Markdown created by different companies and individuals. For example, Github Flavored Markdown (GFM) (opens in a new tab) and MDX (opens in a new tab)

What can markdown be used for?

Markdown is used for many things, including, but not limited to:

• Documentation
• README files
• Forum posts
• Blog posts
• Messages
• And more!

In this tutorial, we will have a look at the basics of Markdown and how to use it to style text on the web. We will only focus on the basic syntax of Markdown, and not on any specific flavor or extentions.

Markdown playground

You can try out markdown in the editor below. Just type/modify the existing text and you will see the parsed output in real time.

Popular Markdown Editors

There are many editors that support Markdown. Some of the most popular ones are:

• Visual Studio Code (opens in a new tab)
  • VS Code supports Markdown out of the box. You can use it to write and preview Markdown files. You can find more information on how to use Markdown in VS Code here (opens in a new tab).
• Writerside (opens in a new tab)
  • Writerside is a Markdown editor that is part of the JetBrains suite of tools. It is a simple and easy-to-use editor that supports Markdown. You can find more information on how to use Writerside here (opens in a new tab).
• Etherpad (opens in a new tab)
  • Etherpad is a collaborative Markdown editor that allows multiple users to edit a document at the same time. To use Etherpad online, simply choose one of the many instances available online. Here's a list of some of them (opens in a new tab).

You can also use the markdown playground which we have provided below to try out Markdown in real time.

Basic Syntax

The basic syntax of Markdown comprises only a few elements. We will show these elements and an example of each of them.

Headers

Headers are specified using the # symbol. The number of #s specifies the level of the header. We can have up to 6 levels of headers in Markdown

Bold

To make text bold, it should be surrounded by two *s or two _s.

Italic

Italic text is surrounded by only one * or _.

Lists

Ordered

Ordered lists are written using when writing any number followed by a .. The first number you use will be the starting point of your ordered list. All other numbers that come after that do not have any effect as the list items will simply be incremented by 1 for every new item.

Unordered

Unordered lists can use either *, +, or - as list markers. Use two empty spaces to indent the list items once, four spaces two indent twice and so on. We don't recommend that you mix different symbols for the same list and same level as this is parsed as seperate lists.

Line breaks

Single line breaks that you have in your input are ignored by the parser. If you want to have a line break in the output, you can either use \ or add two or more line breaks in your text. If you want to have more than one line break in your output(e.g., A few empty lines), then you have to use \ for each one.

Links

• You can just enclose your text between < and > and it will be shown as a link.
• But if you want to display a different text, you should use this syntax [Text to display](https://url.org)
• you can also use relative links: [text to display](/relative)

Images

Images are very close to links in markdown. But they have an extra ! in front. The syntax for images are ![Alt text](/path/to/image).

The "Alt text" is a short textual description of the the image.

Here the path to the image can also be a url or a relative path.

Code

Inline code

Inline code is displayed on the same line. It is added by surrounding your code by a backtick `.

Code blocks

You can also write code on a seperate line (or lines) by surrouding it by three backticks ```.

git push
git pull

Blockquotes

To add a block quote, simply add a > at the begining of the line. Multiple consequetive quoted lines are grouped toghether in a larger quote.

You can also nest quotes by increasing the number of >s. You can also optionally adda spaces between them.

Keep in mind that you cannot go back to a lower level of a quote in the same block after a nested quote in basic MD as this would not be parsed properly.

Horizontal Rule

Horizontal rules help you seperate your text. To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a line by themselves

Escape Character

To escape any Character in Markdown, prepend it with a \. To escape the backslash itself, use \\.

Further Resources

• A comprehensive cheat sheet with an interactive tutorial for Markdown syntax can be found here (opens in a new tab)

Comments