What Is Markdown? A Complete Guide to Markdown Syntax and Formatting

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its goal is to allow people to write content in a plain-text format that is easy to read and write, while being convertible to valid HTML. Markdown files use the .md extension and are supported by virtually every development platform, content management system, and note-taking application.

The key philosophy behind Markdown is that a document should be readable even in its raw form, without requiring special rendering. This makes it ideal for version control, collaborative editing, and technical documentation.

Headers

Markdown supports six levels of headers, created by prefixing text with one to six hash symbols:

• # Heading 1 — The largest heading, typically used for page titles
• ## Heading 2 — Major section headings
• ### Heading 3 — Subsection headings
• #### Heading 4 through ###### Heading 6 — Progressively smaller headings

Text Formatting

Markdown provides simple syntax for basic text formatting:

• Bold text: Wrap text in double asterisks (**bold**) or double underscores (__bold__)
• Italic text: Wrap text in single asterisks (*italic*) or single underscores (_italic_)
• Strikethrough: Wrap text in double tildes (~~strikethrough~~)
• Inline code: Wrap text in backticks (`code`)

Lists

Markdown supports both ordered and unordered lists:

• Unordered lists: Use asterisks (*), plus signs (+), or hyphens (-) as bullet markers
• Ordered lists: Use numbers followed by periods (1., 2., 3.)
• Nested lists: Indent items with two or four spaces to create sub-lists

Links and Images

Adding links and images is straightforward:

• Links: [Link text](URL) creates a hyperlink
• Images: ![Alt text](image-url) embeds an image
• Reference links: Define links at the bottom of the document for cleaner readability

Code Blocks

For multi-line code, use triple backticks (```) or triple tildes (~~~). You can specify the programming language after the opening fence for syntax highlighting:

function greet(name) {
  return `Hello, ${name}!`;
}

Tables

Markdown tables use pipes and hyphens to create rows and headers. While basic tables are part of standard Markdown, extended features like cell alignment use the GitHub Flavored Markdown (GFM) specification.

Blockquotes and Horizontal Rules

Blockquotes are created with the > symbol and are useful for citing sources or highlighting important information. Horizontal rules can be created with three or more hyphens (---), asterisks (***), or underscores (___).

Markdown's simplicity and universality make it the go-to format for developers, writers, and anyone who needs to create well-structured text content quickly.