Markdown Formatting Guide: Syntax, Examples, and Tips

Introduction

Markdown formatting turns plain text into structured content with simple symbols, so you can write readable files without a heavy editor. Plain text stays portable, easy to version control, and easy to publish across tools that power README files, documentation, and content management systems.

This markdown formatting guide is for beginners learning the basics, writers shaping clean content, developers maintaining docs, and documentation teams working in plain text workflows. You’ll learn the core Markdown syntax, where extended features like tables, task lists, footnotes, and definition lists fit in, and how different Markdown flavors can change what renders correctly.

The examples focus on real use cases: README files in GitHub and GitLab, product documentation, and CMS workflows in tools that support Markdown editors. You’ll also see how to avoid common rendering issues, such as broken lists, inconsistent headings, and features that work in one platform but fail in another.

If you want a quick refresher first, start with Markdown basics and Plain text formatting.

What Is Markdown?

Markdown is a lightweight markup language for formatting plain text into structured content. You write symbols like #, *, [](), and > directly in the text, and Markdown processors convert that plain text into HTML for publishing on the web. For a deeper primer on the basics, see Markdown basics and Plain text formatting.

Unlike WYSIWYG editors and other rich-text tools, Markdown keeps formatting visible in the source instead of hiding it behind toolbar buttons. That makes it popular for documentation, blogs, note-taking, collaborative writing, README.md files, and content management systems. In many teams, Markdown is the default format for developer documentation because it is easy to review in plain text and works well in version control.

CommonMark is the baseline spec many tools follow, but implementations vary, so the same Markdown can render slightly differently across platforms. If you need predictable output, check the CommonMark spec and test the result in your target Markdown editor or Markdown processor.

Why Use Markdown for Formatting?

Markdown is faster to write than formatting through a toolbar because you stay in plain text and use simple syntax instead of clicking through menus in WYSIWYG editors. That speed matters when you draft Markdown content formatting for README files, release notes, or Markdown for documentation.

Plain text Markdown also works well with GitHub, GitLab, and other version control tools because changes are easy to diff, review, and merge in code reviews. Teams can track exactly what changed in documentation without wrestling with hidden formatting. Markdown editors and documentation platforms also preserve the same structure across tools, which reduces copy-paste errors.

Compared with rich-text editors, Markdown is easier to maintain over time because the source stays readable and consistent. That makes it a strong fit for developer documentation and collaborative content workflows where multiple people need to update the same files without breaking formatting.

Markdown Basic Syntax

The core Markdown elements to learn first are headings, paragraphs, emphasis, blockquotes, lists, links, images, code, and horizontal rules. Use # for headings, blank lines for paragraphs, *italic* or **bold** for emphasis, and > for blockquotes. Create ordered lists with 1. and unordered lists with - or *; GitHub Flavored Markdown also supports task lists like - [ ] Draft and - [x] Review. Use Markdown style examples and Markdown formatting checklist to compare patterns.

Inline code uses backticks, like npm install, for short commands or filenames; fenced code blocks use triple backticks for multi-line examples and can include a language tag such as bash for syntax highlighting. Use [text](https://example.com) for links and ![alt text](image.jpg) for images. Separate sections with horizontal rules like ---. If you need literal symbols, escape them with backslashes, such as \* or \#, so Markdown does not format them accidentally.

Markdown Extended Syntax and Platform Features

Extended Markdown syntax adds platform-specific features beyond the core spec, so support depends on the Markdown processor you use. Common examples include tables, footnotes, definition lists, and heading IDs for linking directly to sections in docs. Writers use heading IDs to build a table of contents and create stable anchor links that jump to “Installation” or “API Reference” sections.

Some processors also support autolinks, embedded HTML, emoji, highlight, subscript, and superscript, but HTML may be sanitized or blocked. GitHub Flavored Markdown powers much of GitHub and is also used differently by GitLab and documentation tools, so feature support is not identical. Before you rely on any extension in a markdown formatting guide, verify the platform’s Markdown processors and test the output.

Markdown on GitHub and Documentation Platforms

Markdown is widely used in GitHub repositories, especially in README.md files, where GitHub Flavored Markdown renders headings, links, code blocks, task lists, and tables directly in the browser. That makes README files the first place many users see project documentation, so clarity and predictable formatting matter.

Rendering differs across GitHub, GitLab, documentation tools like Docusaurus or MkDocs, and content management systems. Some Markdown processors support task lists, tables, footnotes, or heading IDs differently, and raw HTML may be stripped or sanitized in CMS platforms. When portability matters, write to the lowest common denominator and avoid relying on platform-only features.

Preview content in the target Markdown editor or processor before publishing, especially for Markdown for documentation and Developer markdown guide.

Common Markdown Mistakes and Best Practices

Most Markdown rendering problems come from small syntax errors, not broken tools. The most common issues are missing blank lines around headings, lists, and code blocks; inconsistent indentation in nested lists; forgetting to escape characters like *, _, [, ], and # when they should appear as literal text; and using syntax that the platform does not support. If a list breaks unexpectedly, check the spacing first. If a heading or table looks wrong, compare it against the rules in your platform’s Markdown formatting checklist.

Platform choice matters as much as syntax. CommonMark gives you a reliable baseline, while GitHub Flavored Markdown adds features such as task lists, tables, and strikethrough that work well in GitHub and many developer tools. Before you write documentation or developer documentation, confirm what the target Markdown editor or publishing system supports. Use the simplest syntax that renders correctly everywhere you need it.

Keep headings hierarchical, use descriptive link text, and write useful alt text for images. Prefer relative links for files inside the same repository so content stays portable across branches and environments. Use syntax highlighting in fenced code blocks when it improves readability, but avoid over-formatting with too much bold, italics, or nested styling. Reserve raw HTML for edge cases that Markdown cannot handle cleanly.

For style consistency, follow one format for lists, headings, and code fences throughout the document. If you need examples, compare your draft with Markdown style examples and keep a Markdown cheat sheet nearby while you edit.

Quick Answers to Common Markdown Questions

What is Markdown formatting?

Markdown formatting is a way to style plain text with simple symbols so it can be converted into structured content. It is commonly used in documentation, README files, and content management systems.

How do you format text in Markdown?

You use Markdown syntax directly in plain text. For example, # creates headings, **bold** makes bold text, *italic* makes italic text, and > creates blockquotes.

What are the basic Markdown syntax elements?

The basic elements include headings, paragraphs, bold and italic text, blockquotes, ordered lists, unordered lists, links, images, inline code, fenced code blocks, and horizontal rules.

How do you make headings in Markdown?

Use one or more # symbols at the start of a line. One # creates an H1, two create an H2, and so on through H6.

How do you add bold and italic text in Markdown?

Use double asterisks or double underscores for bold, and single asterisks or single underscores for italic. For example, **bold** and *italic*.

How do you create lists in Markdown?

Use numbers for ordered lists and hyphens or asterisks for unordered lists. For task lists in GitHub Flavored Markdown, use - [ ] for incomplete items and - [x] for completed items.

How do you make a link in Markdown?

Use the format [link text](https://example.com). For files in the same repository, relative links are often better because they stay portable.

How do you add images in Markdown?

Use ![alt text](image.jpg). The alt text should describe the image clearly for accessibility and fallback display.

How do you write code blocks in Markdown?

Use fenced code blocks with triple backticks:

npm install

You can also use indented code blocks in some processors, but fenced code blocks are easier to read and support syntax highlighting.

What is the difference between inline code and code blocks?

Inline code is for short snippets inside a sentence, such as README.md or npm install. Code blocks are for multi-line examples, commands, or samples that need their own formatting.

How do you escape special characters in Markdown?

Use escape characters, usually a backslash, before symbols that Markdown would otherwise interpret as formatting. Common examples include \*, \_, \#, \[, and \].

What is extended Markdown syntax?

Extended Markdown syntax refers to features beyond the core Markdown spec, such as tables, footnotes, definition lists, task lists, heading IDs, and autolinks. Support depends on the Markdown flavor or processor.

Does Markdown support tables?

Yes, many Markdown flavors support tables, including GitHub Flavored Markdown and CommonMark-based processors with extensions. Always test table rendering in your target platform.

How do task lists work in Markdown?

Task lists use checkbox syntax like - [ ] for open tasks and - [x] for completed tasks. They are commonly supported in GitHub and GitLab.

Can you use HTML in Markdown?

Yes, many Markdown processors allow HTML, but some platforms sanitize or block it. Use HTML only when Markdown cannot express the layout cleanly.

Why is my Markdown not rendering correctly?

Common causes include missing blank lines, incorrect indentation, unsupported syntax, broken links, and platform differences between Markdown processors. Check the CommonMark spec or your platform’s documentation, then preview the file in the target Markdown editor.

What is the best Markdown flavor to use?

Choose the flavor that matches your destination. CommonMark is a reliable baseline, GitHub Flavored Markdown is best for GitHub-centric workflows, and GitLab or documentation platforms may add their own extensions.

Is Markdown good for documentation?

Yes. Markdown is widely used for documentation and developer documentation because it is readable in plain text, easy to review in version control, and supported by many documentation tools.

How do section links work in Markdown?

Section links usually rely on heading IDs or anchor links generated from headings. Some platforms let you link to a section with a URL fragment, such as #installation, and many README files include a table of contents for quick navigation.

What are Markdown best practices?

Use consistent heading levels, write descriptive link text, add useful alt text, prefer relative links when appropriate, escape special characters when needed, and test your content in the target Markdown processor before publishing.

Quick recap: use blank lines, consistent indentation, escaped characters, and platform-supported syntax; choose CommonMark or GitHub Flavored Markdown based on the destination; keep links, alt text, and headings clear; use HTML sparingly. Next, practice in a sample document and verify the output in your target Markdown editor before publishing.