Markdown syntax is a simple set of text formatting rules used to create structured documents with plain text. Instead of using formatting buttons like in Microsoft Word, Markdown uses characters such as #, *, -, and backticks to define headings, lists, links, code blocks, and other formatting elements.

For example, writing:

# Welcome

creates a level one heading when the Markdown document is rendered.

Because the syntax is easy to read even before formatting is applied, Markdown has become one of the most popular writing formats for developers, technical writers, students, bloggers, and documentation teams.

Today, Markdown is widely supported by GitHub, GitLab, Obsidian, VS Code, Notion, Stack Overflow, documentation generators, and many AI tools.

Markdown itself is plain text.

When you write Markdown, a parser reads the syntax and converts it into HTML, which your browser or application displays as formatted content.

The process is simple:

Markdown Text
        ↓
Markdown Parser
        ↓
HTML Output
        ↓
Rendered Page

This approach allows you to write documents quickly without manually creating HTML tags.

For example:

Markdown

## Installation

becomes

HTML

<h2>Installation</h2>

after it is processed by a Markdown parser.

This simple conversion process is one of the reasons Markdown has become the standard format for documentation and README files.

Learning Markdown saves time while creating clean, readable documents.

Markdown is commonly used for:

• GitHub README files
• Software documentation
• Project wikis
• Technical blogs
• AI-generated content
• Meeting notes
• Knowledge bases
• Personal note-taking
• Static websites

Unlike traditional word processors, Markdown documents remain lightweight, portable, and easy to edit with almost any text editor.

Not every Markdown feature belongs to the original Markdown specification.

Modern editors often support additional formatting known as Extended Markdown or GitHub Flavored Markdown (GFM).

Standard Markdown	Extended Markdown
Headings	Tables
Bold & Italic	Task Lists
Lists	Strikethrough
Links	Footnotes
Images	Syntax Highlighting
Blockquotes	Emoji Support (some editors)

Understanding this difference helps explain why some Markdown features work in one application but not in another.

For example, tables and task lists work perfectly on GitHub but may not appear correctly in editors that only support basic Markdown.

Several Markdown implementations exist today.

Original Markdown

The original Markdown syntax created by John Gruber includes the basic formatting features such as headings, lists, emphasis, links, images, and blockquotes.

CommonMark

CommonMark provides a standardized specification designed to make Markdown behave consistently across different applications.

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown extends standard Markdown by adding useful features including:

• Tables
• Task lists
• Strikethrough
• Fenced code blocks
• Syntax highlighting
• Automatic URL linking

If you're creating README files or GitHub documentation, GitHub Flavored Markdown is the version you'll use most often.

Different platforms support different Markdown features.

Feature	Standard Markdown	GitHub	Obsidian	Discord
Headings	✅	✅	✅	✅
Lists	✅	✅	✅	✅
Tables	❌	✅	✅	❌
Task Lists	❌	✅	✅	❌
Footnotes	❌	✅	✅	❌
HTML	✅	✅	Partial	❌

Always check which Markdown version your editor supports before using advanced formatting.

Headings organize your document into clear sections, making it easier to read and navigate. They also create a logical structure for long documents, README files, tutorials, and technical documentation.

Markdown supports six heading levels.

Syntax

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Example

# MDConvertHub
## Markdown Tools
### Markdown Editor
#### Features
##### Live Preview
###### Tips

Rendered Output

Where to Use Headings

Use headings to:

• Organize long documents
• Structure GitHub README files
• Create technical documentation
• Separate chapters in guides
• Improve document readability

Best Practices

• Start every document with one H1 heading.
• Keep heading names short and descriptive.
• Maintain a logical order (H1 → H2 → H3).
• Don't skip heading levels without a reason.

Common Mistakes

Wrong:

# Main Heading
#### Jumping directly to H4

Better:

# Main Heading
## Section
### Subsection

Paragraphs are the foundation of every Markdown document.

To create a new paragraph, simply leave one blank line between blocks of text.

Syntax

This is the first paragraph.

This is the second paragraph.

Example

Markdown is easy to read.

It also makes documents easy to maintain.

Rendered Output

Best Practices

• Keep paragraphs short.
• Focus on one idea per paragraph.
• Use blank lines to separate content.

Long paragraphs are harder to read, especially on mobile devices.

Sometimes you need a new line without starting a new paragraph.

Markdown supports this by adding two spaces at the end of a line before pressing Enter.

Syntax

Line One··
Line Two

(The dots represent two spaces.)

Another option supported by many Markdown editors is using an HTML line break.

Line One<br>
Line Two

Best Practice

For maximum compatibility, use blank paragraphs whenever possible and only insert manual line breaks when necessary.

Bold text highlights important words or key information.

Syntax

**Bold Text**

You can also use:

__Bold Text__

Example

This is **important** information.

Rendered Output

Best Practices

Use bold text to emphasize important notes, warnings, key terms, feature names, and commands.

Avoid making entire paragraphs bold because it reduces readability.

Italic text adds subtle emphasis without drawing as much attention as bold formatting.

Syntax

*Italic Text*

or

_Italic Text_

Example

*Markdown* is simple to learn.

Rendered Output

Best Practices

Use italics for new terms, book titles, gentle emphasis, and foreign words.

Don't overuse italic formatting throughout the document.

You can combine bold and italic formatting when stronger emphasis is needed.

Syntax

***Bold and Italic***

Example

***Important Update***

Rendered Output

Use this style sparingly for important notices or highlighted sections.

Strikethrough marks text that has been removed, replaced, or completed.

It is commonly used in GitHub issues, changelogs, documentation, and task tracking.

Syntax

~~Old Text~~

Example

~~Version 1~~

Version 2

Rendered Output

Best Practices

Strikethrough works especially well for completed tasks, deprecated features, changelog updates, and documentation revisions.

Remember that strikethrough is part of GitHub Flavored Markdown and may not be available in every Markdown editor.

Horizontal rules visually separate major sections of a document.

They improve readability in long articles and documentation.

Syntax

Any of these styles work.

---

***

___

Rendered Output

Best Practices

Use horizontal rules between major topics instead of adding excessive blank space.

Too many horizontal rules can make a page feel cluttered, so use them only where they genuinely improve navigation.

Lists help organize information into easy-to-read points. Markdown supports both unordered and ordered lists, and you can also create nested lists for more detailed content.

Unordered Lists

Use a hyphen (-), asterisk (*), or plus sign (+) followed by a space.

Syntax

- Apple
- Banana
- Orange

Example

- Markdown Editor
- Markdown Table Formatter
- Markdown Viewer

Rendered Output

Common Mistake

Wrong:

-First Item

Correct:

- First Item

---

Ordered Lists

Ordered lists use numbers followed by a period.

Syntax

1. First
2. Second
3. Third

Example

1. Install the project.
2. Configure the settings.
3. Run the application.

Rendered Output

Tip

Markdown automatically renumbers ordered lists in many editors, so you don't always have to update every number manually.

---

Nested Lists

Lists can contain sub-items.

Syntax

- Fruits
  - Apple
  - Orange
- Vegetables
  - Carrot
  - Potato

Indent nested items with two or four spaces, depending on your editor.

Links connect your document to websites, files, or other pages.

Markdown supports several link styles.

Inline Links

Syntax

[MDConvertHub](https://mdconverthub.com)

Example

Visit the [Markdown Editor](/tools/markdown-editor).

Rendered Output

---

Links with Titles

You can add a tooltip that appears when users hover over the link.

[Markdown Guide](https://example.com "Markdown Guide")

---

Automatic Links

<https://example.com>

---

Email Links

<support@example.com>

---

Best Practices

• Use descriptive link text instead of "Click here."
• Check links regularly to avoid broken URLs.
• Keep link labels meaningful and easy to understand.

Images are inserted using syntax similar to links, with an exclamation mark at the beginning.

Syntax

![Alt Text](image.png)

Example

![Markdown Logo](markdown-logo.png)

Alt Text

Alt text describes an image for screen readers and users when the image cannot be displayed.

Good example:

![Markdown syntax example](syntax-example.png)

Poor example:

![Image](syntax-example.png)

Meaningful alt text improves accessibility and provides helpful context.

Best Practices

• Always include descriptive alt text.
• Use clear image file names.
• Keep images relevant to the surrounding content.

Blockquotes highlight quoted text, notes, or important information.

Syntax

> This is a blockquote.

Example

> Markdown focuses on readability before formatting.

Rendered Output

Nested Blockquotes

> Main quote
>
>> Nested quote

Best Practices

Use blockquotes for tips, notes, documentation warnings, quotes, and important information.

Avoid using blockquotes for normal paragraphs.

Task lists are supported in GitHub Flavored Markdown and several other Markdown editors.

They're commonly used in README files, issue tracking, project planning, and documentation.

Syntax

- [ ] Pending Task
- [x] Completed Task

Example

- [x] Create documentation
- [x] Review examples
- [ ] Publish project

Rendered Output

Best Practices

Task lists are useful for project roadmaps, development checklists, documentation progress, and release planning.

Remember that task lists are part of GitHub Flavored Markdown and may not render in editors that only support basic Markdown.

Code formatting is essential in technical documentation.

Inline Code

Highlight commands, filenames, or short snippets with single backticks.

Syntax

Use the `npm install` command.

Rendered Output

---

Fenced Code Blocks

Use triple backticks for longer examples.

Syntax

console.log("Hello");

Example

```javascript
function greet(name) {
  return `Hello ${name}`;
}

### Rendered Output

Rendered Output
function greet(name) {
  return `Hello ${name}`;
}



### Best Practices

- Always specify the language when possible for syntax highlighting.
- Use inline code for short commands and fenced blocks for multi-line examples.
- Keep code examples focused and runnable when possible.

Tables organize structured data in rows and columns. They are part of GitHub Flavored Markdown.

Syntax

| Name | Role |
| ---- | ---- |
| Alex | Developer |
| Emma | Designer |

Example

| Tool | Purpose |
| ---- | ------- |
| Markdown Editor | Write and preview |
| Table Generator | Build tables |

Rendered Output

Best Practices

• Keep column counts consistent on every row.
• Use the Markdown Table Generator for large tables.
• Align columns with colons in the separator row when needed (:---, :---:, ---:).

Even though Markdown is simple, small formatting mistakes can prevent your content from rendering correctly.

Problem	Why It Happens	Solution
Heading doesn't render	Missing space after #	Use # Heading instead of #Heading
Bold text not working	Missing closing **	Make sure both opening and closing markers are present
Broken link	Incorrect bracket order	Use [Text](URL)
Table formatting breaks	Missing separator row	Add the --- separator below the header
Code block isn't formatted	Missing closing backticks	Always close fenced code blocks
Nested list looks incorrect	Incorrect indentation	Use consistent indentation (2 or 4 spaces)
Task list not displayed	Editor doesn't support GFM	Use a GitHub Flavored Markdown editor

Always preview your document before publishing to catch formatting errors early.

Following a few simple guidelines will make your Markdown documents easier to read, maintain, and share.

Keep your formatting consistent

Use the same heading levels, list style, spacing, and code formatting throughout the document.

Write meaningful headings

Clear headings improve navigation and make long documents easier to scan.

Instead of Information, use Installation Guide or Project Requirements.

Preview before publishing

Different applications render Markdown differently. Always preview your document in the platform where it will be published.

Use descriptive links

Avoid generic links like "Click Here." Write Markdown Editor or Markdown Table Generator instead.

Keep paragraphs short

Large blocks of text are difficult to read. Short paragraphs improve the reading experience on both desktop and mobile devices.

Use code blocks for commands

npm install

This makes technical documentation much easier to follow.

Markdown is one of the easiest ways to create clean, well-structured documents without using complex formatting tools. Whether you're writing a GitHub README, project documentation, blog content, or personal notes, understanding Markdown syntax helps you work faster while keeping your content readable and portable.

Start with the basic formatting rules, then explore advanced features like tables, task lists, code blocks, and GitHub Flavored Markdown as your projects grow.

Bookmark this guide as your complete Markdown syntax reference. For a compact lookup table, see the Markdown Cheat Sheet. For a friendly introduction, read the beginner guide on the blog.