Markdown Guide: Getting Started
Markdown is a plain-text formatting syntax that turns typed symbols into structured documents, and the core takes about 10 minutes to learn. John Gruber released it in March 2004 with input from Aaron Swartz, and 22 years later it formats README files on GitHub, notes in Obsidian, and posts on Reddit. The whole system has two parts: a text file saved with an .md extension and a processor that converts that text to HTML. Everything below builds on those two parts.
What Is Markdown?
*Markdown is a lightweight markup language from 2004 that adds formatting instructions to plain text through visible characters such as #, , and >. A # at the start of a line creates a heading. Two asterisks around a word make it bold. A hyphen starts a bullet point. The original release was a single Perl script, Markdown.pl, published on Gruber's Daring Fireball site.
Heavier markup languages, HTML and LaTeX among them, wrap content in tags and commands that clutter the raw file. Markdown took the opposite path. Gruber designed the syntax around one goal: a markdown file reads cleanly as plain text before any conversion happens. The line ## Pricing is obviously a heading even to someone who has never heard of markdown. That readability is why the format spread from blogs in 2004 to GitHub in 2008, Stack Overflow in 2010, and note apps such as Obsidian and Joplin through the 2010s.
How Markdown Differs from WYSIWYG Editors
A WYSIWYG editor such as Microsoft Word or Google Docs applies formatting through toolbar buttons and hides the instructions; markdown keeps every instruction visible as characters in the file. WYSIWYG stands for "what you see is what you get". In Word, you select a phrase and click the Bold button, and the file stores that decision in binary XML you never see. In markdown, you type **launch date** and the two asterisk pairs are the formatting.
The difference shows up at save time. A .docx file opens correctly in a short list of programs, Word, LibreOffice, and Pages chief among them. A markdown file opens in any text editor released since the 1970s, from Notepad to vim to VS Code. Many markdown editors close the visual gap with a split-screen live preview: raw syntax in the left pane, rendered output in the right pane, updated on every keystroke. You get the immediate feedback of Word with the transparency of plain text.
Why People Use Markdown
Writers choose markdown for four practical reasons: portability, platform independence, future-proofing, and reach. Each one traces back to the plain-text foundation.
- Portability. A markdown file moves between applications without conversion. Draft a post in iA Writer, edit it in VS Code, publish it through Ghost. The file never changes shape. Proprietary formats such as .docx and .pages lock content into one vendor's ecosystem.
- Platform independence. Markdown works identically on Windows 11, macOS, Linux, iOS, and Android. The file is UTF-8 text, so a note typed on a phone in 2026 opens byte-for-byte identical on a desktop.
- Future-proofing. Software dies; text files survive. WordPerfect dominated word processing in 1990 and its old files are a recovery project today. A markdown file from 2004 still opens in under a second, which matters for theses, contracts, and book manuscripts that carry 20-year horizons.
- Reach. Platforms including GitHub, GitLab, Reddit, Discord, Notion, and Slack accept markdown input. Learn the syntax once and it pays off across all of them.
How Markdown Processing Works
Markdown becomes a formatted document through a 4-step pipeline: you write an .md file, a processor parses it, the processor outputs HTML, and a browser renders that HTML. The processor, also called a parser or implementation, is the engine inside every markdown application. Popular processors include markdown-it, marked, cmark, and Pandoc, and cmark converts a typical document in under 10 milliseconds.
| Step | What happens | Example |
|---|---|---|
| 1. Write | You save markdown text in a plain file | notes.md with # Q3 Report |
| 2. Parse | A processor reads the syntax | markdown-it scans the # symbol |
| 3. Convert | The processor emits HTML | <h1>Q3 Report</h1> |
| 4. Render | A browser displays the HTML | A styled H1 heading on screen |
Different tools expose different amounts of this pipeline. An online editor with live preview runs steps 2 through 4 invisibly on every keystroke. A static site generator such as Hugo runs the same pipeline across hundreds of files in one build command. The pipeline itself never changes, and the HTML output pairs with any CSS stylesheet or converts onward to PDF, EPUB, or .docx through a tool like Pandoc.
What Is Markdown Used For?
Markdown handles seven common jobs: websites, notes, documents, books, presentations, email, and technical documentation. The same 10-minute syntax covers all seven.
Websites
Static site generators such as Hugo, Jekyll, and Eleventy build entire websites from folders of markdown files. Jekyll, released in 2008, powers GitHub Pages and its free hosting. Content platforms take markdown too: Ghost has a native markdown editor, and WordPress accepts markdown through its block editor. A blog post is one .md file, and version control systems like Git track every edit to it.
Notes and documents
Note applications including Obsidian, Joplin, Bear, and Simplenote store every note as markdown. Obsidian alone keeps each vault as a folder of .md files on your own disk, so a 5,000-note collection stays searchable with standard tools. For one-off documents, letters, meeting minutes, and assignments, a markdown editor exports straight to PDF or HTML, and the PDF prints, attaches to email, or uploads anywhere.
Books and presentations
Leanpub turns a folder of markdown files into a finished ebook in PDF and EPUB formats, and Pandoc does the same from the command line. Authors have shipped complete novels and 300-page technical books this way. For slides, tools such as Marp and Remark convert a markdown file into a presentation deck, with one --- separator per slide, which is faster to revise than a PowerPoint file with 40 hand-formatted slides.
Email and technical documentation
Browser extensions such as Markdown Here convert markdown into formatted HTML email inside Gmail and other webmail clients. Documentation is markdown's home turf: GitHub renders a README.md at the top of every repository, and generators including MkDocs, Docusaurus, and Read the Docs build full documentation sites from .md source files. Docusaurus, released by Meta in 2017, adds versioning and search on top of plain markdown pages.
Markdown Flavors: CommonMark and GFM
A markdown flavor is a specific variant of the syntax, and the two that matter most are CommonMark, specified in 2014, and GitHub Flavored Markdown, specified in 2017. Gruber's 2004 release left edge cases undefined, such as how nested lists indent, so early processors disagreed on output. The same file rendered differently in different tools.
CommonMark fixed that. Published in September 2014 by a working group that included John MacFarlane and Jeff Atwood, the CommonMark spec pins down every parsing rule across more than 600 test cases. Stack Overflow moved its rendering to CommonMark in June 2020.
GitHub Flavored Markdown, or GFM, is a strict superset of CommonMark that GitHub formalized in March 2017. It adds five extensions: tables, task lists, strikethrough, autolinks, and fenced code blocks with language tags. When a product page says it "supports markdown", check which flavor it means, because a GFM table renders as plain pipe characters in a CommonMark-only tool. GFM is the safest default in 2026, and it is the flavor this site's editor renders.
How to Start Writing Markdown Today
Open a browser-based markdown editor, type a # followed by a title, and you have written your first markdown; there is nothing to install and no account to create. A split-pane editor shows the rendered result while you type, which is the fastest feedback loop for learning syntax.
Start with the five highest-frequency elements: # for headings, **bold**, *italic*, - for lists, and [text](url) for links. Those five cover roughly 90% of everyday formatting. Practice by rewriting something real, a meeting note or a to-do list, then save the result as a .md file. From there the basic syntax guide covers all 9 core elements, and the extended syntax guide adds GFM tables, footnotes, and task lists.
Frequently asked questions
Do I need to install software to write markdown?
A web browser is enough; an online markdown editor handles writing, preview, and export with zero installation. Desktop applications such as Obsidian, iA Writer, and VS Code add offline access and local file management once you want them.
What file extension does a markdown file use?
Markdown files use the .md extension, with .markdown as a less common alternative. Both hold identical plain text, and every markdown processor, from cmark to Pandoc, accepts either one.
How long does it take to learn markdown?
The five core elements take about 10 minutes, and the full basic syntax of 9 elements fits into one sitting. GFM extensions such as tables and task lists add another 15 minutes. Compare that with LaTeX, where competent formatting takes weeks.
What is the difference between CommonMark and GFM?
CommonMark is the 2014 base specification that standardizes core markdown parsing, and GFM is GitHub's 2017 superset that adds tables, task lists, strikethrough, autolinks, and fenced code blocks. Every valid CommonMark document is also valid GFM, so writing to GFM is the practical choice.