Markdown is a lightweight markup language for creating structured documents in plain text. Introduced by John Gruber in 2004, with substantial input from Aaron Swartz, it combines punctuation-based conventions for headings, lists, emphasis, links, and other document elements with a conversion process originally designed to produce HTML. Its defining design goal is that the source should remain readable without being rendered: a Markdown document should resemble an ordinary text document rather than a page dominated by formatting instructions.
The name refers both to Gruber’s original syntax and conversion program and, more broadly, to a family of related formats. Markdown is widely used for software documentation, project readme files, technical publishing, discussion platforms, and personal notes. Later specifications and implementations, notably CommonMark and GitHub Flavored Markdown, have clarified ambiguous rules and added features. Understanding Markdown therefore involves distinguishing its shared conventions from the behavior of particular parsers, extensions, and publishing systems.
Origins and design principles
John Gruber published Markdown in March 2004 through his Daring Fireball website. The initial release included a syntax description and a conversion program written in Perl, commonly known as Markdown.pl. Aaron Swartz contributed ideas, testing, and feedback during its development. The original software was distributed under a BSD-style license, allowing its incorporation into other projects. Markdown emerged during a period when weblog publishing and web-based writing tools were expanding, but authors often still needed to write HTML directly.
Its central design priority was readability of the unprocessed source. HTML explicitly marks document structure with elements such as <p> and <em>. Markdown instead uses familiar textual conventions: blank lines separate paragraphs, asterisks suggest emphasis, and lines beginning with punctuation indicate lists or quotations. These conventions drew on practices already established in email and other plain-text communication. A document could consequently remain understandable in a basic editor, an email message, or a source-code repository even when no rendering software was available.
Markdown’s design was not an attempt to replace every capability of HTML. The original syntax covered frequently used prose structures while allowing authors to insert HTML for features without a Markdown equivalent. This made it practical for web publishing: authors could write most of a document using simple text conventions and add specialized HTML where needed. The resulting language occupied a middle ground between completely unstructured text and a comprehensive document-description system.
The name plays on the term “markup,” emphasizing a comparatively unobtrusive notation rather than the absence of structure. Markdown still has syntax, precedence rules, and implementation-dependent behavior. Its apparent simplicity chiefly concerns the authoring experience; interpreting nested lists, emphasis delimiters, or embedded HTML can require substantial parser logic.
The original description also left some interactions incompletely specified. It explained common usage effectively, but it was not a formal grammar resolving every possible input. As independent implementations appeared in different programming languages, they made different decisions about ambiguous cases. This combination—an accessible core, permissive implementation culture, and incomplete specification—helped Markdown spread while also producing the dialect differences that later standardization efforts addressed.
Document structure and block syntax
Markdown distinguishes block-level structures from inline formatting. Blocks include paragraphs, headings, quotations, lists, thematic breaks, and code blocks. Inline elements, such as emphasis and links, generally occur inside those blocks. This distinction matters because punctuation acquires meaning in context: an asterisk at the beginning of a suitable line may introduce a list item, while an asterisk inside a paragraph may delimit emphasized text.
Paragraphs normally consist of consecutive nonblank lines. A single source newline usually does not create a new paragraph; a blank line separates paragraphs. In CommonMark terminology, an ordinary newline within a paragraph produces a soft line break, whose rendering can vary. Two spaces before a newline, or a backslash before a newline in CommonMark, produce a hard line break. Some platforms deliberately treat ordinary newlines more aggressively, particularly in comments and messages, so behavior may differ between a repository document and a discussion interface.
Headings use two principal forms. ATX headings begin with one to six number signs followed by suitable separation from the heading text. Setext headings place a line of equals signs or hyphens beneath the text, producing first- or second-level headings respectively. The following example illustrates several block structures:
# Installation
Download the package and unpack it.
## Requirements
- A supported operating system
- Sufficient disk space
> Check the release notes before upgrading.
The heading levels express hierarchy rather than a prescribed visual size. Their actual appearance depends on the output renderer and stylesheet.
Lists can be unordered or ordered. Unordered lists commonly use -, +, or *; ordered lists use numbered markers. CommonMark recognizes both a period and a closing parenthesis after an ordered-list number. The starting number can affect the generated list’s start value, but subsequent source numbers need not determine the displayed sequence. Nested lists and multi-paragraph items depend on indentation and block-continuation rules. Blank lines can distinguish “tight” lists, whose item paragraphs are rendered without surrounding paragraph elements, from “loose” lists.
Block quotations use the > marker and can contain paragraphs, lists, or other quotations. Thematic breaks use suitable lines of repeated asterisks, hyphens, or underscores. Because a line of hyphens may also form a setext heading underline, context determines its interpretation. These interactions explain why superficially similar text can produce different structures: Markdown parsing is not simply a collection of independent punctuation substitutions.
Inline formatting, links, and literal text
Inline syntax gives structure to text within paragraphs, headings, and other containers. Asterisks or underscores ordinarily mark emphasis, while doubled delimiters mark strong emphasis. These constructs normally become HTML <em> and <strong> elements, which express emphasis rather than merely requesting italic or bold type. Exact delimiter behavior varies by dialect. CommonMark, for example, defines rules involving surrounding whitespace and punctuation to reduce unintended emphasis inside words and to resolve nested combinations consistently.
Links combine a visible label with a destination. The usual inline form is [label](destination), optionally followed inside the parentheses by a title. Reference-style links separate the label’s use from its destination definition, allowing repeated references or long addresses to be managed away from the surrounding prose. Images use a related form beginning with an exclamation mark; the text in brackets supplies an alternative description rather than an ordinary clickable label.
Read the [installation guide](guide.html).
Consult the [reference manual][manual].
[manual]: manual.html "Reference manual"

Reference labels have matching and normalization rules; they are not necessarily compared as exact byte sequences. Relative destinations are interpreted in the context supplied by the publishing system. A reference that works in a repository viewer may require rewriting when the same source is published at a different location.
Code spans use backtick delimiters to represent literal text. Delimiters can contain more than one backtick, allowing the enclosed text itself to contain shorter backtick sequences. Code spans suppress ordinary emphasis and link interpretation, making them suitable for identifiers, commands, and syntax examples. Their whitespace handling is defined by the dialect and is not always identical to preserving every source character literally. Larger literal examples belong in code blocks rather than inline spans.
Backslash escapes allow many punctuation characters to appear without their usual structural meaning. They are context-sensitive: an escape recognized in ordinary prose may have no special effect inside a code span. Character references such as & are also supported in ordinary text by major dialects. Authors therefore need to distinguish the characters written in the source from the text produced after parsing.
Links and images expose an important boundary between document content and application behavior. Markdown can describe a destination and label, but it does not itself retrieve a resource, decide whether a destination is safe, or specify how an image is laid out. Those tasks belong to the surrounding publishing software, web browser, or output renderer. Similarly, automatic heading identifiers, image dimensions, and opening links in new windows are not universal features of the original syntax.
Parsing, rendering, and document models
A Markdown processor interprets source text and produces an output representation. The original program primarily converted Markdown to HTML, but later systems often separate parsing from rendering. A parser can construct an abstract syntax tree containing nodes for paragraphs, headings, lists, text, links, and other elements. Different renderers can then transform that structure into HTML, another markup format, or an intermediate representation used by a publishing tool.
Many contemporary parsers operate in two broad stages. Block parsing determines the document’s large-scale organization, including which lines belong to list items, quotations, or code blocks. Inline parsing then identifies emphasis, code spans, links, and related constructs within eligible blocks. This separation helps resolve dependencies: punctuation inside a fenced code block must not be treated as ordinary prose syntax, while text inside a paragraph generally remains eligible for inline interpretation.
An intermediate tree makes transformations possible without repeatedly manipulating raw strings. A tool can collect headings into a table of contents, rewrite relative links, attach source positions to nodes, or inspect image descriptions. These operations depend on data structures representing document meaning rather than its final visual appearance. Source-position information is particularly useful for editor diagnostics and for connecting rendered output with the original file.
Rendering is a separate concern from styling. HTML output may contain structurally correct headings and lists, but their fonts, margins, colors, and responsive behavior are usually controlled by Cascading Style Sheets. Syntax highlighting likewise usually comes from an additional component. A fenced code block may declare a language in an information string, but the Markdown parser need not understand that language or perform highlighting itself.
This processing pipeline also explains why Markdown is not generally a lossless interchange format. Different source forms can produce the same document structure: a heading written with an underline may be equivalent to one written with number signs. Once a processor retains only the interpreted structure, the original spelling, spacing, and reference-link arrangement may be lost. A formatter may therefore preserve meaning while substantially rewriting the source. Systems requiring exact round-trip editing need richer representations that retain syntax details or associate tree nodes with the original text.
Output quality also depends on the target format. HTML naturally accommodates hyperlinks, flowing text, and embedded web content. Pagination, floating figures, numbered equations, and detailed typography require additional conventions or a more expressive publishing layer. Conversion to another format is consequently not just a matter of replacing punctuation with tags.
CommonMark and standardization
Markdown’s early success produced numerous independent implementations, but the original syntax description did not settle every edge case. Parsers differed over questions such as how many spaces were necessary for nested blocks, whether a delimiter could form emphasis inside a word, and when a line interrupted an existing paragraph. Authors could write a document that appeared correct in one application but rendered differently elsewhere.
CommonMark began publicly in 2014 as an effort to define a precise, testable specification for a widely shared Markdown core. John MacFarlane and Jeff Atwood were prominent participants. The project initially used the name Standard Markdown before adopting CommonMark. Rather than relying only on prose examples of ordinary usage, its specification pairs detailed rules with a large collection of input-and-output examples. Those examples also serve as tests against which implementations can be checked.
The specification addresses details that casual users may rarely notice but parser authors must resolve. It defines container blocks, blank lines, tabs, list-marker widths, emphasis delimiter runs, link precedence, and raw HTML blocks. It also formalizes fenced code blocks, which were not part of Gruber’s original documented syntax but had become common in later implementations. A fence consists of a suitable run of backticks or tildes, with a closing fence governed by explicit matching rules.
CommonMark does not simply mean “every feature that a modern Markdown application supports.” Tables, task lists, footnotes, bibliographic citations, and mathematical notation are not all part of its core specification. A processor can implement CommonMark and separately offer extensions. This distinction makes the core useful as a compatibility baseline while leaving applications free to support specialized document types.
Reference implementations include cmark, written in C, and commonmark.js, written in JavaScript. Other parsers have their own architectures and extension systems. Conformance is ultimately about observable interpretation of inputs, not the language in which a processor is implemented.
CommonMark also illustrates a broader tension in language standardization. Strictly retaining every historical parser behavior would preserve contradictions rather than eliminate them, while changing behavior can affect existing documents. Its rules therefore represent a defined interpretation of Markdown, not proof that all older interpretations were identical. The original Markdown description, CommonMark, and platform-specific dialects remain distinct reference points. Stating which one a tool implements is more informative than describing it merely as “Markdown compatible.”
Dialects and extensions
A Markdown dialect combines a core syntax with a particular set of extensions and interpretation rules. Some dialects are formally documented; others are effectively defined by a specific application. The shared visual vocabulary can conceal substantial differences. A table, footnote, or mathematical expression may appear to be ordinary Markdown to users of one platform while remaining plain text in another.
GitHub Flavored Markdown, usually abbreviated GFM, is a prominent example. GitHub published a formal specification in 2017 based on CommonMark. Its specified extensions include tables, task-list items, strikethrough, extended automatic link recognition, and filtering of certain raw HTML constructs. A task-list marker such as [ ] or [x] can produce a checkbox-like display when it appears in the appropriate list context. Whether a checkbox is interactive is a property of the host application, not merely of the syntax.
GFM tables use pipes to separate cells and a delimiter row to distinguish headings from data. Colons in that delimiter row can indicate alignment. This notation is convenient for compact rectangular data but does not supply the full expressive range of HTML tables: merged cells and complex multi-level headers generally require another representation. Long or multiline cell content can also make a plain-text table difficult to maintain.
Other families arose for different purposes. Markdown Extra added features such as tables, definition lists, and footnotes. MultiMarkdown developed richer support for documents involving metadata, notes, tables, and publishing workflows. Pandoc supports an extensive Markdown dialect with configurable extensions and facilities for citations, attributes, and mathematical content. MDX combines Markdown with JSX, allowing documents to incorporate components from a JavaScript application. MDX therefore changes not only available notation but also the execution and trust assumptions of the publishing pipeline.
Many applications add conventions outside the body syntax. A metadata block at the beginning of a file, often called front matter, may define a title, date, author, layout, or tags. YAML is a common notation for such metadata, but front matter is not part of original Markdown or CommonMark. Wiki-style links, callouts, diagram fences, and embedded queries are similarly application-specific unless a chosen dialect explicitly defines them.
Platform features must also be distinguished from dialect features. Repository issue references, user mentions, uploaded attachments, and generated navigation may depend on application data unavailable to a standalone parser. Copying the Markdown source alone does not necessarily reproduce those functions. Portability therefore depends on both syntax compatibility and the availability of the services surrounding the document.
Authoring tools and publishing workflows
Markdown’s plain-text representation makes it suitable for workflows built around Git and other version-control systems. A document can be stored beside the software it describes, reviewed in the same change request, and updated with related code. Textual differences reveal changed words and lines rather than opaque revisions to a binary document. This has made Markdown particularly influential in the “docs as code” approach to documentation.
The most familiar repository example is a README.md file. Hosting services commonly render it automatically as an introduction to a project. Similar files record contribution procedures, release histories, and development notes. Markdown does not determine these conventions, but its low entry cost and readable source fit their purpose. A contributor can make a small correction with an ordinary editor without needing the original author’s publishing application.
Static site generators extend this model into complete websites. Systems such as Jekyll, Hugo, and MkDocs combine source documents with navigation rules, templates, and stylesheets, producing deployable files. Metadata can control page titles or ordering, while themes supply visual design. In this arrangement, Markdown describes much of the page content, but the generator defines important behavior such as URL construction, asset copying, and navigation.
Publishing pipelines frequently include automated checks. A linter can identify inconsistent heading styles, suspicious indentation, or formatting patterns associated with mistakes. Separate checks can validate internal links, detect missing files, or test code examples. These functions are not interchangeable: a document can be syntactically valid yet contain a broken destination or an inaccurate command. Integration with continuous delivery allows documentation changes to trigger preview builds and publication in much the same way as software changes trigger tests and deployment.
Editors range from simple text applications to split-pane environments with a live preview. Some provide rich-text-like editing while storing Markdown underneath. The latter approach can hide syntax details, but it must decide how to represent structures for which the source offers several equivalent forms. Switching between source and visual modes may therefore normalize formatting or rewrite parts of the file.
Markdown is also used in computational notebooks, learning materials, and technical books. A notebook can place prose cells alongside executable code and its output, while a book pipeline can combine chapters, citations, and cross-references. These applications demonstrate the value of Markdown as a lightweight authoring surface, but their richer functions come from the notebook or publishing system rather than from Markdown alone.
Security, accessibility, and international text
Markdown source is text, but rendered Markdown is not automatically safe. A processor may pass embedded HTML through to its output, and links or images may refer to external resources. When content comes from an untrusted author, a publishing system must distinguish parsing from HTML sanitization. Parsing determines what the source means; sanitization restricts which resulting elements, attributes, and destinations may be used.
A central risk is cross-site scripting, in which hostile content causes script to execute in another user’s browsing context. Filtering Markdown punctuation alone does not address every route to unsafe output. A security boundary may need to account for raw HTML, dangerous URL schemes, event-handler attributes, and changes introduced by plugins. Escaping literal text, validating destinations, and sanitizing the resulting HTML solve different parts of the problem.
The trust model changes further when extensions can execute code. A fenced code block normally displays text, but a notebook or publishing plugin may interpret selected blocks as executable instructions. MDX can involve JavaScript components, while diagram or template extensions invoke additional processors. Such documents cannot be evaluated solely as passive Markdown. Their handling belongs to the surrounding system’s cybersecurity design, which may include restricted capabilities or a sandbox.
Accessibility depends on how authors use structure and how renderers express it. Genuine headings provide navigation landmarks for assistive technology; visually enlarged text alone does not necessarily do so. Image descriptions should convey the relevant information or function of an image, but a basic Markdown image construct cannot supply every accessibility feature needed for complex graphics. Similarly, pipe-table syntax may not express sophisticated header relationships. Additional HTML or publishing features may be necessary for more demanding documents.
Markdown commonly uses Unicode text, allowing prose in many writing systems while retaining punctuation-based syntax largely drawn from ASCII. The format itself does not prescribe every file-encoding or display convention; applications commonly use UTF-8. Fullwidth punctuation and visually similar characters are generally not interchangeable with syntax characters. An editor’s typography can therefore make a syntactic difference difficult to see.
International publishing introduces further application-level issues. Right-to-left text, mixed-direction links, line breaking, language metadata, and heading-identifier generation may require support outside the core syntax. Two renderers can display the same multilingual heading correctly yet produce different fragment identifiers for links to that heading. Such behavior affects navigation even when the prose itself is preserved.
Portability and limits of representation
Markdown’s portability has several distinct meanings. Source portability means a file can be opened and read in many tools. Syntactic portability means different parsers recognize the same structures. Presentation portability means the resulting documents look similar. Markdown is strong in the first sense, more conditional in the second, and deliberately limited in the third. A plain-text file survives independently of a particular editor, but its rendering still depends on a dialect, configuration, styles, and assets.
The filename extensions .md and .markdown are widely used, but neither identifies an exact syntax profile. RFC 7763 registered the text/markdown media type in 2016, and the companion RFC 7764 discussed variants and processing practices. These documents recognize that “Markdown” encompasses multiple interpretations. A media type identifies the broad format more reliably than it guarantees support for every extension used inside a file.
Reproducible publishing therefore depends on more than retaining the source. A project may need to record parser versions, enabled extensions, templates, stylesheets, and asset locations. A change to heading-identifier generation can break incoming links even if the visible headings remain unchanged. A syntax-highlighting update can alter generated markup. A remote image may disappear while its Markdown reference remains intact. These are dependencies of the published document rather than defects that plain-text storage alone can prevent.
Compared with HTML, Markdown offers fewer explicit controls and a more compact authoring notation. Compared with LaTeX, it generally provides less built-in machinery for mathematical typesetting, cross-referencing, and precise page composition. Compared with a structured XML vocabulary, it usually imposes fewer constraints on document organization. These differences reflect different design priorities: Markdown favors approachable prose authoring, whereas more elaborate formats can encode richer semantics and publishing requirements.
That simplicity has representational costs. Figures with structured captions, complex tables, indexes, conditional content, and detailed scholarly apparatus usually depend on extensions or external tools. Converting such a document to another Markdown dialect may discard information even when both systems support headings and links. Conversion through HTML can also lose distinctions that were meaningful to the source application.
Long-term maintenance consequently involves identifying which information resides in the text and which resides elsewhere. A paragraph and an ordinary list are largely self-contained; an executable diagram, repository-specific mention, or dynamically generated bibliography is not. The boundary between a readable document and an application-dependent publishing source is determined by the features actually used, not by the .md extension alone.