What is Markdown, in plain terms?
A way of writing formatted text using only the characters already on a keyboard, so the raw file is still pleasant to read even before anything converts it to anything else.
It was created in 2004 by John Gruber, working with Aaron Swartz on the syntax, and released as a Perl script called Markdown.pl that turned a .text file into HTML. Gruber's stated goal was for a Markdown-formatted document to be "publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions" - a sentence that still describes the format's entire design philosophy two decades later.
The name is a small joke: it is the opposite of "marking up" text with angle-bracket tags, while still producing markup as its output.
What does the actual syntax look like?
A small, deliberately short list of conventions, most of which map to something people already did in plain-text e-mail: a line starting with # is a heading (more # characters make it deeper, down to ###### for an h6), asterisks or underscores around a word add emphasis (**bold**, _italic_), a line starting with -, * or a number followed by a period becomes a list item, and a > at the start of a line makes a blockquote.
Links use [text](url), images are the same syntax with a leading !, and inline code sits between backticks, with triple backticks opening and closing a fenced block for multi-line code, optionally tagged with a language name for syntax highlighting.
A horizontal rule is three or more hyphens, asterisks or underscores alone on a line. Two trailing spaces at the end of a line force a line break inside a paragraph, which is one of the format's few genuinely unintuitive rules and a frequent source of confusion for people reading the raw spec for the first time.
Why did this particular format become so popular?
Because the file you write is already almost the document you wanted, which removes an entire category of friction that heavier formats never solved.
A .doc or .docx file needs Word, or something pretending convincingly to be Word, to be useful; a raw HTML file is legible but tedious to type by hand and easy to break. A Markdown file is a .md text file that opens in any editor on any operating system, reads clearly without rendering, diffs cleanly in version control because it is line-oriented plain text, and degrades gracefully - a document with no renderer available is still perfectly readable, just with some asterisks and hash marks visible.
That combination of properties - human-readable, machine-convertible, tool-independent - is what made it the default choice anywhere a document needs to survive being read by a person, parsed by software, and stored in a Git repository, sometimes all three at once.
Is there just one Markdown, or many?
Many, and the differences matter more than most casual users realize.
Gruber's original 2004 specification was intentionally informal - a prose description plus a reference implementation, with several genuinely ambiguous edge cases (nested emphasis, lazy list continuation, what exactly counts as a code block) that different parsers resolved differently. Over the following decade, dozens of implementations - Python-Markdown, Redcarpet, Marked, Showdown, and more - each filled the gaps slightly differently, so the same file could render three different ways depending on which tool opened it.
CommonMark, published in 2014 by a group including Jeff Atwood and John MacFarlane, is the response to that fragmentation: a formal, unambiguous specification with an accompanying test suite of over six hundred cases, designed so that any compliant parser produces byte-identical output for the same input. It is now the de facto baseline most modern tools build on.
GitHub Flavored Markdown (GFM) is CommonMark plus GitHub's own extensions - tables, strikethrough (~~text~~), automatic linking of bare URLs, and task lists (- [ ] / - [x]) - and is, by sheer usage volume across README files and pull request descriptions, probably the most-read Markdown dialect on earth. MultiMarkdown and Pandoc's Markdown go further still, adding footnotes, citations, definition lists and cross-format conversion aimed at academic and technical publishing.
Where does Markdown actually get used today?
Almost anywhere a person writes structured text that also needs to be read as source: repository documentation, static site generators, note-taking software and a surprising number of chat interfaces.
Every major code-hosting platform renders a repository's README.md automatically, which alone made Markdown the default language of open-source documentation. Static site generators - Jekyll, Hugo, Gatsby, Eleventy - take a folder of Markdown files plus YAML front matter and produce a full website, and documentation frameworks like MkDocs, Docusaurus and GitBook are built on the same idea for technical manuals and API references.
Note-taking and personal-knowledge-management tools - Obsidian, Notion's underlying export format, Bear, Logseq and SumizAI among them - store notes as plain .md files specifically so a vault of notes remains readable and portable independent of the application that created it. Slack, Discord and WhatsApp all support a reduced subset for basic chat formatting, and academic writers use Pandoc to draft in Markdown and compile the same source to a PDF, a Word document or a LaTeX file for submission.
How does a Markdown file actually become HTML?
A parser reads the plain text and builds an intermediate tree structure - an Abstract Syntax Tree, or AST - representing the document's headings, paragraphs, lists and inline formatting as nested nodes, then a separate renderer walks that tree and emits HTML (or another target format) from it.
That two-stage design - parse, then render - is what lets the same underlying document become a web page through one renderer, a PDF through Pandoc, or a slide deck through a different tool entirely, without the source file changing at all. It is also why AST-based parsers like remark (JavaScript), cmark (the reference C implementation of CommonMark) and Python-Markdown can support plugins: an extension hooks into the tree between parsing and rendering rather than pattern-matching the raw text, which is far less fragile.
Most modern parsers are also deliberately defensive about untrusted input - CommonMark's specification includes explicit guidance on this - because "convert this text to HTML and put it in a web page" is a textbook cross-site-scripting vector if raw <script> tags or javascript: links inside the Markdown are passed straight through unescaped.
What are the features experienced Markdown users rely on but beginners rarely discover?
YAML front matter is the big one: a block of key: value metadata delimited by --- lines at the very top of a file, which static site generators and note apps read as structured data - title, date, tags, author - without it ever appearing in the rendered document. It is how a folder of plain-text files acquires a database's worth of queryable metadata with no database involved.
Reference-style links ([text][id] with the actual URL defined once elsewhere in the document) keep long documents readable by moving repeated URLs out of the running text. Footnotes (text[^1] with the definition [^1]: the note anywhere in the file) and definition lists exist in most extended dialects but not in bare CommonMark, which is a common source of "this works on GitHub but not in my static site generator" confusion.
Escaping matters more than it looks: a literal asterisk or underscore needs a backslash (\*) precisely because those characters are otherwise significant syntax, and knowing that is usually the difference between someone who has used Markdown casually and someone who has debugged why their file path with underscores rendered half of it in italics.
MDX is the frontier case worth knowing about: Markdown extended to allow embedded JSX components, used by documentation frameworks that need interactive examples inside otherwise static prose - a genuine hybrid of a markup language and a component syntax, and a sign of how far the format has been stretched beyond Gruber's original plain-text goal.
What are Markdown's real limitations, and when is it the wrong tool?
It is a document format for prose with light structure, not a layout system and not a data-interchange format, and both misuses are common.
There is no native way to express a two-column layout, precise typography, or pixel-level positioning - that is what HTML and CSS are for, and most renderers do allow raw HTML inline specifically as an escape hatch for the rare case that needs it. For structured data - configuration, API payloads, anything a program needs to parse reliably - YAML, JSON or TOML are the right choice; Markdown tables exist but are meant for human-readable summaries, not as a serialization format.
The dialect fragmentation described earlier is a real, practical cost: a document using GFM tables or footnotes will silently render as broken or missing syntax in a bare-CommonMark renderer, so portability claims ("it's just plain text, it works everywhere") are only as true as the least-capable tool in the chain actually supports.
And because rendering means converting untrusted text into HTML, any tool that accepts Markdown from outside users and renders it without sanitization is exposing itself to injected scripts and links - a genuine security surface, not a theoretical one, and the reason every serious Markdown library ships a sanitization step or explicit escaping rules for raw HTML.
How does Markdown compare to HTML, reStructuredText and AsciiDoc?
Each of those solves the same underlying problem - writing structured documents as plain text - with a different trade-off between simplicity and power, and the differences are the reason none of them has fully replaced the others.
HTML is the ceiling: it can express anything a browser can render, but writing it by hand is verbose and unforgiving - a single unclosed tag can break a whole page, and nobody drafts a paragraph in <p></p> tags if they have a choice. Markdown deliberately covers a small, common subset of that same output and falls back to raw HTML for anything it does not have its own syntax for, which is why the two are usually described as complementary rather than competing.
reStructuredText, born in the Python documentation community, is stricter and considerably more powerful out of the box - it has native syntax for tables, footnotes, cross-references and directives for arbitrary extensions - at the cost of a steeper learning curve and a much less forgiving parser; a misaligned list indent produces a build error rather than a slightly odd-looking list. AsciiDoc sits a step further in the same direction: it has first-class support for multi-part books, admonitions, conditional includes and cross-document references, and tools like Asciidoctor use it for full technical books and API documentation where Markdown alone would need heavy custom tooling to cope.
The practical rule of thumb professionals use: reach for Markdown when the audience is people reading raw source as often as rendered output; reach for reStructuredText or AsciiDoc when the document is long, deeply structured, and the tooling investment pays for itself; reach for raw HTML only for the specific fragment that genuinely needs it.
What does a serious Markdown writing workflow actually look like?
A plain-text editor with live preview, a linter, and version control - the same toolchain as writing code, which is not a coincidence given where the format's heaviest users came from.
VS Code's built-in Markdown preview, Typora's live-rendering editor, and Obsidian's editing mode are the most common choices; all three render formatting as you type without hiding the underlying plain text, which matters because the whole point of the format is that the source stays legible. markdownlint and similar tools catch the errors that are easy to make and hard to spot by eye - inconsistent heading levels, trailing whitespace with unintended meaning, duplicate link reference definitions - the same category of mistake a code linter catches in a programming language.
Because a Markdown file is line-oriented plain text, it plays natively with Git: a one-line edit produces a one-line diff, merge conflicts are readable instead of being an opaque binary clash, and git blame tells you exactly who changed which sentence and when. Large documentation sets go further still and add a continuous-integration step that renders every Markdown file on every commit specifically to catch broken internal links and malformed syntax before they reach a live site - the same discipline applied to prose that is normally reserved for code.
How does SumizAI use Markdown for the notes it generates?
As the storage format for every single note, by design and without exception: when an AI answer is worth keeping, SumizAI turns it into ai notes - a title, a summary, an expansion and the full original exchange - saved as a plain .md file inside a vault that is just a folder on your own disk.
That choice is the direct, practical payoff of everything above: the ai notes SumizAI writes open in Obsidian, VS Code, a static site generator or any plain-text editor with no import step and no proprietary format to escape from, links between notes are ordinary [text](file.md) Markdown links to files that actually exist, and the vault's table of contents is itself a generated base.md file rather than a database record hidden behind an application.
The database SumizAI keeps is only a search index; the notes ai are the source of truth, and if the application disappeared tomorrow, a folder of ordinary Markdown files is what would be left - readable, portable, and exactly as useful as the format was designed to be in 2004.
Seven days, no card, one dollar after that
Point SumizAI at a folder, connect the AI provider you already pay for, and start a conversation. The first note files itself.