Master Markdown: Your Ultimate Guide
Are you ready to elevate your Markdown game? Dive into this comprehensive crash course designed to supercharge your Markdown skills and unleash your document formatting potential!
Benchmark Markdown Support
Benchmarking the support of Markdown with a comprehensive checklist
Are you working on a project featuring Markdown?
Drop the source of this page wherever you want to test or showcase the support of Markdown, and check that every single feature is properly rendered.
Basic formatting
Bold text
Syntax:
You can mark some text as bold with **two asterisks** or __two underscores__.
Output:
You can mark some text as bold with two asterisks or two underscores.
Italic
Syntax:
Use a *single asterisk* or a _single underscore_ for italic.
Output:
Use a single asterisk or a single underscore for italic.
Bold and italic
Syntax:
Three stars gives `***bold and italic***`
Three stars gives bold and italic
Strikethrough
Syntax:
By using \~~two tildes\~~ the text will be ~~striked through~~.
Output:
By using ~~two tildes~~ the text will be striked through.
Blockquotes
Syntax:
> blockquote
Output:
blockquote
Nested blockquotes
Syntax:
> First level
>
>> Second level
Output:
First level
Second level
Markdown in blockquotes
Syntax:
> **Markdown** can be used *inside quotes*
>
> 1. This is the first list item.
> 1. This is the second list item.
>
> ~~strikethrough~~
>
> Here's some example code:
>
> return shell_exec("echo $input | $markdown_script");
Output:
Markdown can be used inside quotes
- This is the first list item.
- This is the second list item.
strikethroughHere’s some example code:
return shell_exec("echo $input | $markdown_script");
Lists
Unordered list
Cant be marked with -, + or *
Syntax:
- First item
- Second item
- Third item
+ First item
+ Second item
+ Third item
* First item
* Second item
* Third item
Output:
- First item
- Second item
- Third item
- First item
- Second item
- Third item
- First item
- Second item
- Third item
Ordered lists
Incrementation is automatic, you can simply use 1. everywhere
Syntax:
1. First item
2. Second item
3. Third item
Output:
- First item
- Second item
- Third item
Nested list
Unordered
Syntax:
- First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item
Output:
- First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item
Ordered
Syntax:
1. First item
1. Second item
1. Third item
1. Indented item
1. Indented item
1. Fourth item
1. Fifth item
1. Indented item
1. Indented item
1. Indented item
Output:
- First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item
- Fifth item
- Indented item
- Indented item
- Indented item
Mixed
Syntax:
1. First item
1. Second item
1. Third item
* Indented item
* Indented item
1. Fourth item
1. Fifth item
1. Indented item
1. Indented item
1. Indented item
1. Indented item
* Indented
1. Indented item
* Indented
1. Indented item
* Indented
1. Indented item
1. Sixth item
Output:
- First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item
- Fifth item
- Indented item
- Indented item
- Indented item
- Indented item
- Indented
- Indented item
- Indented
- Indented item
- Indented item
- Indented
- Indented
- Indented item
- Sixth item
Linebreaks
When you hit enter just once between two lines, both lines are joined into a single paragraph.
But, if you leave a blank line between them, they will split into two paragraphs.
Demonstration:
Syntax:
This text is a paragraph.
This won't be another paragraph, it will join the line above it.
This will be another paragraph, as it has a blank line above it.
Output:
This text is a paragraph. This won’t be another paragraph, it will join the line above it.
This will be another paragraph, as it has a blank line above it.
Force line breaks
To force a line break, end a line with two or more whitespaces, and then type return.
Syntax:
This is the first line.··
Second line
Output:
This is the first line. Second line
Horizontal lines
Syntax:
Can be inserted with four *, - or _
----
****
____
Output:
Links
Basic links
Syntax:
[Semantic description](https://roneo.org/markdown)
<address@example.com>
<https://roneo.org/markdown> works too. Must be used for explicit links.
Output:
Semantic description address@example.com https://roneo.org/markdown works too. Must be used for explicit links.
Links using text reference
Syntax:
[I'm a link][Reference text]
[This link] will do the same as well. It works as the identifier itself.
[reference text]: https://jamstack.club
[this link]: https://roneo.org/markdown
Output:
This link will do the same as well. It works as the identifier itself.
Note: The reference text is not case sensitive
Link with a title on hover
Syntax:
[Random text][random-identifier].
Hover the mouse over it to see the title.
Several syntaxes are accepted:
[One](https://eff.org "First site")
[Two](https://example.com 'Second site')
[Three](https://example.com (Third site))
[random-identifier]: https://roneo.org/markdown "This example has a title"
Output:
Random text. Hover the mouse over it to see the title.
Several syntaxes are accepted: One Two Three
Links with Markdown style
To emphasize links, add asterisks before and after the brackets and parentheses.
Syntax:
I love supporting the **[EFF](https://eff.org)**.
This is the *[Markdown Guide](https://www.markdownguide.org)*.
To denote links as `code`, add backticks _inside_ the brackets:
See the section on [`code`](#code).
Output:
I love supporting the EFF. This is the
Markdown Guide. See the section on
code.
Attribute a custom anchor to a heading
Anchors are automatically generated based on the heading’s content. You can customize the anchor this way:
Syntax:
### Heading {#custom-id}
Output:
Heading
Code formatting
Inline
Wrap with single backticks to highlight as`code` → code
Codeblocks
Create a code block with three backticks ``` before and after your block of
code.
Syntax:
```bash
sudo apt hello
cat /etc/apt/sources.list
```
Output:
sudo apt hello
cat /etc/apt/sources.list
Also possible with a tabulation or four empty spaces at the beginning of the lines:
Tabulation
Syntax:
```bash
sudo apt hello
echo "hi"
**Four whitespaces**
sudo apt hello
Let's test the wrapping of a long line:
apt install test apt install test apt install test apt install test apt
install test apt install test apt install test apt install test apt install
test apt install test apt install test apt install test apt install test apt
install test
```
Output:
sudo apt hello
echo "hi"
**Four whitespaces**
sudo apt hello
Let's test the wrapping of a long line:
apt install test apt install test apt install test apt install test apt
install test apt install test apt install test apt install test apt install
test apt install test apt install test apt install test apt install test apt
install test
Codeblocks with syntax highlighting
Set the language right after the first backticks (for example html) to get
syntax highlighting
Samples
HTML
Syntax:
```html
<!DOCTYPE html>
<html lang="fr" itemscope itemtype="https://schema.org/WebPage">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, maximum-scale=1.0"
/>
</head>
</html>
```
Output:
<!DOCTYPE html>
<html lang="fr" itemscope itemtype="https://schema.org/WebPage">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, maximum-scale=1.0"
/>
</head>
</html>
CSS
Syntax:
```css
/* Comment */
.blog-post h2,
h3 {
margin-top: 1.6em;
margin-bottom: 0.8em;
}
```
Output:
/* Comment */
.blog-post h2,
h3 {
margin-top: 1.6em;
margin-bottom: 0.8em;
}
Bash
Syntax:
```bash
# Comment
if [[ ! $system =~ Linux|MacOS|BSD ]]; then
echo "This version of bashtop does not support $system platform."
sudo apt install test
```
Output:
# Comment
if [[ ! $system =~ Linux|MacOS|BSD ]]; then
echo "This version of bashtop does not support $system platform."
sudo apt install test
Diff
Syntax:
```diff
- delete
+ add
! test
# comment
```
Output:
- delete
+ add
! test
# comment
Escaping with backslashes
Any ASCII punctuation character may be escaped using a single backslash.
Example:
\*this is not italic*
Output:
*this is not italic*
Markdown provides backslash escapes for the following characters:
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
Images
Basic syntax
Note: The text inside the square brackets is important!
Screen reader users get informations about the image with this attribute called
ALT, for alternative text.
Including descriptive alt text
helps maintain accessibility for every
visitor and should always be included with an image. When you add alt text be
sure to describe the content and function of the picture. In addition to the
accessibility benefits, ALT is useful for SEO. It’s also displayed when, for
some reason, the picture is not loaded by the browser.
Image with title and caption
*Your caption*
Clickable images
For clickable images, simply wrap the image markup into a link markup:
[](https://homelab-alpha.nl)
Output:
Image with an identifier
You can call the image with an identifier as we do for links
![Semantic desc.][image identifier]
Lorem ipsum dolor sit amet consectetur adipisicing elit [...]
[image identifier]: https://raw.githubusercontent.com/homelab-alpha/docs/main/assets/images/logos/logo.png "Title"
Task lists
Syntax:
- [X] Write the press release
- [ ] Update the website
Output:
- Write the press release
- Update the website
Tables
Syntax:
| Syntax | Description |
| --------- | ----------- |
| Header | Title |
| Paragraph | Text |
or
| Syntax | Description |
| - | --- |
| Header | Title |
| Paragraph | Text|
will render the same way.
Output:
| Syntax | Description |
|---|---|
| Header | Title |
| Paragraph | Text |
Text alignment in tables
Syntax:
| Syntax | Description | Test Text |
| :-------- | :---------: | ----------: |
| Header | Title | Here's this |
| Paragraph | Text | And more |
See the way the text is aligned, depending on the position of ':'
Output:
| Syntax | Description | Test Text |
|---|---|---|
| Header | Title | Here’s this |
| Paragraph | Text | And more |
Footnotes
Syntax:
Here's a sentence with a footnote[^1].
(see the result at the bottom of the page)
[^1]: This is the first footnote.
Output:
Here’s a sentence with a footnote1. (see the result at the bottom of the page)
Long footnote
Syntax:
Here's a longer one.[^bignote]
(see the result at the bottom of the page)
[^bignote]: Here's one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
`{ my code }`
Note that you can place the footnote anywhere you want in your article
Output:
Here’s a longer one.2 (see the result at the bottom of the page)
Definition List
Syntax:
term
: definition
second term
: meaning
complex term
: long definition including **bold text**. Velit tempor cillum aute culpa
pariatur enim laboris consectetur tempor. Aute elit non do ipsum. Nisi quis
culpa magna esse ipsum. Ad aliquip ullamco minim cillum in ullamco.
Output:
term : definition
second term : meaning
complex term : long definition including bold text. Velit tempor cillum aute culpa pariatur enim laboris consectetur tempor. Aute elit non do ipsum. Nisi quis culpa magna esse ipsum. Ad aliquip ullamco minim cillum in ullamco.
Headings
Add ## at the beginning of a line to set as Heading. You can use up to 6 #
symbols for the corresponding Heading levels
Syntax:
## Heading 1
[...]
###### Heading 6
Output:
Heading 1
pedit quia voluptates atque nobis, perspiciatis deserunt perferendis, nostrum, voluptatem voluptas dolorem iure voluptatum? Accusantium a dolores dicta? Pariatur voluptates quam ut, cum aliquid eum, officiis laudantium totam suscipit, ducimus odit nobis! Corrupti, doloremque sed optio voluptatibus deserunt quas repellat eius minus quasi, ipsam unde esse sequi deleniti.
Heading 2
pedit quia voluptates atque nobis, perspiciatis deserunt perferendis, nostrum, voluptatem voluptas dolorem iure voluptatum? Accusantium a dolores dicta? Pariatur voluptates quam ut, cum aliquid eum, officiis laudantium totam suscipit, ducimus odit nobis! Corrupti, doloremque sed optio voluptatibus deserunt quas repellat eius minus quasi, ipsam unde esse sequi deleniti.
Heading 3
pedit quia voluptates atque nobis, perspiciatis deserunt perferendis, nostrum, voluptatem voluptas dolorem iure voluptatum? Accusantium a dolores dicta? Pariatur voluptates quam ut, cum aliquid eum, officiis laudantium totam suscipit, ducimus odit nobis! Corrupti, doloremque sed optio voluptatibus deserunt quas repellat eius minus quasi, ipsam unde esse sequi deleniti.
Heading 4
pedit quia voluptates atque nobis, perspiciatis deserunt perferendis, nostrum, voluptatem voluptas dolorem iure voluptatum? Accusantium a dolores dicta? Pariatur voluptates quam ut, cum aliquid eum, officiis laudantium totam suscipit, ducimus odit nobis! Corrupti, doloremque sed optio voluptatibus deserunt quas repellat eius minus quasi, ipsam unde esse sequi deleniti.
Heading 5
pedit quia voluptates atque nobis, perspiciatis deserunt perferendis, nostrum, voluptatem voluptas dolorem iure voluptatum? Accusantium a dolores dicta? Pariatur voluptates quam ut, cum aliquid eum, officiis laudantium totam suscipit, ducimus odit nobis! Corrupti, doloremque sed optio voluptatibus deserunt quas repellat eius minus quasi, ipsam unde esse sequi deleniti.
Heading 6
pedit quia voluptates atque nobis, perspiciatis deserunt perferendis, nostrum, voluptatem voluptas dolorem iure voluptatum? Accusantium a dolores dicta? Pariatur voluptates quam ut, cum aliquid eum, officiis laudantium totam suscipit, ducimus odit nobis! Corrupti, doloremque sed optio voluptatibus deserunt quas repellat eius minus quasi, ipsam unde esse sequi deleniti.
References
- Source of this page: github.com/RoneoOrg/markdown
- Markdown Guide - Basic Syntax
- Markdown Guide - Extended Syntax
- Daring Fireball: Markdown Syntax Documentation
- Markdown Guide at Gitlab.com
- CommonMark Spec
Related projects
Last updated 01 Sep 2024, 10:22 CEST .