Markdown Badge
GitHub Badge Email Badge BuyMeACoffee Badge
Bronze

Comprehensive Markdown Guide

This document provides a comprehensive guide to Markdown syntax—a lightweight markup language used to format plain text.

Use this guide alongside a Markdown previewer or formatter to compare the rendered output with the original raw text for a better understanding of how Markdown works.

Table of Contents

Introduction

Markdown is a lightweight markup language that was created by John Gruber and Aaron Swartz in 2004. The primary goal of Markdown is readability—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.

Markdown has gained immense popularity over the years because of its simplicity and readability. It’s widely used for writing README files, documentation, blog posts, forums, and even in chat applications.

Why Use Markdown?

  • Readability: Markdown’s syntax is designed to be simple and intuitive.
  • Platform Independent: You can use Markdown in a text editor, in a web editor, or as the formatting syntax for entire platforms.
  • Rich Output: With simple syntax, you can produce rich text formatting.
  • Compatibility: Many platforms automatically convert Markdown to HTML, making it easy to display rich text in a web browser.
  • Extensible: While standard Markdown handles most common use cases, many platforms introduce their own extensions (called ‘flavors’) to add additional functionality like tables, code blocks, and more.

Headers

# H1
## H2
### H3
#### H4
##### H5
###### H6

H1

H2

H3

H4

H5
H6

Emphasis

*italic* or _italic_
**bold** or __bold__
**_bold and italic_**
~~strikethrough~~

italic or italic
bold or bold
bold and italic
strikethrough

Lists

Unordered Lists

* Item 1
* Item 2
  * Item 2a
  * Item 2b
  • Item 1
  • Item 2
    • Item 2a
    • Item 2b

Or using dashes:

- Item 1
- Item 2
  - Item 2a
  - Item 2b
  • Item 1
  • Item 2
    • Item 2a
    • Item 2b

Ordered Lists

1. Item 1
2. Item 2
3. Item 3
   1. Item 3a
   2. Item 3b
  1. Item 1
  2. Item 2
  3. Item 3
    1. Item 3a
    2. Item 3b
http://github.com
[GitHub with Title](http://github.com)

http://github.com
GitHub with Title

Code:

Inline code:

Here is `inline code`.

Here is inline code.

Block code without syntax highlighting:

```
This is a block of code.
```

This is a block of code.

Block code with syntax highlighting:

```python
print("Hello, world!")
```

print("Hello, world!")

Tables

| Header One     | Header Two     |
| -------------- | -------------- |
| Content Cell 1 | Content Cell 2 |
| Content Cell 3 | Content Cell 4 |
Header One Header Two
Content Cell 1 Content Cell 2
Content Cell 3 Content Cell 4

Horizontal Rules

Use three or more dashes, asterisks, or underscores:

---
***
___

Blockquotes

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

This is a blockquote.

This is a nested blockquote.

Inline HTML

<span style="color:red">This is red text.</span>
<div align="center">Centered Text</div>

This is red text.

Centered Text

Escaping Characters

Backslash escapes Markdown characters:

\*Not italic\*
\# Not a header

*Not italic*
# Not a header

Task Lists

In GitHub Flavored Markdown, you can create task lists:

- [x] Completed task
- [ ] Incomplete task
  • Incomplete task
  • Completed task

Footnotes

Some Markdown processors allow you to use footnotes, like so:

Here's a sentence with a footnote. [^1]
[^1]: This is the footnote.

Here’s a sentence with a footnote. 1

Definition Lists

Not universally supported, but useful where available:

Apple
:   Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
Orange
:   The fruit of an evergreen tree of the genus Citrus.

Apple
: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.

Automatic URL Linking

Most Markdown processors will automatically turn URLs into links:

http://www.example.com

http://www.example.com

Emojis

On platforms that support it (like GitHub), you can use shorthand for emojis:

:smile: :+1:

😄 👍

Math Equations

Some Markdown renderers like the one used by Jupyter Notebook support LaTeX for rendering math equations:

$$
E = mc^2
$$

$$ E = mc^2 $$

También en línea, como $E = mc^2$.

También en línea, como $E = mc^2$.

Abbreviations

Some extended Markdown processors allow abbreviations:

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

Citations

Certain academic Markdown variants allow citations in BibTeX format:

According to Smith [@smith04], blah blah...
[@smith04]: John Smith. 2004. The Book Title. Publisher Name.

According to Smith [@smith04], blah blah…
[@smith04]: John Smith. 2004. The Book Title. Publisher Name.

Alerts & Callouts

Use alerts/callouts to include additional content without breaking the flow of your notes.

Alerts

GitHub Flavored Markdown supports alerts that can be used to highlight important information:

  > [!NOTE]  
  > Highlights information that users should take into account, even when skimming.

  > [!TIP]
  > Optional information to help a user be more successful.

  > [!IMPORTANT]  
  > Crucial information necessary for users to succeed.

  > [!WARNING]  
  > Critical content demanding immediate user attention due to potential risks.

  > [!CAUTION]
  > Negative potential consequences of an action.

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Callouts

Other markdown editors have their own methods and features for Alerts/Callouts. For Obsidian, for example, check out their document here for more information.

Tags

Markdown editiors like Obsidian may support tags to organize your topics across multiple markdown documents:

#TestTag1 #TestTag2

TestTag1 #TestTag2

HTML Support

Most Markdown editors also support inline HTML, allowing you to incorporate elements that Markdown doesn’t natively support—such as tables with advanced formatting, custom divs, or embedded media.

Closing

Remember, not all of these features are supported in every Markdown processor. Always check your specific processor’s documentation for supported features.

You can use this as a README for your repository. Feel free to expand and improve the guide to better fit your requirements or to add more advanced features. Also, feel free to contribute and expand this guide for better community knowledge.

Resources

  • Markdown Guide - A free and open-source reference guide that explains how to use Markdown.
  • Daring Fireball - The original Markdown project by John Gruber.
  • GitHub Flavored Markdown - GitHub’s variant of Markdown, which includes features like task lists and tables.
  • CommonMark - A strong specification of Markdown, designed to clarify many edge cases and inconsistencies in the original Markdown specification.
  • Markdown Cheatsheet - A quick reference to Markdown syntax.
  • Pandoc - A universal document converter that supports Markdown and many other markup languages.
  • StackEdit - An in-browser Markdown editor.
  • Markdown Tutorial - An interactive tutorial to learn Markdown.
  • Jupyter Notebook - Although not strictly a Markdown resource, Jupyter Notebooks use Markdown for all non-code cells, making it a useful tool for scientific documentation where code and commentary are intermixed.
  • GitHub Markdown Alerts - A blog post that discusses the use of GitHub Markdown Alerts
  • GitHub Markdown Alerts Discussion - A GitHub discussion that discusses the use of GitHub Markdown Alerts
  • Obsidian Callouts - Use callouts to include additional content without breaking the flow of your notes.

License

This project is released under the terms of the MIT License, which permits use, modification, and distribution of the code, subject to the conditions outlined in the license. - The MIT License provides certain freedoms while preserving rights of attribution to the original creators. - For more details, see the LICENSE file in this repository. in this repository.

Credits

Author: Scott Grivner
Email: scott.grivner@gmail.com
Website: scottgrivner.dev
Reference: Main Branch

  1. This is the footnote. ↩