Markdown Syntax for Everyday Writing

I write Markdown every day: pull request descriptions, READMEs, notes, blog drafts, issue comments. After a few months it stops feeling like syntax and starts feeling like typing. But the first week is rough, because the rules are scattered across a dozen tutorials and half of them disagree on the edge cases. This is the compact version I wish I had on day one: the handful of rules that cover ninety percent of real writing, plus the GitHub extras you hit the moment you open a repo.

Everything below is plain text. You type characters, a renderer turns them into formatted output. No buttons, no menus, no mouse. That is the whole point.

Headings and Emphasis

Headings use the hash character. One hash is the biggest, six is the smallest. Always leave a space after the hashes:

# Page title
## Section
### Subsection

For emphasis, wrap text in asterisks. One pair is italic, two pairs is bold, three is both. Strikethrough uses double tildes (that one is a GitHub addition, not in the strict spec):

*italic* and _also italic_
**bold** and __also bold__
***bold italic***
~~struck through~~

A common trip-up: if you want a literal asterisk in your text, put a backslash in front of it. Typing *Terms apply turns the rest of the line italic, but \*Terms apply prints the star and leaves the sentence alone. The same backslash trick rescues underscores inside file names like my\_file\_name, which Markdown would otherwise read as emphasis.

Lists, Links, and Images

Unordered lists start each line with a dash, asterisk, or plus. Ordered lists use a number followed by a dot. Indent with two spaces to nest:

- First item
- Second item
  - Nested item
1. Step one
2. Step two

Links have two parts: the visible text in square brackets, then the URL in parentheses. An optional title in quotes shows on hover:

[Toolora](https://toolora.info "Free online tools")

For long documents where the same URL appears repeatedly, reference links keep the prose clean. You write [text][id] inline and define [id]: https://... somewhere else, usually at the bottom. An autolink wraps a bare URL in angle brackets, <https://example.com>, and renders it clickable with no extra text.

Images are links with a bang in front. The text in brackets becomes the alt attribute:

![Build status](https://img.shields.io/badge/build-passing-green)

Watch the bang: ![alt](url) is an image, but ! [alt](url) with a space becomes a link with a stray exclamation point. To make a clickable image, nest the two forms: [![alt](image-url)](link-url). That nested shape is exactly how README badge rows are built.

Code, Blockquotes, and Horizontal Rules

Inline code uses single backticks: type ` npm install ` to set a phrase in monospace. For a block of code, fence it with three backticks. Add a language hint after the opening fence for syntax highlighting:

function greet(name) { return Hello, ${name}; }

Fenced blocks are the GitHub-flavored way and the one you want most of the time, because nothing inside needs escaping. Everything between the fences is literal.

Blockquotes start a line with a greater-than sign. Stack them for nesting:

> This is quoted.
>
> > And this is nested deeper.

A horizontal rule is three or more dashes, asterisks, or underscores on their own line. I use --- to break a long note into sections.

Tables and GitHub Extras

Pipe tables are the GitHub addition people reach for most. A header row, a separator row of dashes, then data rows. Colons in the separator control alignment, left, center, or right:

| Tool      | Type     | Free |
| :-------- | :------: | ---: |
| Markdown  | Writing  | Yes  |
| JSON      | Data     | Yes  |

One cell of dashes per column, and the column count has to match across rows. Inline formatting like bold and links works inside cells, but block content like lists does not. If hand-aligning those pipes feels tedious, the Markdown table generator builds and aligns the grid for you so you can paste finished output.

GitHub also gives you task lists, which render as checkboxes:

- [x] Write the draft
- [ ] Review the draft
- [ ] Publish

These power the checklist you see in GitHub issues and PRs. Combined with fenced code, strikethrough, and autolinks, they make up the "GitHub Flavored Markdown" extras that go beyond the strict CommonMark spec.

A Worked Example: A Small README Section

Say you are adding a quickstart section to a project README. You want a heading, a short intro, a numbered list of steps, and a link to the docs. Here is the source:

## Quickstart

Get the project running in three steps.

1. Clone the repo with `git clone`.
2. Install dependencies with `npm install`.
3. Start the dev server with `npm run dev`.

See the [full setup guide](https://example.com/docs) for details.

That renders as a clean ## Quickstart heading, one plain sentence, three numbered steps with inline code for the commands, and a clickable link at the end. The two things people forget here: leave a blank line above the list, or it merges into the paragraph above; and wrap the commands in backticks so npm install reads as a command, not prose. Build it once this way and you can copy the skeleton into every project.

A Quick Reference

Keep these eight rules within reach and you can write almost anything:

# Heading 1   →  largest heading
**bold**      →  bold text
*italic*      →  italic text
- list item   →  bullet
1. item       →  numbered list
[text](url)   →  link
![alt](url)   →  image
`code`        →  inline monospace

That table, the live preview pane, and fifty more rules with copy buttons live on the Markdown cheat sheet, where you can see each rule's source next to what it renders. The deeper you go, the more the small flavor differences matter, but those eight cover the daily grind.

Markdown rewards muscle memory. The syntax is small on purpose, so once these rules are in your fingers you stop thinking about formatting and get back to the writing.

Made by Toolora · Updated 2026-06-13