Back to blog

Markdown Guide: Syntax, Examples, and Cheat Sheet

Markdown guide with syntax, examples, and a handy cheat sheet to help you write, format, and troubleshoot Markdown faster.

Introduction

Markdown is a plain text formatting system that uses simple symbols like #, *, and []() to turn readable text into structured content. It gives you a fast, lightweight way to write once in plain text and convert that text into formatted documents for documentation, README files, notes, blogs, GitHub, GitLab, and AI prompting.

Developers, writers, product teams, and anyone who creates documentation or notes use Markdown because it stays readable before it’s rendered. That makes it easy to draft, edit, share, and move across tools without losing structure.

This markdown guide covers the syntax you’ll use most, the mistakes that cause formatting problems, and the differences between Markdown variants that matter on real platforms. You’ll also get a cheat sheet and examples so you can apply the basics quickly and troubleshoot when a renderer behaves differently than expected.

If you want a practical reference you can return to while writing, editing, or debugging formatting, this guide is built for that. For more resources, visit the DocsForDevs home.

What Is Markdown?

Markdown is a lightweight markup language that stays readable as plain text while adding structure with symbols like # for headings, * for emphasis, and []() for links. For example, # Getting Started becomes a heading, while [OpenAI](https://openai.com) becomes a clickable link.

Compared with HTML, Markdown is simpler to write and scan; HTML is more explicit and verbose because it defines structure and presentation with tags like <h1> and <a>. That makes Markdown easier for collaboration and version control, since text diffs stay clean in Git.

CommonMark is the reference specification for Markdown, providing a baseline for consistent behavior. Platforms like GitHub, GitLab, and Notion may add extensions or custom rendering, so the same Markdown can display slightly differently across tools.

What Is Markdown Used For?

Markdown is used for README files, documentation, notes, blog posts, changelogs, issue templates, and AI prompts. It is especially useful when teams need plain text that is easy to review in GitHub or GitLab and easy to reuse in documentation templates and style guides.

Because Markdown is plain text, it works well in version control and across many editors. That makes it a practical choice for documentation workflows, internal knowledge bases, and prompt engineering tasks where structure matters.

Is Markdown Easy to Learn?

Yes. Markdown is easy to learn because the core syntax is small and consistent. Most people can learn headings, emphasis, lists, links, and code blocks in a short time.

The main challenge is not the syntax itself but the differences between editors and Markdown variants. Once you understand the basic rules and know where CommonMark or GitHub Flavored Markdown adds extra behavior, Markdown becomes straightforward to use.

How Do You Use Markdown?

You use Markdown by typing plain text with special characters that indicate structure. A Markdown file is usually saved with a .md extension, then rendered by an editor, platform, or documentation site.

A simple workflow looks like this:

  1. Write your content in plain text.
  2. Add Markdown syntax for headings, lists, links, images, and code.
  3. Preview the result in your editor or target platform.
  4. Adjust formatting if the renderer behaves differently.

This workflow works well in VS Code, Obsidian, Typora, Notion, GitHub, and GitLab.

Markdown Syntax Basics

Markdown syntax is mostly punctuation plus whitespace: #, *, -, [](), and blank lines do most of the work. The core patterns are easy to learn because they map to a few families: emphasis and inline code for formatting, headings, lists, blockquotes, and tables for structure, and links and images for references. Many rules depend on spacing, especially blank lines between blocks and indentation for nested lists or code blocks.

Some syntax is core Markdown, while features like tables and task lists are common extensions in tools such as GitHub Flavored Markdown. Start with the most useful patterns first: headings, emphasis, lists, links, and code. Once those feel natural, the rest of the guide becomes a set of small variations on the same rules.

Core Markdown Syntax: Headings, Text, Lists, Links, and Code

How do you make headings in Markdown?

Use headings to build structure: # H1, ## H2, ### H3, #### H4, ##### H5, ###### H6. Use one H1 per page, then nest lower levels logically. Paragraphs need a blank line between them; use a single line break only when your renderer supports it.

How do you bold or italicize text in Markdown?

For emphasis, use **bold**, *italic*, ~~strikethrough~~, and `code` for inline code. Example: Use **Markdown** to write *clear* docs and npm install commands.

How do you create lists in Markdown?

Lists improve scanability: - item for unordered, 1. item for ordered, and indent nested items with two spaces or a tab. Example:

  • Setup
    1. Install
    2. Configure

How do you add links and images in Markdown?

Links and images use similar syntax: [Markdown style guide](https://docsfordevs.com/blog/markdown-style-guide-for-teams) and ![Alt text](image.png). Keep alt text specific for accessibility and search context.

How do you format code in Markdown?

Use inline code for short tokens like git status; use fenced code blocks for multi-line examples:

const name = "Markdown";

Add a language identifier for syntax highlighting.

How do you create tables in Markdown?

Tables use pipes and a separator row:

Feature Example
Inline code git status
Fenced code blocks ```js
Syntax highlighting Enabled with a language label

Keep tables simple when possible, because some editors handle wide or complex tables differently.

How do you make a checklist in Markdown?

Task lists use checkbox syntax in GitHub Flavored Markdown and other supported editors:

  • Draft the README
  • Review the documentation
  • Add screenshots

Task lists are useful in README files, issue templates, and documentation workflows.

How do you escape characters in Markdown?

If a symbol like *, _, [, ], (, ), or # should appear as plain text, escape it with a backslash: \*, \_, \[. Escaping characters prevents Markdown from interpreting punctuation as formatting.

Extended Syntax, CommonMark, and GitHub Flavored Markdown

Markdown implementations are not identical, which is why the same file can render differently across editors. CommonMark is the reference spec for predictable baseline behavior, while GitHub Flavored Markdown (GFM) adds popular extensions used on GitHub, GitLab, and many docs tools.

Those differences show up in features like tables, task lists, horizontal rules, and blockquotes. GitHub, GitLab, Notion, Obsidian, and Typora each support different subsets and platform-specific behaviors, so a table or task list that works in one app may break or display differently in another.

For a reliable workflow, test your content in the destination platform before publishing, especially when you depend on extended syntax.

Markdown Cheat Sheet, Tools, Best Practices, and Common Mistakes

Quick Markdown cheat sheet

  • # Heading 1 through ###### Heading 6 — headings
  • **bold** or __bold__ — bold
  • *italic* or _italic_ — italic
  • - item or 1. item — unordered and ordered lists
  • [text](https://example.com) — links
  • ![alt text](image.jpg) — images
  • `inline code` and fenced blocks with ``` — code
  • | A | B | with separator rows — tables
  • - [ ] task and - [x] task — task lists
  • > quoted text — blockquotes

A good guide should help you use these patterns consistently, not just memorize them.

Best Markdown editors

For writing and reviewing Markdown, VS Code is the most flexible choice because it combines live preview, shortcuts, extensions, and Git integration. Obsidian works well for linked notes and personal knowledge bases. Typora offers a clean WYSIWYG-style writing experience. Notion is useful when your team wants collaborative docs with light Markdown support. GitHub and GitLab are essential when you want to see how Markdown renders in the platform where the file will live.

What to look for in a Markdown editor

A strong editor should give you:

  • live preview or split-screen preview
  • keyboard shortcuts for headings, lists, and code blocks
  • export options such as HTML, PDF, or DOCX
  • extension support for linting, snippets, and formatting

If you write documentation often, the editor should also match your target platform so you can catch rendering differences early.

Best practices for clean Markdown

Use descriptive headings that tell readers exactly what each section covers. Keep formatting consistent across files, especially for lists, tables, and code fences. Add alt text to images so the content remains accessible and useful in text-only contexts. Test the final output in the platform where it will appear, whether that is GitHub, GitLab, a docs site, or Notion.

For team workflows, pair Markdown with a Markdown style guide and a reusable documentation template. That keeps structure, tone, and formatting aligned across contributors.

Common mistakes to avoid

Broken links, missing spaces after list markers, bad indentation in nested lists, and unescaped characters are the most common problems. If a symbol like *, _, [, ], (, ), or # appears as plain text, use escaping characters with a backslash: \*, \_, \[.

Also watch for:

  • forgetting a blank line before and after blocks
  • mixing tabs and spaces in nested lists
  • using inconsistent heading levels
  • writing image syntax without alt text
  • assuming one Markdown renderer behaves like another

Markdown in Documentation and AI Workflows

Markdown works best when it sits inside a repeatable documentation process. Teams use it to build README files, internal docs, and templates that stay easy to review in GitHub and GitLab. It also fits naturally into AI prompting and prompt engineering because plain text structure makes instructions clearer and easier to reuse.

If you want a practical next step, start with a simple file, apply a team README best practices checklist, and standardize your format with DocsForDevs resources. From there, you can turn this guide into a shared system for writing, reviewing, and generating documentation faster. Explore the DocsForDevs home to continue.