Back to blog

Markdown Guide: Syntax, Examples, and Cheat Sheet

Learn Markdown syntax, examples, and a handy cheat sheet to format docs fast. Master the basics and write cleaner content today.

Introduction

Markdown is a lightweight way to format plain text so it can be converted into HTML or other output formats without the complexity of a full word processor. You write simple symbols for headings, lists, links, code, emphasis, tables, and other elements, then render the file in a Markdown editor, documentation tool, or publishing system.

That simplicity is one reason Markdown is widely used in README files, product docs, knowledge bases, note-taking apps, and static site generators. It also fits well with version control because the source text stays readable in diffs and code reviews.

This guide covers the core syntax, common extensions, preview workflows, and practical best practices for teams. If you work in DocsForDevs or publish content through DocsForDevs, the same habits help you keep documentation consistent and easy to maintain.

By the end, you’ll know what Markdown is, how it works, how it compares with HTML, and how to use it for documentation and README files.

What is Markdown?

Markdown is a lightweight markup syntax for formatting plain text. You write readable text with simple symbols, and a parser or renderer converts it into HTML or another format such as PDF or DOCX. John Gruber created Markdown, with influence from Aaron Swartz, to make writing and reading text easier without giving up basic formatting.

Markdown is not HTML and it is not a programming language. HTML gives you explicit control over structure and attributes, while Markdown is faster to write and easier to scan.

Raw Markdown:

# Hello
**bold text**

Rendered output:

Hello

bold text

How does Markdown work?

Markdown works by using a parser to interpret plain text symbols and convert them into formatted output. For example, # becomes a heading, **text** becomes bold text, and [link text](https://example.com) becomes a hyperlink. The exact output depends on the renderer.

Because Markdown is plain text, you can edit it in almost any text editor, store it in Git, and render it later in tools like GitHub, documentation platforms, or static site generators. That makes it a practical format for collaborative writing.

Is Markdown the same as HTML?

No. Markdown and HTML solve related but different problems.

  • Markdown is a shorthand syntax for writing formatted text quickly.
  • HTML is a markup language that defines structure and presentation more explicitly.

You can include some HTML inside Markdown in many renderers, but support varies. If you need precise layout control, HTML is more flexible. If you want something easy to write and review, Markdown is usually better.

Why is Markdown so popular?

Markdown is popular because it is simple, portable, and readable before it is rendered. Writers and developers can use the same file across tools without learning a complex editor.

It is especially useful for:

  • Documentation
  • README files
  • Knowledge bases
  • Static site generators

Teams also like Markdown because it works well with Markdown editors, supports quick reviews in GitHub, and keeps content close to plain text. That makes it easier to maintain over time.

How do you write headings in Markdown?

Use one to six # symbols at the start of a line:

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

Best practice: use one H1 per page, then organize sections with H2s and H3s. Headings also create anchor links that can be used in a table of contents.

How do you make bold and italic text in Markdown?

Use these patterns:

**bold text**
*italic text*
***bold and italic***

Some renderers also support underscores:

__bold text__
_italic text_

Use emphasis sparingly so the text stays readable.

How do you create lists in Markdown?

Markdown supports unordered and ordered lists.

- Item one
- Item two
  - Nested item

1. First
2. Second
3. Third

Keep indentation consistent for nested items. If a list item contains multiple paragraphs, add a blank line and indent the continuation text.

How do you add links and images in Markdown?

Links use square brackets for the text and parentheses for the URL:

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

Images use the same pattern with an exclamation mark in front. The text inside the brackets is the alt text:

![API error screenshot](error.png)

Write alt text that explains what the image shows and why it matters. If you need a link to a section on the same page, use an anchor link.

How do you format code in Markdown?

Use inline code for short snippets and fenced code blocks for longer examples.

Inline code:

Use `code` for short snippets.

Fenced code block:

```html
<h1>Title</h1>


Code fences can also enable **syntax highlighting** when the renderer supports it. This is useful in documentation, README files, and [technical tutorials](https://docsfordevs.com/blog/api-documentation-guide).

## How do you make tables in Markdown?

Tables use pipes and hyphens:

```md
| Syntax | Use |
|---|---|
| `#` | Heading |
| `**text**` | Bold text |

Tables are useful for comparisons, feature summaries, and reference sections. They are common in documentation, but support can vary slightly across renderers.

What is the difference between basic and extended Markdown?

Basic Markdown, sometimes called core Markdown, covers the most common formatting features: headings, paragraphs, emphasis, lists, links, images, code, and blockquotes.

Extended Markdown adds features that are not part of the original core syntax, such as:

  • Tables
  • Task lists
  • Footnotes
  • Heading IDs

The exact set of extensions depends on the platform. For example, GitHub supports some features through GitHub Flavored Markdown, while other tools may follow the CommonMark spec more closely or add their own extensions.

What is GitHub Flavored Markdown?

GitHub Flavored Markdown is GitHub’s Markdown dialect. It extends standard Markdown with features that are useful in GitHub issues, comments, and README files, including tables, task lists, and automatic linking in some contexts.

Because GitHub is one of the most common places people write Markdown, GitHub Flavored Markdown has become a practical reference point for many teams. Still, not every platform supports the same features, so always check the renderer you are using.

What is CommonMark?

CommonMark is a formal specification for Markdown that aims to remove ambiguity and make parsing more consistent across tools. The CommonMark spec defines how core Markdown syntax should behave so different implementations produce more predictable results.

If you need portability across editors, documentation systems, and publishing platforms, CommonMark is a useful baseline to understand.

Which Markdown editor is best?

The best Markdown editor depends on your workflow.

  • Use a plain text editor like VS Code, Sublime Text, or Vim if you want speed, keyboard control, and tight integration with version control.
  • Use a dedicated Markdown editor like Typora, Obsidian, or Mark Text if you want live formatting, writing-focused features, and easier previewing.

The best choice is the one that matches how you write, review, and publish content. If you work on documentation, choose an editor that supports preview, shortcuts, and clean export.

How do I preview Markdown?

Preview options depend on the tool you use.

  • Many Markdown editors include live preview or split view.
  • GitHub renders Markdown automatically in README files, issues, and comments.
  • Documentation tools and static site generators often provide a local preview server.

Previewing helps you catch broken links, bad indentation, table issues, and heading problems before publishing. It is especially important when your content includes tables, code blocks, or task lists.

What are the most common Markdown mistakes?

Common mistakes include:

  • Missing blank lines between blocks
  • Inconsistent indentation in nested lists
  • Broken links or image paths
  • Incorrect heading hierarchy
  • Forgetting alt text for images
  • Relying on features that your renderer does not support

Another common issue is failing to escape special characters. If you want literal characters such as *, _, #, [, ], (, ), or backticks, use a backslash when needed.

Can Markdown be used for documentation and README files?

Yes. Markdown is one of the most common formats for documentation and README files because it is easy to write, easy to review, and widely supported.

It works well for:

  • Project overviews
  • Installation instructions
  • API references
  • Internal documentation

For teams, a shared Markdown style guide helps keep formatting consistent. A reusable documentation template can also speed up content creation and make structure more predictable. If you are building project docs, README best practices and documentation template guidance can help standardize the result.

Does Markdown support footnotes, task lists, and tables?

Sometimes. Support depends on the flavor or renderer.

  • Task lists are commonly supported in GitHub Flavored Markdown.
  • Tables are widely supported in GitHub and many documentation tools.
  • Footnotes are supported in some extended Markdown implementations, but not all.

If you need these features, confirm support in the platform you plan to use.

How do you escape special characters in Markdown?

Use a backslash before a character you want to show literally.

Examples:

\*not italic\*
\# not a heading
\[literal brackets\]

Escaping is important when you are writing technical docs, code examples, or content that includes symbols Markdown normally interprets.

Who created Markdown?

John Gruber created Markdown, and Aaron Swartz helped shape its early development and adoption. Their goal was to make plain text easy to write and easy to read while still allowing simple formatting.

Markdown best practices for teams

If you want Markdown to stay maintainable across a team, use a shared workflow:

  1. Pick one editor or a small set of approved Markdown editors.
  2. Follow a Markdown style guide.
  3. Use a documentation template for repeatable pages.
  4. Preview every file before publishing.
  5. Keep README files aligned with README best practices.
  6. Store content in version control so changes are easy to review.

If your team publishes through DocsForDevs, these habits make it easier to keep documentation consistent across projects.

Conclusion

Markdown is a simple, durable way to write formatted content in plain text. It works well for documentation, README files, knowledge bases, note-taking apps, and static site generators, and it remains popular because it is readable, portable, and easy to preview.

If you understand the core syntax, the differences between basic and extended Markdown, and the behavior of CommonMark and GitHub Flavored Markdown, you can write content that travels well across tools and teams.