Markdown is the closest thing the development world has to a universal writing format. It powers README files on GitHub, GitLab, and Bitbucket. Documentation sites built with MkDocs, Docusaurus, GitBook, and Sphinx use it as their primary authoring format. Blogging platforms like Ghost and Hashnode render it directly. Chat tools like Slack and Discord support Markdown-flavored text formatting. Learning Markdown well is not just about syntax memorisation — it's about understanding how the format works, where its different dialects diverge, and how to use it to produce consistently well-structured technical content.
Markdown's Origins and Design Philosophy
Markdown was created by John Gruber and Aaron Swartz in 2004 with a specific design goal: to produce HTML from plain text using a format that reads naturally as plain text, even before rendering. The original Markdown specification was implemented as a Perl script that converted a lightly structured plain text document into HTML. The "lightly structured" part is deliberate — Markdown syntax mirrors the conventions people already used informally in plain text email and documentation: asterisks around emphasis, leading hash signs for headings, indented code blocks, and angle brackets for block quotes.
This design philosophy has a crucial implication: Markdown documents are readable and meaningful even without rendering. A README.md file read as raw text in a terminal is still understandable. A Markdown-formatted email reads naturally without being processed. This is what distinguishes Markdown from HTML, LaTeX, and other markup languages — it was designed to feel like human writing with light annotation, not like a formal markup language with explicit tags.
The original Markdown specification left many edge cases undefined, which led to different implementations handling them inconsistently. By 2014, there were dozens of incompatible Markdown dialects. CommonMark was created as an unambiguous, formally specified standard for Markdown, defining precise parsing rules that eliminate implementation inconsistencies. GitHub Flavored Markdown (GFM) is a superset of CommonMark that adds tables, task lists, strikethrough, and autolinks.
Core Markdown Syntax
Headings are created by prefixing a line with one to six hash signs. One hash (#) produces an H1, two (##) produce an H2, and so on to six (######) for H6. Atx-style headings (hash signs) are universal. Setext-style headings (underline with equal signs or hyphens) only support H1 and H2. Use atx-style for consistency and compatibility.
Emphasis: wrap text in single asterisks or underscores for italics (*italic* or _italic_), double for bold (**bold**), and triple for bold italic (***bold italic***). In GitHub Flavored Markdown, underscores within words are not interpreted as emphasis markers — only asterisks are, for mid-word emphasis. Using asterisks throughout is the more compatible choice.
Links take the form [link text](URL). Reference-style links define a URL elsewhere in the document and reference it by a label, which is useful for long URLs that would break paragraph flow: [link text][label] with [label]: URL defined elsewhere. Images use the same syntax with an exclamation mark prefix: . Always write descriptive alt text for accessibility — screen readers read alt text aloud for users who cannot see the image.
Code formatting: backtick wrapping produces inline code (`code`); triple backtick fencing produces code blocks with optional language specification for syntax highlighting (```javascript). Use the language identifier consistently — parsers use it for syntax highlighting and some documentation tools use it for code example testing. Indented code blocks (4 spaces or 1 tab) are valid CommonMark but are generally deprecated in favour of fenced blocks for clarity.
GitHub Flavored Markdown Extensions
GFM adds several features absent from CommonMark that are essential for GitHub workflows. Tables are created using pipe characters to separate columns and hyphens to create the header separator row. Task lists use - [ ] for unchecked boxes and - [x] for checked boxes — GitHub renders these as interactive checkboxes in issues and pull requests. Strikethrough wraps text in double tildes: ~~deleted text~~. Autolinks automatically linkify URLs, @mentions, and issue/PR references.
GitHub also supports "fenced code blocks" for Mermaid diagrams (flowcharts, sequence diagrams, Gantt charts, entity-relationship diagrams) using the mermaid language identifier. This is an increasingly powerful tool for technical documentation — diagrams defined in plain text alongside code are version-controlled, diff-able, and consistently styled. If you maintain architecture documentation, API flow diagrams, or data model diagrams in a GitHub repository, Mermaid is worth investing time in.
GitHub's Markdown renderer also supports mathematical notation using LaTeX syntax in code fences with the math identifier or inline with dollar signs, useful for documentation involving algorithms, statistics, or any mathematical content. Footnotes are supported in some extended Markdown flavors (including GitHub's): text[^1] with [^1]: footnote content defined elsewhere.
Markdown in Documentation Systems
Documentation sites built on Markdown typically extend the basic syntax with YAML front matter — a block at the top of each file enclosed in triple hyphens containing metadata like title, description, date, tags, and author. This metadata is processed by the static site generator and used for navigation, search indexing, and page rendering.
Documentation tools like MkDocs and Docusaurus use Markdown extensively and add their own extensions: tabbed code blocks (showing the same code example in multiple languages), admonitions (styled callout boxes for notes, warnings, tips, and cautions), and cross-page references that generate correct relative links in the output HTML. If you're building a documentation site, understanding which Markdown extensions your chosen tool supports is important for writing documentation that renders correctly.
Content management systems for technical blogs (Ghost, Hashnode, Dev.to) use Markdown as their primary authoring format. Understanding Markdown well means you can write efficiently in any of these platforms without fighting their editor, using the right syntax for each context, and knowing which GFM extensions are and aren't supported in a given renderer.
Common Markdown Mistakes
The most common rendering inconsistency is paragraph breaks. In Markdown, a paragraph requires a blank line between text blocks — a single newline within a paragraph is treated as a space, not a line break. New Markdown writers often expect every line break in the source to produce a line break in the output. To force a line break within a paragraph (not a new paragraph), end the line with two trailing spaces or use a backslash before the newline (the latter is a CommonMark extension).
Heading level skipping — jumping from H1 to H3 without an intermediate H2 — creates an invalid document outline that breaks screen readers and accessibility tools. Maintain a logical heading hierarchy: H1 for the page title, H2 for major sections, H3 for subsections. Avoid using heading levels purely for visual sizing; use CSS for that.
Escaping special characters with a backslash is necessary when you want to display characters that Markdown would otherwise interpret as formatting: backslash, backtick, asterisk, underscore, curly braces, square brackets, parentheses, hash sign, plus sign, minus sign, period, and exclamation mark can all be escaped. Forgetting to escape these in non-formatting contexts (particularly in code that isn't wrapped in backtick code formatting) causes unexpected rendering.
Using Our Markdown Previewer
Our free Markdown Previewer renders GitHub Flavored Markdown in real time in a split-pane view — write on the left, see rendered HTML on the right. It supports all standard GFM features including tables, task lists, fenced code blocks with syntax highlighting, and strikethrough. The preview uses consistent styling that approximates how your Markdown will render on GitHub, making it useful for drafting README files, writing documentation, composing blog posts, and learning the syntax interactively.
The tool processes everything locally in the browser — no content is transmitted to any server. This makes it safe for drafting documentation that contains internal project details, proprietary code, or any other content you don't want transmitted over the network. All rendering is done by a JavaScript Markdown parser (marked.js with GFM enabled) running entirely client-side.