What Is Markdown and How Do You Use It?

The basics of the lightweight formatting language you'll see on GitHub, Notion, and beyond.

Summary

Markdown is a lightweight markup language that lets you write headings, bold text, lists, and links in plain text without opening a word processor. Learning a handful of symbols covers most everyday needs.

Step by step

For headings, start a line with #; the more # symbols, the smaller the heading.
Use **text** for bold and *text* for italics.
Start a line with - or 1. for a list item.
Use a preview tool to see your Markdown rendered as actual formatted output.

Why it matters

Markdown files are plain text. They open in any editor, can be compared line by line in version control, and will still be readable years from now. If a word processor file gets corrupted or you switch programs, formatting can be lost. In Markdown the formatting lives inside the text itself, and it is readable even before it is rendered. That is why it is so common for project READMEs, technical docs, note apps and forum posts.

It is not the same everywhere

There is no single official version of Markdown. The core syntax is nearly universal, but tables, task lists and strikethrough are extensions that some platforms add. A table that renders fine on GitHub may show up as raw text in another note app. Knowing where your content will be displayed tells you which features are safe to use.

Common mistakes

No blank line before a list. Many renderers treat list lines directly under a paragraph as part of that paragraph.
Expecting a single Enter to start a new line. In most cases you need an empty line between paragraphs.
Pasting code outside a code block. Asterisks and underscores in code can turn into italics or bold by accident.
Forgetting a backslash before an asterisk or hash sign when you want the literal character to show.
Inconsistent indentation in nested lists. If sub-items use different amounts of spacing, the list structure can break.

An example

Say you are writing a README for a small software project. You put the project name at the top as a large heading, then a short description paragraph, then a smaller heading called Installation. The install commands go inside a code block fenced with three backticks, so nothing gets reformatted when someone copies them. Contribution rules go in a numbered list. Before you push the file, you open it in a preview tool to confirm the heading levels and lists look the way you expect.

When Markdown is not enough

If you need a complex page layout, multiple columns, tables with merged cells, or precise print formatting, Markdown runs out of road. In those cases it often works better to draft in Markdown and convert to HTML or PDF afterwards, or to use a proper layout tool from the start.