What Is Markdown and How Do You Use It? A Beginner's Guide

What Is Markdown, and Why Did It Appear?

Markdown is a lightweight markup language designed by John Gruber in 2004 to quickly turn plain text into formatted HTML. The aim was to let writers create headings, bold text, lists or links with just a few simple symbols, without wrestling with HTML tags.

Markdown's core philosophy is this: a Markdown file should be understandable and readable even when read as plain text, without being converted at all. A # sign represents a heading, a pair of * marks emphasis, a - sign a list item; unlike raw HTML tags, these do not break the flow of the text or tire the eye.

That design decision has a practical consequence: when you read a Markdown file in a plain text editor with no converter at all, the content largely stays understandable. The same cannot be said of HTML; an HTML source full of tags becomes a structure that is hard to follow when read outside a browser. Markdown keeps the writing and reading experience on plain text first, and the conversion in the background.

The Core Syntax Elements

Markdown's core syntax consists of a small number of rules and is shared by almost every Markdown tool:

Code blocks are opened with three consecutive backticks and closed the same way; every line in between is shown as it is, unformatted, in a monospaced font. This keeps line breaks and indentation intact, which matters especially when sharing code examples, because characters such as * or # inside a code block are not interpreted as formatting symbols.

Where Is Markdown Used Today?

On almost every code hosting platform, GitHub first among them, project descriptions are written in Markdown in README.md files. Static site generators (such as Jekyll, Hugo and Astro) and documentation tools also use Markdown files directly as their content source; the author writes plain text, and the tool converts it to HTML automatically during the build. The same approach applies to technical documentation wikis and static blog engines.

Messaging applications such as Slack and Discord also support a subset of Markdown — usually *bold*, _italic_, ~~strikethrough~~ and code blocks work, but more complex elements such as headings or tables are not supported. So you should not assume the same syntax will render identically on every platform; check which subset each environment supports.

Note-taking applications (such as Obsidian and Notion) and issue/pull request descriptions are built on Markdown too; a developer writes Markdown dozens of times a day without noticing. That ubiquity makes learning Markdown a matter of learning the common language of many platforms rather than of a single tool.

The Difference Between GitHub Flavored Markdown (GFM) and Core Markdown

The original Markdown syntax did not include elements such as tables or task lists; GitHub defined its own extension set to fill that gap, and it was named GitHub Flavored Markdown (GFM). GFM became so widespread over time that many people now mean GFM when they simply say Markdown; John Gruber's original definition, however, does not include these extra features. GFM adds a few practical features on top of core Markdown:

• Tables — columns separated by the | character and a divider line drawn under the header row
• Task lists — checkboxes that can be marked with - [ ] and - [x]
• Strikethrough text — ~~text~~
• URLs becoming clickable automatically without any link syntax (autolinking)

The preview tool on this site deliberately focuses on core Markdown: headings, bold/italic, inline and block code, lists, quotes and links are supported; full GFM (tables, task lists, strikethrough) is out of scope. The raw text you enter is first fully escaped as HTML, and only then are the safe tags the tool generates itself added; link addresses become clickable only if they begin with http:, https: or mailto: or are a relative path, while dangerous schemes such as javascript: are automatically dropped to plain text.

Common Beginner Mistakes

• Forgetting the space after the heading marker — #Heading is not recognised as a heading by most parsers; # Heading is required.
• Not leaving a blank line between list items and the surrounding paragraphs — some parsers merge the list into the preceding paragraph or do not detect it as a list at all.
• Mixing the - and * markers within the same list — in some tools this can split a single list in two.
• Using inconsistent indentation in nested lists — a sub-item can end up attached to the wrong level instead of the parent item it belongs to.
• Mixing raw HTML tags into Markdown — many simple previewers convert raw HTML to plain text for security reasons, so the tag you expect is not rendered.

Seeing the result as you type, rather than memorising the syntax, both speeds up learning and lets you spot formatting mistakes early. Small but annoying errors such as list indentation, blank-line rules and link syntax are far easier to deal with when you see them while writing rather than after publishing the text.