Markdown Explained: Syntax, Flavors, and Practical Uses

Markdown is a lightweight markup language created by John Gruber in 2004 with one explicit goal: readability. A Markdown file should be publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions. That constraint shapes everything about the syntax.

Today Markdown is everywhere: GitHub READMEs, documentation sites, static site generators, note-taking apps, forums, and content management systems all accept it. Understanding the syntax and its variants saves time and prevents surprises when content looks different in different renderers.

Core Syntax

Markdown covers the most common document formatting needs with minimal syntax. Headings use # prefixes (one # for h1, up to six for h6). Bold text is **wrapped in double asterisks**. Italic text uses *single asterisks* or _underscores_. Links are [text](url). Images are . Blockquotes prefix lines with >. Horizontal rules are three or more hyphens on their own line.

# Heading 1
## Heading 2

**bold**, *italic*, ~~strikethrough~~

[Link text](https://example.com)
![Alt text](image.png)

> A blockquote

- Unordered list item
- Another item

1. Ordered list
2. Second item

`inline code`

```javascript
const x = 1;
```

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown (GFM) is the most widely used Markdown extension, adding features absent from the original spec: tables, task lists, strikethrough (~~text~~), fenced code blocks with language identifiers, and autolinked URLs. GFM is the de facto standard for technical documentation because GitHub, GitLab, and most developer platforms support it.

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |

- [x] Completed task
- [ ] Pending task

~~strikethrough~~

CommonMark: The Specification

The original Markdown spec left many edge cases underspecified, leading to inconsistent rendering across implementations. CommonMark (commonmark.org) is a rigorous formal specification that defines exact behavior for every syntactic edge case. Most modern Markdown libraries (including the one used in this site) implement CommonMark as their base. When portable output matters, write to CommonMark and test it.

Converting Between Markdown and HTML

Markdown is compiled to HTML for display. The conversion is one-directional by design: Markdown → HTML is reliable and complete. HTML → Markdown is a heuristic process — HTML can express things Markdown cannot (arbitrary inline styles, nested structures, custom attributes), so converters must make trade-offs. Clean HTML from a CMS or document export converts well; ad-hoc HTML with inline styles or complex tables does not.

Common conversion needs: exporting a blog post written in Markdown to HTML for a mailer; importing HTML from a legacy CMS into a Markdown-based documentation system; stripping all formatting from a document to get plain text for search indexing or LLM prompting.

Markdown in Code Projects

• README.md: the first file every developer reads. GitHub and GitLab render it on the repository homepage.
• CHANGELOG.md: structured release history following formats like Keep a Changelog.
• Docs as code: documentation committed alongside source, rendered by tools like MkDocs, Docusaurus, or Jekyll.
• PR/issue templates: GitHub supports .github/PULL_REQUEST_TEMPLATE.md to pre-populate pull request descriptions.
• Code comments: JSDoc, Python docstrings, and Rust doc comments all support Markdown formatting.