Markdown

What is Markdown?

Markdown is a lightweight markup language: you write plain text with a few punctuation marks, such as # for a heading or * for emphasis, and a converter turns it into HTML. John Gruber released it in 2004 with help from Aaron Swartz, with the goal of being as readable as possible even before conversion. Files usually end in .md.

How Markdown works

A parser reads the text and emits HTML. The same source can feed a web page, a README or a documentation site.

• # Title becomes a heading, more # signs make lower levels.
• **bold** and *italic* mark emphasis.
• - item starts a bullet list, 1. item a numbered one.
• [text](https://example.com) makes a link, ![alt](image.png) an image.
• Backticks wrap inline code, and three backticks fence a code block.

Flavors and the spec

Gruber's original description left many cases open, such as how much indentation a sublist needs, so implementations rendered the same file differently. The CommonMark specification (version 0.31.2, January 2024) states the syntax unambiguously and includes examples that double as tests. GitHub Flavored Markdown is a strict superset of CommonMark that adds tables, task list items, strikethrough and extended autolinks. A feature you rely on may not exist in another renderer, so check which flavor your tool uses.

Example

A project README might start with # Payments API, a short description, a bullet list of endpoints and a fenced code block with a sample request. Pushed to a repository, it renders as a formatted page. In a static site generator (see static site generation), the same file becomes a web page at build time.

Common mistakes

• Forgetting the blank line before a list or heading, which many parsers need.
• Using a table or task list and assuming every renderer supports it.
• Skipping heading levels, which hurts both outline and accessibility.
• Pasting untrusted Markdown into a page without sanitizing the HTML it produces.
• Using Markdown for layout it cannot express, where rich text or HTML is the better tool.

Markdown in documentation and testing

Teams keep docs, changelogs and test plans in Markdown next to the code, so they go through the same review and CI as everything else. Reusable pieces map well to a content block. LoadFocus publishes its product guides on the documentation site. For pipelines that run checks on every commit, see the guide to GitHub Actions.

FAQ: Markdown

What is Markdown used for?

Writing readme files, documentation, blog posts, notes and chat messages in plain text that converts to HTML. It is popular because the source stays readable and works well with version control.

What is the difference between Markdown and HTML?

HTML describes a page with tags and covers every feature of the web. Markdown is a shorter syntax for common structure like headings, lists and links, and converts to HTML. You can often mix raw HTML inside Markdown.

What is CommonMark?

CommonMark is a specification that defines Markdown syntax unambiguously, with examples that act as conformance tests. It was created because the original description left many cases undefined.

What is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is a strict superset of CommonMark. It adds tables, task list items, strikethrough and extended autolinks.

How do I convert Markdown to HTML?

Use a Markdown parser or a tool that includes one, such as a static site generator, an editor preview or a command-line converter. Sanitize the output if the Markdown comes from users.