Markdown: the lightweight text format

Markdown is a lightweight markup language designed so that plain text is both easy to write and easy to convert to HTML and other formats. Unlike HTML, Markdown reads comfortably in raw form — unrendered — because its formatting symbols mimic the informal typographic conventions people already used in emails and forums.

The basic syntax includes headers with #, **bold**, *italic*, lists with -, links with [text](url) and code blocks with backticks. The result is a plain-text document that is also easily rendered to clean HTML.

History & evolution

Markdown was created in 2004 by John Gruber with the collaboration of Aaron Swartz. The goal was to create a plain-text format that could be converted to valid HTML without the complexity of manual markup.

The turning point came when GitHub adopted Markdown for README files in 2008, making it the de facto standard for software project documentation. Stack Overflow, Reddit and many other platforms soon integrated it.

The lack of a formal specification led to a proliferation of incompatible dialects. Standardisation efforts like CommonMark (2014) have achieved some harmonisation. Today, Markdown is the default format on GitHub, GitLab, Notion, Obsidian and thousands of documentation tools.

Best practices

Know the dialect variants in use. GitHub Flavored Markdown supports tables, task lists and syntax highlighting in code blocks; original Markdown does not. Checking the platform-specific documentation avoids rendering surprises.

Consistent hierarchical structure. Using a single H1 per document and correctly ordering heading levels improves accessibility and the semantic structure of the resulting document.

Significant whitespace. Markdown is sensitive to line breaks: a single break sometimes does not create a new paragraph. Separating paragraphs with a blank line avoids unexpected rendering issues.

Avoid inline HTML when possible. Markdown allows mixing HTML, but overusing it eliminates the format's main advantage: readability as plain text. Reserve HTML for cases where Markdown offers no native equivalent.

Use cases

Markdown is the reference format for technical documentation: README files, project wikis, installation guides and API references, because it enables efficient version control with Git. In blogs and content platforms (Ghost, Jekyll, Hugo), it lets writers work without complex WYSIWYG editors. In data science environments, Jupyter Notebooks combine Python code with Markdown text to create reproducible, shareable analytical documents.

Curiosities

  • Aaron Swartz, Markdown's co-author, was also a co-founder of Reddit, creator of the RSS syndication format and a digital rights advocate. He died in 2013 at the age of 26.
  • The name "Markdown" is a wordplay: in typography, "markup" adds information to text. Markdown is the opposite: plain text that simplifies notation.
  • Obsidian, one of the most popular note-taking apps among knowledge workers, uses pure Markdown files that are fully readable without any special software.
  • The CommonMark specification of Markdown documents over 600 edge case examples. Despite its apparent simplicity, the precise formal definition of the format is surprisingly complex.

You might be interested in...

Markdown viewer

Real-time Markdown editor and previewer. Supports headings, lists, links and code. Perfect for documentation and articles.