Ultimate Markdown Syntax Guide: From Basics to Advanced
Learn Markdown syntax with this comprehensive guide covering basic to advance headings, lists, links, images, tables, and more.
Introduction
If you write blogs, create GitHub README files, or work on documentation, you have probably heard about Markdown. It’s a very simple way to write and format text without learning complicated HTML. Many people love Markdown because it keeps writing clean, fast, and focused on the content. Instead of getting lost in tags or design, you can just write your thoughts and let Markdown handle the formatting.
The best part is that Markdown works in many places like GitHub, blogging platforms, documentation tools, and even simple note apps like Obsidian and VS Code. This makes it one of the most useful skills for students, writers, and developers. But at the same time, beginners often face problems like not remembering all the Markdown syntax or not knowing which features are supported on GitHub or in blogs.
In this guide, I will walk you through every part of Markdown step by step. We will start with basic Markdown syntax like headings, bold, italic, lists, and links. Then we will also explore advanced Markdown features such as tables, code highlighting, emojis, diagrams, and even math formulas. By the end, you will have a complete Markdown cheatsheet that you can use anytime for blogging, GitHub, or any writing project.
Problems Faced With Markdown Formatting
When people start writing online, they usually run into the same problems again and again. If you have ever tried to write with plain HTML, you know how messy it feels. Too many tags, closing brackets, and small mistakes can break your page. This makes writing slow and frustrating.
Another common problem is that every platform looks different. What works in one editor does not always work in GitHub or on your blog. For example, some blogs support Markdown tables, but others don’t. So writers spend extra time fixing the same text for each platform. This can feel like wasted effort when all you wanted was a simple, clean format.
Even students and casual writers face trouble. They just want to take quick notes, but formatting in apps can get in the way. Instead of focusing on ideas, they get distracted with toolbars, fonts, and styles. This kills the flow of writing.
That’s where Markdown solves everything. It removes these daily struggles by giving you one simple set of rules that work across GitHub, blogs, and documentation tools. You don’t need to fight with HTML or waste time adjusting formatting again and again.
What is Markdown? A Beginner's Guide
Markdown is a simple markup language that lets you format text using plain text characters. Created by John Gruber in 2004, markdown allows you to write using easy-to-read and easy-to-write plain text that converts to clean HTML.
Why Markdown is Popular
Markdown is popular because it's easy to read and write. It's also lightweight and portable. Many people use it for blogging, documentation, and GitHub README files.
The Goal of This Guide and Problems With Markdown
While Markdown makes writing much easier than HTML, it also comes with its own small problems. One of the biggest issues for beginners is that you need to remember the syntax. For example, do you use one star or two stars for bold? Or how do you add a link with a title? When you forget these small rules, it slows you down and breaks your flow.
Another problem is that not every platform supports every feature. For example, GitHub Markdown has emojis, mentions, and task lists, but many blogging platforms don’t. This can confuse new users who expect Markdown to always work the same everywhere.
The goal of this guide is to make Markdown easy for everyone. You will not only learn the basic Markdown syntax but also discover advanced Markdown features and which platforms support them. This way, you can write once with confidence and know exactly how it will look on your blog, in GitHub, or in your notes.
Complete Markdown Syntax Guide (Basic, Advanced, and Add-ons)
Now that we understand why Markdown is so useful, it’s time to explore the actual Markdown syntax. In this part, I will show you every Markdown feature step by step. We will start with basic Markdown syntax that works almost everywhere, then move on to advanced Markdown features that give you more control, and finally look at add-ons that are supported in special platforms like GitHub, Obsidian, or blogging tools.
Basic Markdown Syntax
- Headings
- Paragraphs and Line Breaks
- Bold Text
- Italic Text
- Strikethrough
- Blockquotes
- Lists (ordered, unordered, nested)
- Task Lists (checkboxes)
- Links (with and without title)
- Images (with and without title)
- Inline Code
- Code Blocks (with triple backticks)
- Horizontal Rules
- Tables
- Escaping Characters
- Inline HTML
Advanced Markdown Syntax
- Footnotes
- Definition Lists
- Syntax Highlighting in Code Blocks
- Tables with Alignment
- Automatic Links
- Heading IDs and Anchor Links
- Images with Links
- Extended Blockquotes (multi-paragraph)
Markdown Add-ons (Platform Specific)
- Emoji (GitHub flavored)
- Mentions and References (@username, #issue)
- Diagrams with Mermaid.js
- Math Equations with LaTeX/KaTeX
- Collapsible Sections (details/summary)
- Keyboard Keys (like <kbd>Ctrl</kbd>)
- Callouts or Admonitions (docs and plugins)
- HTML Embeds (iframes, videos)
Heading Syntax
Headings are used to create titles and sub-titles.
Purpose: They give structure to content and improve readability and SEO.
Use Case: Use H1 for page title, H2 for sections, H3 for
Platform Support: Works on GitHub, blogs, docs, and note-taking apps.
# H1, ## H2, ### H3, #### H4, ##### H5, ###### H6#### H4, ##### H5, ###### H6Markdown Content
# Complete Markdown Syntax Guide (H1)
## Basics (H2)
### Headings (H3)
#### Small Subsection (H4)
##### Note (H5)
###### Smallest Heading (H6)List Syntax
Lists are used to group related items in bullets or steps.Purpose: Make information scannable and organized.
Platform Support: Works on GitHub, blogs, docs, note apps.
Types:
Unordered List: Bullets with- or *Ordered List: Numbered steps with
1., 2.Nested List: Indented items under a main item.
Syntax
- Bullet item, * Bullet item, 1. Numbered item, - Nested bullet, - Nested bulletMarkdown Content
- Features (unordered list)
- Fast
- Simple
- Lightweight
1. Install the app (ordered list)
2. Open settings
1. Choose option A (nested list)
2. Choose option B
3. Start usingBold and Italic Syntax
Bold and italic text in Markdown are used to highlight important words or add emphasis. Bold is typically used to strongly emphasize keywords, commands, or warnings, while italic is better suited for soft stress or highlighting a single word or phrase. You can also combine both for very strong focus.
These styles are commonly used to draw attention to notes in blogs or documentation, show keyboard shortcuts or commands, and add emphasis in tutorials, readme files, or personal notes. This syntax works seamlessly across platforms like GitHub, WordPress, Hashnode, Dev.to, Docsify, Docusaurus, Notion, Obsidian, and Typora.
Syntax
*italic*, _italic_, **bold**, __bold__, ***bold and italic***, ___bold and italic___
Markdown Content
# Examples of Bold & Italic
This is *italic text*
This is _also italic_
This is **bold text**
This is __also bold__
This is ***bold and italic***
This is ___another bold and italic___
# Real-world use case
**Warning:** Make sure to save your file before exiting.
Use *italics* to highlight a filename like *config.json*.Paragraph and Line Break Syntax
Paragraphs in Markdown are blocks of text separated by a blank line, making them ideal for writing normal content like explanations, notes, or documentation.
Line breaks allow you to move to a new line within the same paragraph—useful for formatting poetry, addresses, or commands. This syntax is widely supported across platforms including GitHub, blogs, documentation tools, and note-taking apps.
Syntax
Paragraph text, New paragraph (leave one blank line), Line 1 (end with two spaces␣␣), Line 2
Markdown Content
# Paragraph Example
This is the first paragraph.
It talks about Markdown basics and why it's useful.
This is the second paragraph.
Notice how we left one blank line above.
# Line Break Example
Roses are red,
Violets are blue,
Markdown is simple,
And powerful too.Strikethrough Syntax
Strikethrough adds a horizontal line through text, making it useful for visually indicating that content has been deleted, outdated, or corrected while still keeping it readable.
It is commonly used to show corrections in documentation, mark invalid items in to-do lists, or display old vs new prices in blogs and product pages. This syntax is supported on GitHub, most modern blogs, documentation tools, and note-taking apps, though some older Markdown parsers may not support it.
Syntax
~~strikethrough~~
Markdown Content
# Strikethrough Example
This is normal text.
This is ~~strikethrough text~~.
# Real-world use cases
- ~~Old feature~~ New feature is better
- ~~$99~~ $79 (discounted price)
- ~~Pending~~ CompletedBlockquote Syntax
Blockquotes are used to highlight quoted text or special notes by visually separating them from the main content. They are ideal for displaying quotations from books, articles, or individuals, and for emphasizing tips, warnings, or important notes in blogs and documentation.
Common use cases include quoting authors or official sources, adding sections like "Pro Tip", "Note", or "Warning", and formatting replies in GitHub issues or discussions. Blockquotes are fully supported across platforms such as GitHub, blogs, documentation tools, and most modern note-taking apps.
Syntax
> Quoted text, > Nested blockquote, >>> Multiple nested blockquotes
Markdown Content
# Blockquote Examples
> This is a simple blockquote.
> Markdown is easy to learn and widely used.
> – Common Developer Saying
# Nested Blockquote
> This is the first level
>> This is the second level
>>> This is the third level
# Real-world use case
> 💡 Pro Tip: Always commit small changes frequently.
> ⚠️ Warning: Do not share your API keys publicly.Task List / Check Box Syntax
Task lists in Markdown allow you to create interactive checkboxes that can be marked as complete or incomplete. This feature is especially useful for organizing tasks and tracking progress in both personal and collaborative projects.
They are commonly used to
- Track tasks, to-dos, and progress in projects
- Show step-by-step actions in tutorials or documentation
- Organize work inside GitHub issues, pull requests, and project boards
Additional use cases include
- Creating a publishing checklist for bloggers
- Maintaining a feature checklist in a project’s README file
- Managing team tasks and tracking completion in GitHub
Platform support includes
- GitHub: Fully supports task lists with clickable checkboxes
- Docs & Blogs: Most modern documentation tools and blogs support them
- Basic Renderers: Some Markdown parsers only display them as plain text
Syntax
- [ ] Task not done, - [x] Task completed
Markdown Content
# Task List Example
- [ ] Write the blog draft
- [ ] Add images
- [x] Research Markdown syntax
- [x] Create outline
- [ ] Publish article
# Real-world Project Checklist
**Project Setup**
- [x] Install Node.js
- [x] Install dependencies
- [ ] Configure environment variables
- [ ] Run tests
- [ ] Deploy to productionLink Syntax
Links in Markdown allow you to connect to web pages, documents, or sections within the same page. This makes it easy to reference external resources, navigate long documents, or provide additional context using optional title attributes that appear as tooltips on hover.
Links are commonly used to:
- Connect readers to external websites or resources
- Create navigation inside the same page or document
- Add context with a title attribute
Use Cases:
- Adding references in blogs or articles
- Creating documentation with quick navigation to sections
- Linking to files, images, or related resources inside GitHub projects
Platform Support:
- GitHub: Fully supports links with or without titles
- Blogs & Docs: WordPress, Dev.to, Hashnode, and documentation tools render links perfectly
- Note-taking apps: Apps like Obsidian and Notion support both internal and external links
Benefits of Using Titles:
- Accessibility: Screen readers can read the title for better context
- User Experience: Provides extra info when hovering over a link
- SEO: Helps search engines understand the link’s purpose
Syntax
[Link Text](URL), [Link Text](URL "Optional Title"), [Internal Link](#section-name)
Markdown Content
# Link Examples
Regular Link:
[ReadmeCodeGen](https://readmecodegen.vercel.app)
Link with Title (shows on hover):
[Google](https://www.google.com "Search Engine")
Internal Link (jump inside the same page):
[Go to Headings Section](#heading-syntax)
# Real-world Use Cases
- Learn more on [GitHub Docs](https://docs.github.com "GitHub Documentation")
- Visit [Markdown Guide](https://www.markdownguide.org) for complete reference.
- Jump to [Task List Section](#task-list--check-box-syntax) inside this document.Image Syntax
Images in Markdown allow you to display pictures directly within your content using a simple and intuitive syntax. This enhances the visual appeal of your writing and makes technical or instructional material easier to understand.
Images are commonly used to:
- Make blogs, docs, and articles more engaging with visuals
- Explain ideas better using diagrams, screenshots, or infographics
- Add branding elements like logos or banners inside documentation or projects
Use Cases:
- Adding screenshots to explain tutorial steps
- Displaying architecture diagrams in README files
- Using product images, feature charts, or marketing visuals
Platform Support:
- GitHub: Supports both local image files and external links
- Docs & Blogs: Platforms like WordPress, Hashnode, and Dev.to render Markdown images effectively
- Note-taking apps: Tools such as Notion, Obsidian, and Jupyter Notebooks support image embedding
Benefits of Alt Text and Title:
- Alt Text: Improves accessibility for screen readers and boosts SEO
- Title: Displays additional info when hovering over the image
- SEO: Helps search engines understand image content for better ranking
Syntax
, , [](link-url)
Markdown Content
# Image Examples
Basic Image:
Image with Title (hover text):
Clickable Image (image as a link):
[](https://github.com)
# Real-world use cases
- Add screenshots in tutorials:
- Show product logos in documentation:
- Make images clickable to redirect to resources.Image Examples
Basic Image:
Image with Title (hover text):
Clickable Image (image as a link):
Real-world use cases
-
Add screenshots in tutorials:
-
Show product logos in documentation:
-
Make images clickable to redirect to resources.
Table Syntax
Tables in Markdown help you organize and present information in rows and columns. They are especially useful for displaying structured data in a clean, readable format, making documentation and reports easier to digest.
Tables are commonly used to:
- Display product comparisons, feature lists, or schedules
- Make documentation easy to read with neatly arranged rows and columns
- Create reports or specifications in a text-based format
Use Cases:
- Comparing features of two products
- Displaying pricing tables in a blog post
- Organizing task responsibilities in documentation
Platform Support:
- GitHub: Fully supports Markdown tables
- Docs & Blogs: Platforms like Dev.to, Hashnode, and GitBook support them
- Basic Renderers: Some older Markdown parsers may not support tables
How to Create Tables:
- Header Row: Use
|(pipe symbol) with---underlining - Columns: Separate each column using
| - Alignment:
---:→ Right align:---:→ Center align:---→ Left align
Syntax
| Column 1 | Column 2 | Column 3 ||----------|----------|----------|| Data 1 | Data 2 | Data 3 |
Markdown Content
# Table Examples
Basic Table:
| Name | Age | Country |
|----------|-----|-----------|
| Sonu | 21 | India |
| Alice | 25 | USA |
| Bob | 30 | Canada |
Aligned Table:
| Product | Price | Stock |
|:---------|------:|:-----:|
| Laptop | $800 | Yes |
| Monitor | $200 | No |
| Keyboard | $50 | Yes |
Real-world Use Case (College Timetable):
| Day | Subject | Time |
|-----------|-----------------|--------------|
| Monday | Computer Science| 10:00 - 11:00|
| Tuesday | Math | 09:00 - 10:00|
| Wednesday | Physics | 11:00 - 12:00|Horizontal Rule Syntax
Horizontal rules in Markdown are lines used to separate sections of content. They help break up text visually, making documents easier to read and navigate.
Horizontal rules are commonly used to:
- Visually separate different sections of a document
- Improve readability by dividing content into parts
- Act as dividers between unrelated topics in blogs or documentation
Use Cases:
- Separating the introduction from the main content in blogs
- Dividing chapters or sections in documentation
- Splitting multiple ideas clearly in personal notes
Platform Support:
- GitHub: Fully supports horizontal rules
- Docs & Blogs: Compatible with nearly all Markdown renderers
- Note-taking apps: Supported in Notion, Obsidian, Jupyter, and more
Syntax Options:
---***___
Markdown Content
# Horizontal Rule Example
This is section one.
---
This is section two.
***
This is section three.
___
This is section four.
# Real-world usage
Blog Post Example:
Intro text about the topic.
---
Main content starts here.Inline Code & Code Block Syntax
Inline code and code blocks in Markdown let you display programming code, commands, or snippets clearly. They’re essential for tutorials, documentation, and technical writing.
They are commonly used to:
- Inline Code: Highlight short code inside a sentence
- Code Block: Show longer code snippets with proper formatting
- Make technical content easier to understand
Use Cases:
- Displaying commands in a tutorial (e.g.,
npm install) - Embedding HTML, CSS, or JavaScript examples in blogs
- Sharing code in GitHub README files
Platform Support:
- GitHub: Fully supports inline and fenced code blocks with syntax highlighting
- Docs & Blogs: Platforms like Dev.to, Hashnode, and GitBook support fenced blocks
- Editors: Works in Jupyter Notebooks, Obsidian, Notion, etc.
How to Write Code in Markdown:
- Inline Code: Use single backticks
`around the code - Indented Code Block: Add 4 spaces before each line
- Fenced Code Block: Use triple backticks (
```) — recommended
Syntax
`inline code here`
Markdown Content
# Example usage in Markdown
Inline Code:
Use `git status` to check repository status.
Indented Code Block:
console.log("Hello World");
Fenced Code Block:
```python
def add(a, b):
return a + b
print(add(2, 3))
```
Escaping Characters Syntax
Escaping in Markdown means adding a backslash \ before a character so Markdown does not treat it as special formatting.
Purpose:
- To display Markdown symbols like
*,#,[ ],_as plain text. - Helpful when teaching Markdown (showing raw syntax instead of formatted output).
- Needed when writing about programming or regex that uses Markdown characters.
Use Cases:
- A blog explaining Markdown itself (you want to show
**bold**instead of rendering it). - Writing documentation about regex
\d+without breaking formatting. - Explaining file paths or commands with backslashes.
Platform Support:
- GitHub: Fully supports escaping with
\. - Blogs/Docs: Works in most Markdown engines.
- Exceptions: Some minimal parsers may not support all escape sequences.
Syntax:
- Use
\before the character you want to escape.
Basic Examples:
\*Not bold text\* \# Not a heading \[This is not a link\]Markdown Content
# Escaping Example
Normally: *italic* → italic
Escaped: \*italic\* → *italic*
Normally: **bold** → bold
Escaped: \**bold** → **bold**
Normally: # Heading → Heading
Escaped: \# Heading → # Heading
Escaping brackets:
[Link\]
(https://example.com) → [Link](https://example.com)Inline HTML in Markdown
Inline HTML means writing raw HTML code directly inside a Markdown file. Markdown will render it as normal HTML.
Purpose:
- To add styles, attributes, or elements not supported by pure Markdown.
- To extend Markdown with HTML features like colored text, tables, buttons, or iframes.
- To mix simplicity of Markdown with the power of HTML when needed.
Use Cases:
- A blogger wants to highlight text with a custom color (
<span style="color:red">). - A developer needs to embed a YouTube video (
<iframe>). - Adding styled tables, custom headers, or dividers inside Markdown docs.
Platform Support:
- GitHub: Supports inline HTML but blocks dangerous tags (like
<script>). - Blogs & Docs: Most blogging platforms allow safe inline HTML.
- Note Apps: Some note apps (like Notion, Obsidian) limit HTML support.
Syntax:
- Just write HTML directly inside your Markdown file.
Markdown Content
# Inline HTML Example
Paragraph with <strong>bold</strong> text using HTML.
<span style="color:blue;">This text is blue</span>
<span style="background:yellow;">This has a yellow highlight</span>
<div align="center">
<h3>Centered heading using HTML</h3>
</div>
Embedding YouTube video:
<iframe width="300" height="200" src="https://www.youtube.com/embed/1d7pFLqO74o?si=jPFpZoyawV52H6AQ"></iframe>Advanced Markdown Syntax
Introduction:Basic Markdown is good for headings, lists, and links — but sometimes you need more control for complex documentation, technical blogs, or GitHub READMEs. That’s where advanced Markdown syntax comes in. We’ll now cover all important advanced Markdown features step by step.Emoji
Emojis are small icons made of characters that you can insert in Markdown using shortcodes. They make documentation, blogs, and README files more engaging and fun.
Use Cases:
- Adding emotions in changelogs, task lists, GitHub projects, or even showing project status
Platform Support:
- GitHub: Supports emoji shortcodes
- Slack & Discord: Fully compatible with emoji syntax
- Blogs: Most blogging platforms support emojis
- Note-taking apps: Some apps (like Notepad editors) may not support emoji rendering
Syntax:
:emoji-name:
Markdown Content
# Emoji Example
Hello World :smile:
Let's launch this project :rocket:
This is on fire :fire:
Made with :heart: in MarkdownCommon Emoji Shortcodes:
- :smile: - 😀
- :rocket: - 🚀
- :fire: - 🔥
- :heart: - ❤️
- :star: - ⭐
- :bug: - 🐛
- :warning: - ⚠️
- :checkered_flag: - 🏁
- :100: - 💯
- :thumbsup: - 👍
- :clap: - 👏
- :eyes: - 👀
Definition List
Definition lists are a special type of list used to define terms along with their explanations. They help create glossaries, FAQs, or structured notes where each term has a clear description.
Use Cases:
- Technical documentation
- Dictionaries and glossaries
- Study notes where terms and meanings need to be paired
Platform Support:
- Kramdown (Jekyll): Fully supports definition lists
- Pandoc: Compatible with definition list syntax
- Blog engines: Some support definition lists
- GitHub Markdown: ❌ Not supported in README files
Syntax:
Termfollowed by a line starting with:for the definition
Markdown Content
# Definition List Example
HTTP
: A protocol used for transferring data on the web.
API
: A set of functions and rules that allow software applications to communicate.
Markdown
: A lightweight markup language for creating formatted text using plain text.Syntax Highlighting in Code Blocks
Syntax highlighting is a feature that colors and styles code inside fenced code blocks according to the programming language. It makes code easier to read and understand by showing keywords, variables, and symbols in different colors.
Use Cases:
- Writing technical blogs
- Creating documentation with readable code examples
- GitHub README files that include code snippets
Platform Support:
- GitHub: Fully supports syntax highlighting
- GitLab & Bitbucket: Compatible with language-specific code blocks
- Stack Overflow: Uses syntax highlighting for clarity
- Markdown engines: Most modern parsers support it
Syntax:
```languagefollowed by your code, then closed with```
Markdown Content
```python
def greet(name):
return f"Hello, {name}!"
print(greet("Sonu"))
```
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
console.log(greet("Sonu"));
```
```html
<!DOCTYPE html>
<html>
<body>
<h1>Hello Sonu</h1>
</body>
</html>
```Automatic Links
Automatic links are created by simply wrapping a URL or email address inside angle brackets < > without any extra text. They make it quick and easy to turn plain URLs or email addresses into clickable links.
Use Cases:
- Adding quick references in documentation
- Inserting website URLs in README files
- Providing contact emails without full Markdown link syntax
Platform Support:
- GitHub: Fully supports automatic links
- GitLab & Bitbucket: Compatible with angle bracket syntax
- Markdown parsers: Most modern engines support automatic links
Syntax:
<https://example.com><user@example.com>
Markdown Content
# Automatic Links Example
Visit my website <https://example.com>
Send me an email <user@example.com>Footnotes
Footnotes let you add references or extra details without breaking the flow of your main content. The reader can click the marker and jump to the note at the bottom of the page. They keep your text clean while still allowing you to explain terms, add references, or cite sources.
Use Cases:
- Writing research articles
- Creating documentation with citations
- Adding extra information in blogs without cluttering the main text
Platform Support:
- Markdown-it: Fully supports footnotes
- Pandoc: Compatible with footnote syntax
- Jekyll (Kramdown): Supports footnotes in static site generation
- GitHub README: ❌ Not supported directly
Syntax:
[^1]to mark the footnote in the text[^1]:followed by the footnote content at the bottom
Markdown Content
# Footnote Example
Markdown is very popular for documentation.[^note]
[^note]: Markdown is supported in GitHub, blogs, and many platforms.Heading IDs and Anchor Links
Heading IDs let you give a unique identifier to a heading, and anchor links allow you to jump directly to that heading from anywhere in the document. This makes navigation easier in long documents, tutorials, or documentation by letting users click a link and scroll to the right section.
Use Cases:
- Creating a table of contents for long documents
- Linking between sections in the same README or wiki
- Improving navigation in tutorials and technical documentation
Platform Support:
- GitHub: Supports heading IDs and anchor links
- GitLab: Fully compatible with custom heading IDs
- Markdown engines: Most modern parsers that render HTML support this feature
Syntax:
### My Section Title (#custom - id)[Go to My Section](#custom-id)
Markdown Content
# Table of Contents
- [Introduction](#introduction)
- [Features](#features)
- [Contact](#contact)
# Introduction (#introduction)
This is the intro section.
# Features (#features)
These are the features.
# Contact (#contact)
Here’s how to contact us.Images with Links
Images with links allow you to wrap an image inside a hyperlink in Markdown. This makes the image clickable, redirecting users to another page or resource — useful for buttons, badges, or navigation banners.
Use Cases:
- Badges in GitHub README files
- Linked screenshots in tutorials
- Clickable logos in documentation or landing pages
Platform Support:
- GitHub: Fully supported
- GitLab: Fully supported
- Bitbucket: Fully supported
- Markdown engines: Most modern parsers support this syntax
Syntax:
[](link-url)
Markdown Content
# Images with Links Example
[](https://github.com)
Click the logo to visit GitHub.Images with Links Example
Click the logo to visit GitHub.
Extended Blockquotes (Multi-Paragraph)
Extended blockquotes allow you to include multiple paragraphs, headings, or other Markdown elements inside a single blockquote. This is especially useful when quoting long texts, articles, or multi-line notes without breaking the visual or semantic flow.
Use Cases:
- Quoting blog posts or articles with multiple paragraphs
- Referencing documentation with nested explanations
- Displaying long-form notes or commentary in Markdown
Platform Support:
- GitHub: Fully supported
- GitLab: Fully supported
- Bitbucket: Fully supported
- Markdown parsers: Most modern engines support multi-paragraph blockquotes
Syntax:
> This is the first paragraph of a blockquote.>> This is the second paragraph in the same blockquote.
Markdown Content
# Extended Blockquote Example
> Markdown is simple and powerful.
>
> It supports headings, lists, links, and much more inside blockquotes.
>
> You can even add **bold text**, *italic text*, or `inline code`.Tables with Alignment
Tables let you organize data in rows and columns.Alignment controls how text inside each column is displayed — left, center, or right. This helps format structured information like comparison charts, pricing tables, or feature lists with clarity.
Use Cases:
- Feature comparisons in documentation
- Product pricing or specification tables
- Aligning numbers or text for better readability
Platform Support:
- GitHub: Fully supported
- GitLab: Fully supported
- Bitbucket: Fully supported
- Markdown engines: Most modern parsers support table alignment syntax
Syntax:
| Column 1 | Column 2 | Column 3 ||----------|:--------:|---------:|| Left | Center | Right |
Explanation of Alignment:
- Left Align: Use
---or:---
Example:|:---→ Left aligned text - Center Align: Use
:---:
Example:|:---:→ Center aligned text - Right Align: Use
---:Example:|---:→ Right aligned text
Markdown Content
# Table with Alignment Example
| Feature | Supported | Score |
|:-----------|:---------:|------:|
| Headings | Yes | 10 |
| Lists | Yes | 8 |
| Tables | Yes | 9 |Nested Tables & Complex Tables
Nested tables are tables placed inside another table cell.Complex tables may include merged cells, multiple headers, or mixed HTML for advanced formatting. These techniques help display hierarchical or multi-layered structured data inside Markdown documents.
Use Cases:
- Documentation with detailed feature breakdowns
- Dashboards where one cell contains multiple values
- Tables with sub-sections or embedded comparisons
Platform Support:
- Pure Markdown: ❌ Does not support nested or complex tables directly
- GitHub: I have tried but it not supported.
- Markdown parsers: ✅ Most modern engines allow embedded HTML
Syntax (Using HTML inside Markdown):
| Feature | Details ||------------|---------|| Tables | <table>...</table> |
Markdown Content
## Nested Table Example
| Feature | Details |
|------------|---------|
| Tables | <table>
<tr><td>Row 1</td><td>Nested</td></tr>
<tr><td>Row 2</td><td>Table</td></tr>
</table> | Markdown Add-ons (Platform Specific)
Markdown is lightweight, but different platforms extend it with their own add-ons to make it more powerful. These add-ons are **not part of the original Markdown spec**, but they make life easier for developers, writers, and open-source contributors. You’ll see these add-ons in:- GitHub Flavored Markdown (GFM): Used in GitHub READMEs, issues, pull requests, and wikis. It adds support for task lists, tables, strikethrough, and automatic links.
- GitLab Markdown: Similar to GFM but with some extras like math blocks and diagrams.
- Bitbucket Markdown: Supports GFM features with its own tweaks.
- Jekyll & Static Site Generators: Blog engines often extend Markdown with plugins like syntax highlighting, footnotes, or math equations.
- Pandoc Markdown: A powerful Markdown engine used for academic writing, with support for citations, references, and custom extensions.
- Obsidian / Notion / Typora: Personal note-taking apps that add custom Markdown features like callouts, diagram blocks, or backlinks.
Emoji (GitHub Flavored)
Emoji make your text more expressive and fun in Markdown, especially in GitHub READMEs, issues, and pull requests. Instead of plain text, you can use emojis to grab attention, highlight status, or simply add a human touch. GitHub supports a wide range of emojis by using a special syntax with colons around the emoji name.Syntax
:emoji_name:Markdown Content
### Emoji Example
I love Markdown! :heart:
This task is done! :white_check_mark:
Need help? :question:
Celebration time! :tada:Common Emojis
- :smile: → 😄
- :heart: → ❤️
- :tada: → 🎉
- :white_check_mark: → ✅
- :x: → ❌
- :star: → ⭐
- :fire: → 🔥
- :rocket: → 🚀
Use Case
- Make README files more engaging with status icons.
- Add fun reactions in GitHub issues and discussions.
- Highlight completed tasks with ✅ or mark problems with ❌.
- Celebrate milestones with 🎉 or show excitement with 🚀.
Mentions and References (GitHub Flavored)
Mentions and references are a powerful way to connect people and issues directly in your GitHub project. Instead of plain text, you can mention a user with @username or reference an issue, pull request, or discussion using #number. This improves collaboration by notifying the person instantly and linking readers to the relevant issue or PR.
Use Cases:
- Team Collaboration: Mention teammates directly so they get notified
- Issue Tracking: Link bugs, features, or tasks with
#issue - Cross-repo Work: Reference issues in other repositories using
org/repo#id - Clear Documentation: Keep project history connected by pointing to relevant PRs and issues
Platform Support:
- GitHub: Fully supported
- GitLab: Partially supported (mentions only)
- Bitbucket: Limited support
- Markdown engines: Depends on platform integration
Syntax:
@username→ Mentions a GitHub user#123→ Links to issue or pull request number 123organization/repo#123→ References issue/PR in another repository
Markdown Content
# Mentions and References Example
Thanks for the review, @sonu!
We need to fix the bug in #45 before release.
Also check organization/project#101 for related discussion.Collapsible Sections (GitHub Flavored)
Collapsible sections allow you to hide large blocks of text or code under a clickable summary. This keeps your README or documentation clean and lets readers expand only what they need. It’s commonly used for long examples, FAQs, or optional notes.
Use Cases:
- Hide long code examples in documentation
- Include FAQs or optional instructions in README files
- Organize content so the main page stays clean
- Let readers expand only what interests them
Platform Support:
- GitHub: ✅ Fully supported in README, issues, PRs, and wikis
- GitLab: ✅ Supported in Markdown with HTML
- Bitbucket: ⚠️ Limited support; may render as plain text
- Other Markdown editors: ❌ May not render collapsible behavior
Syntax:
<details><summary>Summary text here</summary>Hidden content goes here. It can include text, code blocks, or lists.</details>
Markdown Content
# Collapsible Section Example
<details>
<summary>Click to expand!</summary>
Here is the hidden content. You can include:
- Lists
- Code blocks
- Images
- Any Markdown content
</details>Diagrams with Mermaid.js (GitHub Flavored)
Mermaid.js lets you create diagrams and visualizations directly in Markdown using simple text-based syntax. Instead of manually drawing images, you write code that dynamically generates diagrams. This is ideal for documenting workflows, software architecture, processes, or timelines in a clean and maintainable way.
Use Cases:
- Document software workflows with flowcharts
- Visualize user interactions with sequence diagrams
- Plan project timelines with Gantt charts
- Show class structures or state diagrams in documentation
- Create simple pie charts to show proportions
Supported Diagram Types:
- Flowcharts
- Sequence Diagrams
- Gantt Charts
- Class Diagrams
- Pie Charts
- State Diagrams
- Requirement Diagrams
Platform Support:
- GitHub:Supported in README, issues, and wikis using Mermaid blocks
- GitLab: Supports Mermaid in Markdown files
- Bitbucket: ⚠️ Limited or partial support; may require plugins
- Other Markdown editors: ⚠️ Some editors like Obsidian or Typora support Mermaid natively; others may need extensions
Syntax:
```mermaidgraph TDA[Start] --> B{Is it working?}B -- Yes --> C[Celebrate]B -- No --> D[Fix the issue]```
Example (Flowchart):
Markdown Content
# Flowchart Example
```mermaid
graph TD
A[Start] --> B{Is it working?}
B -- Yes --> C[Celebrate]
B -- No --> D[Fix the issue]
D --> B
```Example (Sequence Diagram):
Markdown Content
# Sequence Diagram Example
```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>Bob: Hello Bob, how are you?
Bob-->>Alice: I am good, thanks!
```Example (Gantt Chart):
Markdown Content
# Gantt Chart Example
```mermaid
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Development
Task A :a1, 2025-09-01, 5d
Task B :after a1, 3d
section Testing
Task C :2025-09-08, 4d
```Mathematical Expressions (LaTeX/KaTeX)
Math in Markdown allows you to include inline or block-level mathematical formulas directly in your Markdown files. This is especially useful for academic documents, technical blogs, or any content requiring equations, formulas, or symbols. GitHub supports math in Jupyter notebooks, discussions, and some Markdown renderers, while static site generators like Jekyll or Hugo often use KaTeX or MathJax for rendering.
LaTeX is a typesetting system widely used for writing mathematical formulas, scientific documents, and academic papers. It allows you to write complex equations in plain text that are then rendered beautifully.
KaTeX is a fast, web-based math rendering library that displays LaTeX equations on websites. It is used in Markdown renderers, static site generators, and editors to show math formulas in the browser quickly without needing a full LaTeX installation.
Math in Markdown allows you to include inline or block-level mathematical formulas directly in your Markdown files. This is especially useful for academic documents, technical blogs, or any content requiring equations, formulas, or symbols. GitHub supports math in Jupyter notebooks, discussions, and some Markdown renderers, while static site generators like Jekyll or Hugo often use KaTeX or MathJax for rendering.
Use Cases:
- Academic papers, assignments, or tutorials
- Technical blogs explaining formulas or algorithms
- Documenting physics, mathematics, or engineering concepts
- Including clear, readable equations in GitHub READMEs with Jupyter notebooks
Platform Support:
- GitHub: Inline math supported in Jupyter notebooks and discussions. Limited in README files
- GitLab: Supports math blocks using KaTeX/MathJax
- Bitbucket: Limited support; may require HTML or external renderer
- Jekyll/Hugo/Static Sites: Use KaTeX or MathJax plugins for full math support
Syntax:
- Inline Math: Wrap the expression with single dollar signs
$...$ - Block Math: Wrap the expression with double dollar signs
$$...$$or use```mathfenced blocks
Basic Expressions:
$E = mc^2$$$ E = mc^2 $$
Algebra & Arithmetic:
$a^2 + b^2 = c^2$$$ (a + b)^2 = a^2 + 2ab + b^2 $$
Fractions & Roots:
$\frac{1}{2}$$$ \sqrt{a^2 + b^2} = c $$
Sums & Integrals:
$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$$ \int_0^1 x^2 dx = \frac{1}{3} $$
Greek Letters & Symbols:
$\alpha, \beta, \gamma, \Delta, \pi$$$ \theta = \frac{\pi}{4}, \ lambda = 5 $$
Matrices:
$$ \begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix} $$
Markdown Content
# Math Examples
Inline: $E = mc^2$
Block:
$$
E = mc^2
$$
Inline: $a^2 + b^2 = c^2$
Block:
$$
(a + b)^2 = a^2 + 2ab + b^2
$$
Inline: $ rac{1}{2}$
Block:
$$
sqrt{a^2 + b^2} = c
$$
Inline: $sum_{i=1}^{n} i = rac{n(n+1)}{2}$
Block:
$$
int_0^1 x^2 dx = rac{1}{3}
$$
Inline: $alpha, eta, gamma, Delta, pi$
Block:
$$
heta = rac{pi}{4}, lambda = 5
$$
Block:
$$
egin{bmatrix}
1 & 2 \\
3 & 4
end{bmatrix}
$$Callouts / Admonitions (Markdown Add-ons)
Callouts (also called admonitions) are special highlighted blocks used to draw attention to important content like notes, tips, warnings, or alerts. Unlike regular paragraphs, callouts make content stand out with borders, background colors, or icons. They are widely used in documentation sites, knowledge bases, tutorials, and educational content to improve readability and emphasize important points.
Callouts are not part of standard Markdown, so they are supported via platform-specific extensions, plugins, or HTML/CSS. For example, documentation frameworks like MkDocs, Docusaurus, or Jekyll provide built-in support for admonitions, while GitHub README requires a workaround using <div> tags.
Use Cases:
- Highlight warnings in tutorials or documentation
- Provide tips or best practices for readers
- Draw attention to important notes, cautions, or alerts
- Organize content for better readability in technical documentation
Platform Support:
- MkDocs / Material for MkDocs: ✅ Fully supported with
!!!syntax - Docusaurus: ✅ Supported with
:::syntax and plugin - GitHub README: ⚠️ Limited; requires HTML
<div>workaround - Jekyll / Hugo: ✅ Many themes provide admonition support via plugins or shortcodes
- Other Markdown editors: ⚠️ Some may require extensions for proper rendering
Syntax Examples:
- MkDocs / Material for MkDocs:
!!! note "Tip Title" This is a note callout. - Docusaurus:
:::note This is a note callout. ::: - GitHub README (HTML method):
<div style="border-left: 4px solid #36c; padding: 0.5em; background-color: #f0f4ff;">Note: This is a note callout in GitHub README. </div>
Markdown Content
# Callouts Example
!!! warning "Important!"
Be careful while editing this file. Incorrect changes may break the build.
:::tip
Use this tip to improve readability.
:::
<div style="border-left: 4px solid #36c; padding: 0.5em; background-color: #f0f4ff;">
<strong>Note:</strong> GitHub users can use HTML to create callouts.
</div>Which Platforms Support Which Features
Markdown is used everywhere—from blogs to GitHub to documentation sites. However, not all Markdown features are supported equally across platforms. Understanding what works where helps you create consistent content that looks good and functions properly for all users. This section explains which features are supported universally, which are GitHub-specific, which are for blog platforms like WordPress, and which are supported in specialized documentation tools.
Universal (Core) Features
These features form the foundation of Markdown and are supported almost everywhere, including GitHub, WordPress, and documentation tools. Headers, lists, emphasis (italic, bold, bold-italic), links, images, blockquotes, horizontal rules, code (inline and block), simple tables, and safe HTML tags like <strong> or <details> are considered core. They allow you to structure content, emphasize points, include resources, and display code effectively.
For example, using headers (#, ##, ###) allows you to create a hierarchy of content from main titles to subsections, making your articles easy to navigate. Lists help organize steps or features logically. Inline code and fenced code blocks display programming code clearly. Blockquotes can highlight notes or quotes. Even simple tables can present data neatly without complex formatting.
Platforms supporting these core features include GitHub, WordPress (basic Markdown), and static site generators like Jekyll, Hugo, and MkDocs.
GitHub-specific Features
GitHub extends Markdown with features designed for collaboration and interactivity. You can mention users using @username, create task lists with checkboxes (- [ ] and - [x]), add inline emojis using :emoji_name:, generate automatic tables of contents, use heading anchors for easy navigation, create enhanced tables with alignment options, strike through text with ~~text~~, apply syntax highlighting in code blocks, and even render Mermaid diagrams for flowcharts and sequence diagrams.
For instance, task lists are excellent for project management directly inside a README file. Emojis can make your documentation more visually appealing and engaging. Mermaid diagrams allow you to visually explain workflows, making technical documentation clearer.
These features are primarily supported in GitHub repositories, issues, pull requests, and wikis. GitHub sanitizes some HTML tags for security, so certain styling or CSS won’t work in README files.
Blog Platforms (WordPress Markdown Extra)
WordPress supports Markdown differently depending on the editor or plugin. Classic Editor supports Markdown Extra, which adds features such as footnotes, definition lists, styled tables, abbreviations, and automatic links. Gutenberg Markdown block supports standard CommonMark features, while Jetpack plugin enables Markdown across posts and comments. Advanced plugins like WP GitHuber MD offer live preview and extended functionality.
Footnotes are useful for adding references or explanations at the end of articles. Definition lists help clearly define terms. Styled tables organize information neatly. Abbreviations automatically expand short terms for readers. Automatic links convert URLs to clickable links without additional formatting.
Documentation Tools
Specialized documentation tools often extend Markdown further using plugins or native support. MkDocs, Docusaurus, Obsidian, GitLab Flavored Markdown, mdBook, and Quarto allow advanced features such as Mermaid diagrams, mathematical expressions using LaTeX/KaTeX, callouts/admonitions, and other plugin-based extensions.
Mermaid diagrams let you visually represent workflows, flowcharts, or Gantt charts. Mathematical expressions make scientific content readable. Callouts highlight important notes, tips, or warnings. Plugin support enables further customization for professional documentation.