All About Markdown

Markdown is used almost anywhere due to its simplicity.

Netbox, for example, used comment fields supporting markdown https://netbox.timewarp.at/static/docs/reference/markdown

My web content is based on markdown.

My development docs, e.g. on github or gitlab, are in markdown.

Want more than millions of pages? Look for yourself :-)

1. What is Markdown?

Markdown is a lightweight and simple markup language used to add formatting elements to plaintext text documents. Created by John Gruber with Aaron Swartz in 2004, its primary goal is to be as readable as possible, even in its raw form.

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.

It allows you to write using an easy-to-read, easy-to-write plain text format, which then converts to structurally valid HTML (or other formats).

2. Why Use Markdown?

Markdown is incredibly versatile. Here are a few reasons why it’s so popular:

• Simplicity & Speed: The syntax is minimal and intuitive.
• Readability: The raw Markdown text is clean and easy to read.
• Portability: As plain text, Markdown files can be opened on any device.
• Platform Support: It is supported by a vast number of applications and websites, including GitHub, Reddit, and Stack Overflow.
• Flexibility: You can convert Markdown to many other formats, such as HTML, PDF, and more.

3. Markdown Syntax: Command and Effect

Here is a demonstration of the most common Markdown elements, showing both the syntax and the result.

Headers

Headers are used to define the structure of your document.

Syntax:

# Heading 1
## Heading 2
### Heading 3

Effect:

Heading 1

Heading 2

Heading 3

Text Formatting

You can easily emphasize text with bold, italic, or strikethrough.

Bold Text

Syntax:

**This is bold text.**
__This is also bold text.__

Effect: This is bold text. This is also bold text.

Italic Text

Syntax:

*This is italicized text.*
_This is also italicized text._

Effect: This is italicized text. This is also italicized text.

Strikethrough Text

Syntax:

~~This was a mistake.~~

Effect: This was a mistake.

Bold and Italic

Syntax:

***This is really important!***
__*This is also really important!*__

Effect: This is really important! This is also really important!

Blockquotes

Use blockquotes to highlight text from another source. You can nest them.

Syntax:

> This is a blockquote.
>
> > This is a nested blockquote.

Effect:

This is a blockquote.

This is a nested blockquote.

Lists

Unordered Lists

Syntax:

* Item A
* Item B
  - Sub-item B1
+ Item C

Effect:

• Item A
• Item B
  • Sub-item B1
• Item C

Ordered Lists

Syntax:

1. First item
2. Second item
3. Third item
   1. Indented item

Effect:

1. First item
2. Second item
3. Third item
   1. Indented item

Task Lists (GitHub Flavored Markdown)

Syntax:

- [x] Complete initial draft
- [ ] Add more syntax examples
- [ ] Review and finalize

Effect:

• Complete initial draft
• Add more syntax examples
• Review and finalize

Code Blocks

Inline Code

Syntax:

`inline code`

Use backticks for inline code.