Mastering Markdown

What is a Markup Language?

A markup language is a system for adding tags or annotations to text that describe its structure, formatting, or meaning.
The markup itself is usually not displayed to the reader; instead, it tells software how to present or process the content.
Example:-
1. HTML (Creates and structures web pages)
2. XML (Stores and transports structured data)
3. Markdown (Formats plain text into documents with simple syntax)
4. SVG (Describes vector graphics using markup)

<h1>Welcome</h1>                  <h1> indicates a heading.
<p>This is a paragraph.</p>       <p> indicates a paragraph

Markup Language vs Programming Language

Markup language describes the structure or presentation of content whereas programming language tells a computer what actions to perform.
Markup language uses tags or markup whereas programming language uses variables, loops, functions, and conditions.
Markup language does not perform calculations or make decisions whereas programming language can perform calculations, make decisions, and execute logic.
Markup languages: HTML, XML, Markdown, etc.
Programming languages: Python, Java, C++, JavaScript, etc.

What is WYSIWYG editor?

WYSIWYG stands for “What You See Is What You Get”.
It refers to an editor where the content looks approximately the same while you’re editing it as it will look when it’s finally displayed or published.
In WYSIWYG editor you write visually formatted content where the editor immediately shows the formatting in the editor itself like a bold text or large font.
Example: Microsoft Word, Google Docs, etc.

Why use Markdown?

It was created by John Gruber in 2004 and is now the world’s most popular languages. According to Gruber, markdown syntax is designed to be readable even if it isn’t rendered.
It is portable unlike the WYSIWYG editors which locks the content into proprietary file format. The files with markdown formatted text can be opened in any markdown application.
Markdown is platform independent. You can create Markdown-formatted text on any device running any operating system.
Markdown is future proof. Even if the application you’re using stops working at some point in the future, you’ll still be able to read your Markdown-formatted text using a text editing application.
The core purpose of Markdown is to write structured, formatted text in a simple, readable plain-text format. Common uses include:
1. 🌐 Web Pages & Blogs (Markdown can be converted to HTML.)
2. 📚 Documentation (GitHub README files, technical docs, API documentation.)
3. 📝 Notes (apps like Obsidian, Joplin, and many note-taking tools.)
4. 💻 Software Projects (README.md, CONTRIBUTING.md, CHANGELOG.md, etc.)
5. 💬 Communication (Reddit, Discord, Slack, forums, etc. support Markdown-like formatting.)
6. 🤖 AI/LLMs (Markdown is widely used to structure prompts and model responses.)
7. 📄 Publishing (Markdown can be converted to HTML, PDF, DOCX, EPUB, and other formats.)

JotBird

It is a browser-based Markdown editor where you can practice writing Markdown and instantly see the formatted result on the right side.
It is also a zero-friction publishing tool that lets you turn plain text Markdown into a shareable web page in seconds.
It was created by Matt Cone, the author of the popular resource The Markdown Guide. This article is essentially a revision over his original Markdown Guide along with the basics and other latest resources.

Heading Syntax

Headings are created using hash (#) symbols at the beginning of a line. The number of hash (#) symbols determines the heading level.

Alternatively, on the line below the text, add any number of equal sign (=) for heading level 1 and hyphen (-) for heading level 2.

Markdown Syntax	Alternate Syntax
# Heading Level 1	Heading Level 1 ===========
## Heading Level 2	Heading Level 2 —————––
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

Always use a space between hash (#) and heading name because different markdown applications might treat it differently.
```
#Heading ABC              ❌ Wrong
# Heading XYZ             ✅ Correct
```
Also, put blank lines before and after a heading for compatibility across different markdown applications.
```
Try to put a blank line before...

# Heading ABC

...and after a heading.
```

Paragraph Syntax

No special syntax is required for writing a paragraph, just write the text normally.
Leave a blank line between paragraphs to create a line break but it doesn’t always promise to create a new paragraph as it depends on which markdown application you are using.
To force a line break within the same paragraph, use two spaces at the end of the line or <br>.
Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs as it can result in unexpected formatting problems.
Sometimes you might see a backslash (\) at the end of the line to create a line break but not all markdown applications support this, so it’s better to avoid this for any compatibility issues.

Emphasis Syntax

Italic: To make a piece of text italic, you can use an asterisk (*) or an underscore (_) before and after it.
Bold: To make a piece of text bold, you can use two asterisks (**) or two underscores (__) before and after it.
Bold & Italic: To make a piece of text bold, you can use three asterisks (***) or three underscores (___) before and after it.

Different markdown applications handle the underscores in middle of texts differently so it’s better to avoid underscores to emphasize any such piece of text and use asterisk instead.

Blockquote Syntax

Blockquotes are used to quote or highlight text. They are created using the greater-than sign (>).
```
> This is a blockquote.
```
renders as:

This is a blockquote.
Multiple Paragraphs
```
> This is 1st paragraph.
>
> This is 2nd paragraph.
```
renders as:

This is first paragraph.

This is second paragraph.
Nested Blockquotes
```
> Quote
>> Nested Quote 1
>>> Nested Quoted 2
```
renders as:

Quote

Nested Quote 1

Nested Quoted 2
Blockquotes can contain other markdown elements like bold, italic, lists, links, etc.
It’s always best practice to put blank lines before and after blockquotes.

List Syntax

Markdown supports unordered lists, ordered lists, and nested lists.

Ordered Lists: Use a number followed by a period and a space.
```
1. Apple
2. Kiwi
2. Banana
4. Mango
```
1. Apple
2. Kiwi
3. Banana
4. Mango
Most markdown parsers will automatically number the output, even if you number it in wrong order but the list should start with the number one.

Few parsers let you use a parenthesis ()) as delimiter instead of a period but it is less common.

To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab.
Unordered Lists: Use -, *, or + followed by a space.
```
- Apple
- Kiwi
* Banana
+ Mango
```
- Apple
- Kiwi
- Banana
- Mango
If you need to start an unordered list item with a number followed by a period, you can use a backslash (\) to escape the period.
```
- 2026\. This year changed space exploration forever.
- In April 2026, NASA successfully launched the Artemis II mission.
```
- 2026. This year changed space exploration forever.
- In April 2026, NASA successfully launched the Artemis II mission.

Nested Lists: Indent the nested items.

- Fruits
  1. Apple
  2. Banana
  3. Mango
- Vegetables
  1. Potato
  1. Carrot
  1. Beans

Fruits
1. Apple
2. Banana
3. Mango
Vegetables
1. Potato
2. Carrot
3. Beans

Task Lists ¹ : Many markdown implementations support checkboxes.
```
- [x] Learn Markdown
- [ ] Learn HTML
- [ ] Learn CSS
```
- Learn Markdown
- Learn HTML
- Learn CSS

Code Block Syntax

Fenced Code Blocks ¹ : Use three backticks (```) before and after the code. Put the language name immediately after the opening backticks to specify the programming language.
```
```python
def hello():
    print("Hello, World!")
```
```
renders as:
```
def hello():
    print("Hello, World!")
```
Backticks Inside Code: If the code itself contains three backticks, you can use four or more backticks to create the outer code fence.
```
````
Here is ```some``` code inside.
````
```
Inline Code: Use single backticks for short pieces of code within a sentence.
```
Use the `print()` function to display text.
```
Use the print() function to display text.
Escaping Backticks: If the word or phrase you want to denote as code includes one or more backticks, you can escape it by enclosing the word or phrase in double backticks (``).
```
``The keyword `print()` is used to display text.``
```
The keyword `print()` is used to display text.
Indented Code Blocks: Older/alternative Markdown syntax allows four spaces of indentation.
```
    def hello():
        print("Hello")
```
def hello(): print(“Hello”)

Horizontal Rule Syntax

A horizontal rule (also called a horizontal line or thematic break) creates a visual divider between sections.
To create a horizontal rule, use three or more asterisks (***), dashes (—), or underscores (___).
You can add spaces between the characters but don’t mix the characters.
For compatibility, put blank lines before and after horizontal rules.

Link Syntax

Basic Link: use square brackets [] for the link text and parentheses () for the URL.
```
[Google](https://google.com)
```
Google
Link with a title: You can optionally add a title inside the parentheses. The title usually appears as a tooltip when you hover over the link.
```
[Google](https://google.com "Google Search Engine")
```
Google
URL with spaces: URLs generally should not contain unencoded spaces. But if there is a space then use %20 or another valid URL encoding.
```
[Google Search for "hello world"](https://www.google.com/search?q=hello%20world)
```
Google Search for “hello world”
URL with parentheses: Encode the opening parenthesis (() with %28 and the closing parenthesis ()) with %29. Alternatively, we can escape the parenthesis using \ or wrap the URL in angle brackets < ...url... >.
```
[Wikipedia - Markdown](https://en.wikipedia.org/wiki/Markdown_%28markup_language%29)
[Wikipedia - Markdown](https://en.wikipedia.org/wiki/Markdown_\(markup_language\))
[Wikipedia - Markdown](<https://en.wikipedia.org/wiki/Markdown_(markup_language)>)
```
Wikipedia - Markdown
Wikipedia - Markdown
Wikipedia - Markdown
Email Links: Use mailto
```
[Email Me](mailto:info@example.com)
```
Email Me
Automatic Links ¹ : Some Markdown implementations support angle brackets around URLs which automatically makes them a clickable link.
```
https://google.com
<https://google.com>
<mailto:info@example.com>
`mailto:info@example.com`
```
https://google.com
https://google.com
mailto:info@example.com
mailto:info@example.com

Disabling Automatic URL Linking

If you don’t want a URL to be automatically linked, you can remove the link by denoting the URL as code with backticks.
Reference Style Links: A reference-style link separates the link text from the URL definition. This makes your Markdown cleaner, especially when the same URL is used multiple times. The label, in brackets, followed immediately by a colon and at least one space. URL for the link can be optionally enclosed in angle brackets. The optional title for the link can be enclosed in double quotes, single quotes, or parentheses.
```
[Google][1]
[Gmail][mail]
[Google Drive][]

[1]: https://google.com "Google Search Engine"
[mail]: <https://gmail.com> (Mail Service)
[Google Drive]: https://drive.google.com 'Googel Drive'
```
Google
Gmail
Google Drive

Links can contain formatting for changing their appearances.

Image Syntax

Images uses almost the same syntax as links but adds an exclamation mark ! at the beginning.
It can contain a path or URL to the image.
You can optionally add a title in quotation marks after the path or URL.
```
![Logo](https://rishabhkrsah.in/images/favicon-lg.png "Logo")
```

Escape Characters

Escaping in Markdown is used when you want to display a character literally instead of allowing Markdown to interpret it as formatting syntax.
The escape character in Markdown is the backslash (\).
```
*This text is italic.*
\*This text is not italic.\*
```
This text is italic.
*This text is not italic.*
CommonMark defines a set of ASCII punctuation characters that can be escaped with a backslash:
```
\ ` * _ { } [ ] ( ) # + - . ! | > ~
```

Comment Syntax

Markdown does not have a dedicated, standardized comment syntax in the original Markdown specification or CommonMark.
There are some markdown hacks which are not an official comment syntax. Some markdown processors may interpret it as an invisible link/reference, but it is not a standardized Markdown feature.
```
[This is a comment that will be hidden.]: #
[//]: # (This is sometimes used as a Markdown comment.)
```

Visible Space Syntax ¹

Markdown uses spaces and indentation to determine the structure of certain elements.
Unlike ordinary text formatting, whitespace can sometimes change how Markdown is parsed.
Usually, ordinary spaces in Markdown are usually collapsed while rendering by the parser.
The code block syntax preserves the actual text formatting inside it which can be used in some places.
Alternatively, we can use Unicode En, Em and Non-breaking space for a visible extra space in the text. They produces spaces whose width are different than normal space.
```
HelloWorld
Hello World
Hello&nbsp;World
Hello&emsp;World
```
HelloWorld
Hello World
Hello World
Hello World
Hello World

Table Syntax ¹

Use pipes (|) to separate columns and hyphens (-) to separate the header from the table body.
You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.
```
| Items | Uq. Code | Category | Color |
|------:|:--------:|----------|------:|
| Apple | 28 | Fruit | Red |
| Banana | 30 | Fruit | Yellow |
| Lettuce | 25 | Salad | Green |
```
Items Uq. Code Category Color

Apple 28 Fruit Red

Banana 30 Fruit Yellow

Lettuce 25 Salad Green
You can separate paragraphs within a table cell by using one or more
HTML tags.

Items	Uq. Code	Category	Color
Apple	28	Fruit	Red
Banana	30	Fruit	Yellow
Lettuce	25	Salad	Green

You can add a list within a table cell by using HTML tags.

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title |
| Paragraph   | First paragraph. <br><br> Second paragraph. |
| List        | Here's a list! <ul><li>Item one.</li><li>Item two.</li></ul> |

Syntax	Description
Header	Title
Paragraph	First paragraph. Second paragraph.
List	Here’s a list! Item one. Item two.

Creating tables with hyphens and pipes can be tedious. To speed up the process, try using the Markdown Tables Generator or AnyWayData Markdown Export. Build a table using the graphical interface, and then copy the generated Markdown-formatted text into your file.

You can format the text within tables. For example, you can add links, code (words or phrases in backticks (`) only, not code blocks), and emphasis. You can’t use headings, blockquotes, lists, horizontal rules, images, or most HTML tags.

Heading ID Syntax ¹

Many Markdown processors automatically generate an ID from the heading.
```
# Introduction
```
may become:
```
<h1 id="introduction">Introduction</h1>
```
Some Markdown implementations allow you to specify the custom ID explicitly. Enclose the custom ID in curly braces on the same line as the heading.
```
# Introduction {#intro}
```
and then reference it with:
```
[Go to Introduction](#intro)
```
Go to Introduction

Definition List Syntax ¹

A definition list is a type of list used to associate a term with its definition or description.
Unlike an unordered list or ordered list, a definition list has two distinct parts:
1. Term - the thing being defined.
2. Definition - the explanation of that term.
To create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the definition.
Some implementations may allow a term to have multiple definitions or one definition to have multiple terms.
```
Markdown
: A lightweight markup language.
: A plain text formatting language.

HTML
HyperText Markup Language
: A markup language used to structure web pages.

CSS
: A language used to style web pages.
```
Markdown

A lightweight markup language.
A plain text formatting language.

HTML

HyperText Markup Language

A markup language used to structure web pages.

CSS

A language used to style web pages.

Emoji Syntax ¹

Unicode Emoji: You can simply copy an emoji from a source like Emojipedia and paste it into your document.
```
I love Markdown ❤️
This is great 🚀
Markdown is easy to learn 👍
```
Emoji Shortcodes: To insert emoji shortcodes type emoji name surrounded by colons (:).
```
:smile:
:heart:
:+1:
```
:smile:
:heart:
:+1:

Markdown doesn’t provide special syntax for symbols. However, in most cases, you can copy and paste whatever symbol you want to use into your Markdown document. For example, if you need to display Pi (π), just find the symbol on a webpage and copy and paste it into your document. The symbol should appear as expected in the rendered output.

Strikethrough Syntax ¹

Strikethrough displays text with a horizontal line through it, usually to indicate that the text has been deleted, removed, or is no longer applicable.
To strikethrough, use two tilde symbols (~~) before and after any word or a phrase.
```
This is ~~incorrect~~ correct.
```
This is ~~incorrect~~ correct.

Highlight Syntax ¹

Highlighting is used to display text with a background highlight, similar to using a text highlighter.
To highlight words, use two equal signs (==) before and after the words.
```
This is ==important==.
```
This is ==important==.

Subscript Syntax ¹

Subscript displays text or numbers slightly below the normal baseline. It is commonly used in chemical formulas, mathematical expressions, and scientific notation.
To create a subscript, use one tilde symbol (~) before and after the characters.
```
H~2~O
```
H2O

Superscript Syntax ¹

Superscript displays text or numbers slightly above the normal baseline. It is commonly used for exponents, mathematical expressions, and ordinal numbers.
To create a superscript, use one caret symbol (^) before and after the characters.
```
X^2^
```
X^2^

Footnote Syntax ¹

Footnotes in markdown are similar to footnotes in books or academic papers that provide additional information, explanations, references, or sources without interrupting the main text.
```
- Markdown is a lightweight markup language.[^john_gruber]
- It was designed to be easy to read in its raw form.[^2]
```
- Markdown is a lightweight markup language.²
- It was designed to be easy to read in its raw form.³
The identifier doesn’t have to be a number; we can use descriptive identifiers like we have used john_gruber here. The identifier is only used internally; the rendered output generally displays a numbered footnote.

Formatting in Markdown

Not every Markdown element can be formatted in the same way, and this is where it’s useful to distinguish content syntax, inline formatting, and styling.

HTML Syntax

Many Markdown implementations allow HTML to be embedded directly within Markdown. However, HTML support varies between implementations, and applications may sanitize or restrict certain HTML elements and attributes for security reasons. Therefore, HTML should not be assumed to work identically across all Markdown applications.

Not all the syntax mentioned on this page are included in the original/core Markdown syntax. Some of them are an extension supported by particular Markdown parsers. There isn’t just one implementation of Markdown. Different Markdown based languages extend the basic Markdown syntax with additional features.
- Original Markdown: Core Markdown syntax having John Gruber’s original implementation.
- CommonMark: Precisely defined core syntax standardized across Markdown parsers.
- GitHub Flavored Markdown (GFM): Extends tables, task lists, strikethrough, autolinks, fenced code blocks used in GitHub, GitHub Pages.
- Markdown Extra: Extends tables, footnotes, fenced code, attributes, definition lists for PHP markdown ecosystem.
- MultiMarkdown: Extends tables, footnotes, citations, metadata, cross-references for documents and publishing.
- Pandoc Markdown: Extends footnotes, tables, citations, math, attributes, definition lists used for technical and educational document conversion.
- R Markdown: Combines markdown + executable R code + scientific/analytical output used for R in data science.
- Quarto Markdown: Combines markdown + executable code + citations + cross-references + diagrams used for scientific & technical publishing.
- MyST Markdown: Combines markdown + directives + roles + cross-references + rich documentation features used for scientific & technical documentation.
- Kramdown: Extends tables, footnotes, math, attributes, block extensions for Jekyll / Ruby ecosystem.
- Textile: Markdown-like lightweight markup, but technically a separate markup language used for web publishing.
- CommonMark + Extensions: CommonMark core with application-specific extensions provided by modern markdown applications. Also, there are dozens of Markdown processors available and many of them allow you to add extensions that enable extended syntax elements.
- MDX: It extends Markdown with JSX/JavaScript capabilities. It is particularly relevant if you’re learning Astro, React, or modern documentation/blog systems.
↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³
It was created by John Gruber in 2004. ↩
Markdown syntax was designed to remain readable as plain text. ↩

Mastering Markdown

What is a Markup Language?

Markup Language vs Programming Language

What is WYSIWYG editor?

Why use Markdown?

JotBird

Heading Syntax

Paragraph Syntax

Emphasis Syntax

Blockquote Syntax

List Syntax

Code Block Syntax

Horizontal Rule Syntax

Link Syntax

Disabling Automatic URL Linking

Image Syntax

Escape Characters

Comment Syntax

Visible Space Syntax 1

Table Syntax 1

Heading ID Syntax 1

Definition List Syntax 1

Markdown

HTML

HyperText Markup Language

CSS

Emoji Syntax 1

Strikethrough Syntax 1

Highlight Syntax 1

Subscript Syntax 1

Superscript Syntax 1

Footnote Syntax 1