Markdown Basics: A Beginner's Guide

Headings and paragraphs

Headings are made with one to six hash characters followed by a space: # is the biggest heading, ###### the smallest. Use one # for the page title, ## for main sections, ### for subsections, and so on — the hierarchy should mirror the structure of your document, not just the size you want the text to be.

Paragraphs are separated by a blank line. A single line break inside a paragraph is ignored by most renderers, which surprises beginners: to force a line break, end the line with two spaces, or simply start a new paragraph. Keeping paragraphs separated by blank lines also makes the source text much easier to read, which is half the point of Markdown.

# Page title

## Section heading

### Subsection

First paragraph of text.

Second paragraph, separated by a blank line.

Emphasis: bold, italic and code

Wrap text in two asterisks for bold (**like this**), one asterisk for italic (*like this*), and backticks for inline code (`like this`). You can combine them: ***bold and italic*** works, and bold text can contain `code` too. For longer code, use a fenced code block: three backticks on their own lines, optionally followed by the language name so the renderer can highlight the syntax.

A few habits keep emphasis predictable. Prefer asterisks over underscores for bold and italic, because underscores interact badly with words that contain them — file_names and variable_names can trigger accidental italics in some renderers. And remember that formatting characters inside a code span are literal: `**not bold**` renders as the literal characters, which is exactly what you want when documenting syntax.

Lists: bullets, numbers and tasks

Bullet lists start each item with a dash, asterisk or plus sign followed by a space. Numbered lists use "1." and friends — and here is a convenience: most renderers renumber automatically, so you can write every item as "1." and the output will still be 1, 2, 3. That makes reordering a list painless, since you never have to fix the numbers by hand.

Indent an item by two or four spaces to nest it under the previous one, and use "- [ ]" and "- [x]" for task lists with checkboxes — a GitHub favorite. The common mistake is forgetting the blank line before a list: without it, some renderers treat the list as a continuation of the previous paragraph and render nothing at all.

- First item
- Second item
  - Nested item

1. First step
1. Second step

- [ ] Task to do
- [x] Finished task

Links and images

A link is [visible text](https://example.com) — square brackets for the text, round brackets for the destination. An image is the same thing with an exclamation mark in front: . The alt text matters: it is what screen readers announce and what shows when the image fails to load, so describe the image rather than writing "image".

For documents with many links, reference-style links keep the text readable: define [text][ref] in the flow and put [ref]: https://example.com at the bottom of the document. Bare URLs in angle brackets, like <https://example.com>, also auto-link in most renderers. And if you need a link with a title that appears on hover, add it in quotes after the URL: [text](https://example.com "Optional title").

Tables, quotes and rules

Blockquotes start with > and are the way to mark quoted text or callouts. A horizontal rule is three or more dashes, asterisks or underscores on their own line. Tables use pipes and dashes: a header row, a separator row, then data rows, with colons in the separator controlling alignment — :--- for left, ---: for right, :---: for center.

Tables are the fiddliest part of Markdown, and every flavor handles them slightly differently — they are part of GitHub Flavored Markdown, not the original spec. Keep columns aligned in the source so the table stays readable as text, and keep cells short: a table is for data, not essays. For anything Markdown cannot express — a colored box, a specific layout, a footnote in plain Markdown — you can drop raw HTML directly into the document, and most renderers pass it through untouched.

| Name | Role | Since |
| :--- | :--- | ---: |
| Ada | Developer | 2021 |
| Grace | Designer | 2023 |

> A blockquote for quoted text.

---

Where you will use Markdown every day

Once you know the syntax, you will see Markdown everywhere. GitHub renders README files and issue comments as Markdown, so project documentation is usually written in it. Chat tools like Slack and Discord support a Markdown-like syntax for bold, italics and code. Note-taking apps such as Obsidian and Bear store notes as Markdown files, which means your notes are plain text you can open anywhere, sync with any tool, and keep for decades without worrying about a proprietary format disappearing.

Documentation sites are the biggest win. Tools like Docusaurus, MkDocs and VitePress turn a folder of Markdown files into a full documentation website with navigation, search and versioning — no HTML required. That is why most open-source projects document in Markdown: the barrier to contributing is low, the source is readable in a pull request, and the rendered site looks professional. Learning Markdown is a small investment that pays off every time you write anything technical.