What is Markdown? Complete Guide with Examples
Markdown is a lightweight markup language created by John Gruber in 2004 that uses plain-text formatting syntax to create structured documents. It converts simple symbols (# for headings, * for lists, ** for bold) into formatted output, typically HTML. Markdown has become the standard format for README files, documentation, blog posts, forum comments, and note-taking because it's readable as plain text and renders beautifully when processed.
Use our free tools to experiment with markdown.
How Does Markdown Work?
Markdown parsers read plain text and convert formatting symbols to HTML elements. # Heading becomes <h1>Heading</h1>, **bold** becomes <strong>bold</strong>, and [link](url) becomes <a href='url'>link</a>. The CommonMark specification standardizes parsing rules to ensure consistent rendering across tools. Extended flavors like GitHub Flavored Markdown (GFM) add tables, task lists, and syntax-highlighted code blocks. Parsers like marked, remark, and markdown-it handle the conversion.
Key Features
- Simple syntax: # headings, **bold**, *italic*, [links](url), 
- Code blocks with language-specific syntax highlighting via triple backticks
- Tables, task lists, and footnotes in extended Markdown flavors (GFM)
- Readable as plain text even without rendering — no XML-like tags to navigate
- Universal support across GitHub, VS Code, Notion, Obsidian, Jekyll, and hundreds of tools
Common Use Cases
README and Documentation
Every GitHub repository uses README.md as its landing page. Markdown enables developers to write well-formatted documentation with headings, code examples, and links without HTML knowledge.
Blog and Content Writing
Static site generators (Next.js, Hugo, Jekyll, Astro) use Markdown files for blog posts and pages. Writers focus on content while the generator handles HTML rendering and styling.
Note-Taking and Knowledge Bases
Tools like Obsidian, Notion, and Bear use Markdown for notes and knowledge management. The plain-text format ensures portability and longevity of your notes across tools.