Skip to main content
This guide covers the essential Markdown formatting you’ll use in documentation and README files: headings, emphasis, lists, tables, blockquotes, links, images, and code. Each section includes concise examples you can copy and adapt.

​
Headings

Create headings with the hash symbol #. The number of hashes defines the level (one # = H1, six ###### = H6). Use H1 for the main document title and subsections with H2–H4 to keep content scannable for readers and search engines.
Use only one # (H1) per document when possible and structure content with H2/H3 for accessibility and SEO.

​
Emphasis

Use asterisks * or underscores _ to emphasize text.
  • One * or _ for italic
  • Two ** or __ for bold
  • Three *** or ___ for bold + italic
To summarize these markers, here’s a quick reference:
The image explains Markdown basic syntax for text emphasis, illustrating how to apply bold, italic, and bold-italic effects, along with escape characters for plain text.

​
Escaping Markdown Characters

If you need to show literal Markdown characters (for example, an asterisk) without rendering them, escape with a backslash \.
Links and images share a similar syntax. Put the link text in square brackets and the URL in parentheses; prefix with ! to embed an image.
Best practices:
  • Use clear link text that describes the destination.
  • Add descriptive alt text for images to improve accessibility and SEO.
  • For local images in docs, use relative paths.

​
Lists

Use unordered or ordered lists to break down steps or items. Unordered lists accept -, *, or +. For ordered lists, use numbers followed by a period. Indent to create nested lists (2–4 spaces is common).
The image provides a comparison of unordered and ordered list syntax in Markdown, demonstrating basic list formatting.

​
Tables

Markdown tables use pipes | to separate columns and dashes - to separate headers from rows. Put inline code in backticks when table cells contain snippets or commands.
When to use tables:
  • To compare features or commands.
  • To present structured data clearly for readers and search engines.

​
Blockquotes

Blockquotes start with > and are useful for highlighting tips, notes, or quoted text.
The image describes the basic syntax for using blockquotes in Markdown, with an example related to version control.

​
Inline Code and Fenced Code Blocks

Use single backticks for inline code and triple backticks for fenced code blocks. Specify the language immediately after the opening triple backticks to enable syntax highlighting. Inline:
Fenced block with language:
Always specify the language after the opening triple backticks (for example, python) so renderers can apply proper syntax highlighting.

​
Quick SEO & Accessibility Tips

  • Use descriptive headings and alt text for images.
  • Keep link text meaningful (avoid “click here”).
  • Use code fences and language tags for better indexing and readability.
That covers the core Markdown features you’ll use most often when writing documentation and READMEs.

Watch Video