Markdown cheat sheet: syntax for notes, docs, and READMEs

What Markdown is

Markdown is a lightweight way to format plain text. You write simple symbols, such as # for a heading or * for emphasis, and a renderer turns them into formatted output. The text stays readable even before it is rendered, which is why Markdown is used for README files, documentation sites, wikis, note-taking apps, chat tools, and student notes.

There are a few flavors. CommonMark is a precise specification most modern tools follow, and GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough, and automatic links. The syntax on this page works in CommonMark, with GFM extensions marked.

Headings and paragraphs

# Heading 1
## Heading 2
### Heading 3

A paragraph is one or more lines of text.
Lines next to each other join into one paragraph.

Leave a blank line to start a new paragraph.

The rule that surprises most people: a single line break does not start a new line in the output. Leave a blank line between paragraphs. When you really need a line break inside a paragraph, end the line with two spaces or a backslash.

Use one top-level heading per document and do not skip levels. A clean outline makes long documents easier to navigate and helps tools generate tables of contents.

Emphasis and inline formatting

Use asterisks rather than underscores for emphasis inside words, since underscores in the middle of a word are usually left as plain text.

Lists

- Unordered item
- Another item
  - Nested item (indent two or more spaces)

1. First step
2. Second step
3. Third step

- [x] Finished task (GFM)
- [ ] Open task (GFM)

You can number every ordered item 1. and the renderer will count for you, which keeps lists tidy when you reorder them. Leave a blank line before and after a list so it is not merged with surrounding paragraphs.

Links and images

[UtiliStudio](https://utilistudio.com)
[Link with a title](https://utilistudio.com "Hover text")

![Descriptive alt text](images/diagram.png)

Reference-style links keep long URLs out of the text:
Read the [guide][json-errors].

[json-errors]: https://utilistudio.com/guides/common-json-errors

Always write meaningful alt text for images. It is read aloud by screen readers and shown when an image fails to load.

Code blocks and quotes

Fence code with three backticks on their own lines. Add a language name after the opening fence to enable syntax highlighting where supported.

~~~json
{ "name": "UtiliStudio" }
~~~

> A block quote starts with a greater-than sign.
> It can span several lines.

The example above uses tildes as the fence so it can display backticks; three backticks and three tildes both work as fences in CommonMark.

Tables (GFM)

| Tool            | Category  | Runs in browser |
| :-------------- | :-------: | --------------: |
| JSON Formatter  | Data      | Yes             |
| Focus Timer     | Utilities | Yes             |

Pipes separate columns and the second row separates the header. Colons set alignment: :--- left, :---: center, and ---: right. The pipes do not need to line up, but aligning them keeps the source readable. Keep cell content short; tables cannot contain lists or multiple paragraphs.

Horizontal rules, escaping, and HTML

• A line containing only --- creates a horizontal rule. Leave a blank line above it, or the line above may become a heading.
• To show a symbol literally, escape it with a backslash, such as \*not italic\* or \#not a heading.
• Most renderers allow inline HTML, but many platforms remove scripts, styles, and some attributes. Prefer plain Markdown when the document will be published in several places.

Markdown for school, writing, and documentation

For notes and assignments, Markdown keeps you focused on content instead of formatting menus, and the same file can be exported to HTML or converted to other formats. Headings give structure, lists capture key points, and tables organize comparisons.

For blogs and content, many publishing platforms and static site generators accept Markdown directly. Front matter, a YAML block between --- lines at the top of a file, often stores the title, date, and tags.

For software documentation, Markdown lives alongside the code in version control, can be reviewed in pull requests, and can be compared line by line. Writing one sentence per line keeps those comparisons small and precise.

Common Markdown mistakes

• Missing blank lines. A list or code block written directly under a paragraph is often swallowed into that paragraph. Blank lines around blocks fix most rendering surprises.
• Inconsistent indentation in nested lists. Indent nested items under the text of their parent item, not just under the bullet, and use spaces rather than tabs.
• Forgetting to escape special characters. A filename like my_draft_v2.md or a price with an asterisk can turn into unexpected emphasis. Wrap filenames and code in backticks.
• Broken table rows. Every row needs the same number of columns as the header, and a stray pipe character inside a cell splits it. Escape literal pipes as \|.
• Relying on one platform’s extensions. Footnotes, emoji shortcodes, diagrams, and math work on some platforms and show up as raw text on others.

Writing accessible Markdown

Markdown makes accessible documents easy if you use its structure honestly. Headings should describe the content that follows and appear in order, because screen reader users often navigate a page by jumping between headings. Bold text is not a substitute for a heading.

Write link text that makes sense on its own, such as "read the JSON errors guide", rather than "click here". Give every image alt text that conveys what the image shows, or leave the alt text empty for purely decorative images. Keep tables for genuinely tabular data, and use lists rather than manual line breaks for sequences of items, so assistive technology can announce how many items there are.

Tips for consistent results

• Separate every block, such as headings, lists, code, and tables, with blank lines.
• Pick one style for bullets and emphasis and use it throughout a document.
• Preview before publishing, especially tables and nested lists, since renderers differ in edge cases.
• Check where the document will be shown: extensions such as footnotes, diagrams, or math are not supported everywhere.

Keep learning

• The Pomodoro Technique: a practical guide for study and deep work
• Diff Viewer: Side-by-side visual difference comparison for text, code, and structured data.