Back to blog

Markdown Syntax Guide: Basic and Extended Rules

Learn markdown syntax with this clear guide to basic and extended rules, plus examples for headings, lists, links, tables, code, and more.

Introduction

Markdown is a plain text formatting system that lets you write content in a simple, readable way and convert it to HTML with a parser and renderer. It is widely used for documentation, README files, knowledge bases, wiki pages, CMS content, and notes because it is easy to edit, review, and move between tools.

The original Markdown project is associated with John Gruber and Aaron Swartz. Over time, many Markdown flavors have emerged, including GitHub Flavored Markdown (GFM) and CommonMark-based implementations. That is why the same source can look slightly different on GitHub, in GitHub Docs, in a Markdown editor, or on a documentation site.

This guide explains what Markdown syntax is, how to write it, and how the basic Markdown elements work. It also covers the differences between Markdown and HTML, how headings, lists, links, images, code blocks, tables, task lists, and blockquotes work, how to escape special characters, how to link to a heading, and why renderers behave differently across platforms.

If you are building team docs, a README, or a documentation site, these related resources may also help: Markdown style guide for teams, README best practices, and documentation template.

What Is Markdown Syntax?

Markdown syntax is a lightweight way to format plain text using simple symbols such as #, *, -, [ ], and backticks. A parser reads the text and a renderer displays the formatted result. The goal is to keep the source easy to read even before it is rendered.

Compared with HTML, Markdown is shorter and less verbose. HTML uses explicit tags such as <h1>, <ul>, and <a>, while Markdown uses simpler notation such as #, -, and [text](url). Markdown is often preferred for documentation because it is faster to write and easier to scan in raw form.

Basic Markdown Elements

The basic Markdown elements include headings, paragraphs, emphasis, lists, links, images, blockquotes, inline code, fenced code blocks, and horizontal rules.

  • Headings organize content into sections.
  • Lists structure steps and groups.
  • Links connect to web pages or relative files.
  • Images display visual content with alt text.
  • Code blocks format code clearly.

How Do Headings Work in Markdown?

Use one to six hash symbols at the start of a line to create headings:

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

Headings should follow a logical hierarchy. In most documents, use a single H1 for the page title, then H2s for main sections and H3s for subsections. Many renderers also generate heading IDs automatically, which makes anchor links possible.

To link to a heading, use the heading’s anchor link. On GitHub and many documentation sites, this is usually based on the heading text, such as #how-do-headings-work-in-markdown. Exact behavior can vary by renderer, so check the platform’s rules.

How Do You Make Bold and Italic Text in Markdown?

Use double asterisks or double underscores for bold text, and single asterisks or single underscores for italic text:

**bold**
__bold__
*italic*
_italic_

You can combine them for bold italic text:

***bold italic***

How Do You Create Lists in Markdown?

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

Unordered Lists

Use -, *, or + for unordered lists:

- Item one
- Item two
  - Nested item

Ordered Lists

Use numbers followed by a period for ordered lists:

1. First step
2. Second step
3. Third step

Task Lists

Task lists are common in GitHub Flavored Markdown and many documentation workflows:

- [ ] Open task
- [x] Completed task

How Do You Add Links in Markdown?

Use the standard link format [link text](url):

[DocsForDevs](https://docsfordevs.com)

For files within the same repository or documentation set, use relative links:

[Read the README best practices guide](../blog/readme-best-practices)

Relative links are especially useful in GitHub repositories, README files, and documentation sites because they stay valid when content moves within the same project.

How Do You Insert Images in Markdown?

Use the image syntax ![alt text](image-url):

![Architecture diagram](images/architecture.png)

The alt text should describe the image’s purpose, not just repeat the word “image.” Good alt text helps accessibility and makes the content clearer when the image does not load.

How Do You Write Code Blocks in Markdown?

Use backticks for inline code and fenced code blocks for multi-line code.

Inline code:

Use `inline code` for short snippets.

Fenced code block:

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


Fenced code blocks are the preferred format in most Markdown editors because they preserve spacing and support syntax highlighting in many renderers.

## How Do You Escape Special Characters in Markdown?

If you want Markdown to show a character literally, place a backslash before it:

```md
\* \_ \# \[ \] \( \) \!

This is useful when you need to display punctuation that would otherwise trigger formatting. Backticks can also be used to show literal code text without formatting it as Markdown.

What Is the Difference Between Markdown and HTML?

Markdown is a lightweight plain text format designed for quick writing and readable source files. HTML is a markup language with explicit tags and more control over structure and presentation.

Use Markdown when you want speed, readability, and portability. Use HTML when you need precise layout, custom attributes, or elements that Markdown does not support well. In many systems, you can combine both.

Can You Use HTML in Markdown?

Yes, many Markdown parsers allow raw HTML, including tags such as <br>, <span>, <sup>, and <div>. This can be useful when Markdown does not provide a needed formatting option.

However, support for raw HTML depends on the platform. Some renderers sanitize or strip raw HTML for security or consistency, especially in documentation systems, CMS platforms, wiki software, and some GitHub workflows. If you rely on raw HTML, test it in the target renderer first.

What Are Extended Markdown Features?

Extended Markdown features are syntax additions that are not part of the simplest Markdown core. Common examples include tables, task lists, strikethrough, footnotes, automatic links, and heading IDs.

GitHub Flavored Markdown (GFM) includes several of these features, which is why it is popular in GitHub, GitHub Docs, issue trackers, and README files.

Tables in Markdown

Tables use pipes and a separator row:

| Name | Status |
| --- | --- |
| Docs | Ready |
| API | In progress |

Tables are useful in documentation, knowledge bases, and README files, but they can be harder to read on narrow screens.

Task Lists in Markdown

Task lists use checkbox syntax:

- [ ] Draft outline
- [x] Review content

They are common in GitHub issues, project plans, and team documentation.

Blockquotes in Markdown

Use > to create blockquotes:

> This is a quoted or highlighted note.

Blockquotes are useful for warnings, callouts, and sourced quotations.

Line Breaks in Markdown

Line breaks can be created differently depending on the renderer. In many Markdown flavors, you can end a line with two spaces or use an HTML <br> tag. Some platforms treat a single line break as a soft wrap instead of a visible break, so check the target renderer.

What Is CommonMark?

CommonMark is a specification that defines a consistent baseline for Markdown behavior. The CommonMark spec helps reduce ambiguity so content renders more predictably across tools.

You can test Markdown against the CommonMark spec using the CommonMark dingus, and developers can compare behavior with the CommonMark reference implementation. These tools are helpful when you want to verify how a parser should interpret a document.

What Is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is GitHub’s Markdown dialect built on CommonMark. It adds features that are especially useful in GitHub and GitHub Docs, including tables, task lists, strikethrough, autolinks, and support for issue and pull request references in many contexts.

GFM is widely used in README files, README.md files, documentation, and issue trackers because it matches common developer workflows.

Why Does Markdown Render Differently Across Platforms?

Markdown renderers do not always support the same syntax. A parser in one CMS, wiki, documentation site, or Markdown editor may interpret spacing, tables, lists, or HTML differently from another.

Differences can come from:

  • different Markdown flavors
  • different parser rules
  • platform-specific extensions
  • security filtering for raw HTML

That is why the same source can look different on GitHub, in a knowledge base, or in a static documentation site. When consistency matters, test the final output in the target platform and follow a shared style guide.

Quick Markdown Cheat Sheet

  • # Heading 1 — top-level heading
  • ## Heading 2 — second-level heading
  • **bold** — bold text
  • *italic* — italic text
  • - item — unordered list item
  • 1. item — ordered list item
  • [text](url) — link
  • ![alt text](image.png) — image
  • `inline code` — inline code
  • ``` — fenced code block
  • > quote — blockquote
  • - [ ] task / - [x] task — task list item
  • \* — escaped special character

Conclusion

Markdown syntax gives you a practical way to write readable plain text that can be rendered into HTML across many tools. The basics cover headings, emphasis, lists, links, images, code, and blockquotes, while extended Markdown features add tables, task lists, and other conveniences.

If you are writing for GitHub, a README, a documentation site, or a knowledge base, remember that Markdown flavors and renderers can differ. Use CommonMark as a baseline when possible, test in the target platform, and keep your formatting consistent with a team style guide.

For more guidance, revisit the DocsForDevs home, the Markdown style guide for teams, the README best practices, and the documentation template.