Markdown Cheatsheet

Markdown Cheatsheet

Markdown is a plain-text format for writing content that can be turned into HTML. You use simple punctuation and symbols for headings, lists, links, and code so the file stays readable as-is, and tools like GitHub, VS Code, or static site generators can render it. It’s common in READMEs, documentation, comments, and blogs. You write in a normal editor. The renderer does the rest.

Headings

One to six # at the start of a line, then a space, then the heading. One # for the page title, ## for main sections, ### for subsections.

# Page title
## Section
### Subsection

Bold, italic, code

**bold** or __bold__. *italic* or _italic_. Backticks for inline code: `code`. Strikethrough (GitHub and many tools): ~~strikethrough~~.

In a sentence: “Edit the config.json file.” Use Important: when you want to stress a note.

Lists

Unordered: start a line with - or * and a space. Ordered: 1. then space (the number can be 1 for all, renderers renumber). Nested: indent the next line with two or four spaces.

- Apples
- Oranges
  - Navel
  - Blood
1. First step
2. Second step

Put a blank line before a list so it doesn’t run into the paragraph above.

Nested lists. Indent the nested item with spaces (two or four). The indent must align with the content of the parent item, not the bullet. Some parsers are picky: if a nested list doesn’t render, try four spaces for the inner level.

Task lists (GitHub, GitLab, and many tools). Use - [ ] for an unchecked item and - [x] for checked. The space inside the brackets matters.

- [ ] Install dependencies
- [x] Run the build
- [ ] Deploy

Links and images

Inline link: [text](url). Add a hover title: [text](url "title"). Image: ![alt text](image.png). Alt is required for accessibility.

Internal link: [Pricing](/pricing). External: [Google](https://google.com). Image: ![Logo](logo.png).

Reference-style link when you use the same URL twice: [link][ref] and later [ref]: https://example.com. The reference definition can go anywhere in the document (often at the bottom). Use inline links for one-off URLs and reference-style when the same URL appears multiple times or you want to keep the body readable.

How to add code blocks

Step by step. Start with a line that has three backticks. On the same line you can add a language name (e.g. javascript or python) so the renderer can syntax-highlight. On the next lines put your code. End with a line that has only three backticks. A blank line before and after the block helps many parsers treat it correctly.

Inline code. For a short snippet inside a sentence, use a single backtick on each side: `like this`. Good for file names, command names, or one short line. No newlines.

Syntax highlighting. Put the language id right after the opening three backticks (no space). Common ids: javascript or js, python or py, html, css, bash or sh, json, markdown, sql, yaml. Support depends on the renderer (GitHub, GitLab, VS Code, static site generators each have their own list). Wrong or unknown ids are usually ignored and the block is still shown as code.

Edge cases. To show literal backticks in your content, wrap the block in four backticks so the inner three don’t close the block. If a code block inside a list doesn’t render, try indenting the fenced block by four spaces (eight if it’s inside a nested list). Some parsers require that.

Example: what you type to get a code block. In your Markdown file you type exactly this. The first line is three backticks plus the language name. The last line is three backticks alone. Everything between is shown as code. (We use four backticks here so the closing ``` appears as part of the example.)

```javascript
console.log("Hello");
```

The result is a highlighted code block with your snippet. When that Markdown is rendered, it looks like this:

console.log("Hello");

Same idea for other languages: use python, html, bash, json, etc. instead of javascript.

Blockquote and horizontal rule

Blockquote: start a line with >. Multiple lines need > on each line or a > on the first and blank lines end the quote.

> This is a quote.
> It can span lines.

Horizontal rule: a line with three or more --- or *** or ___ (nothing else on the line).

Tables

Header row, then a separator row (pipes and dashes), then data rows. Colons in the separator set alignment: :--- left, ---: right, :---: center.

| Name   | Price |
| ------ | ----: |
| Apple  |  1.00 |
| Banana |  0.50 |

Pipes don’t have to line up in the source, but aligning them makes the raw file easier to read.

Escaping

Backslash before a character that would otherwise be special: \* gives a literal asterisk, \# literal hash, \[ literal bracket. To show the syntax for a link without turning it into a link, use backticks: `[text](url)`.

Tips

Use fenced code blocks with a language id for any snippet longer than one line. It keeps formatting and enables highlighting. For READMEs and docs, keep heading levels in order (don’t jump from ## to ####). Tables are supported in GitHub, GitLab, and most modern Markdown parsers.

When to use which. Headings: # for the doc title, ## for main sections, ### for subsections. For emphasis prefer **bold** for strong and *italic* for emphasis. Use backticks for any inline code, file names, or command names so they stand out and don’t get parsed as Markdown. For long URLs that you don’t want to turn into a link, wrap in angle brackets so they become clickable but don’t need link text: <https://example.com>.

Footnotes (GitHub and some others). Add a note with [^1] in the text and define it later with [^1]: Your footnote text. Multiple footnotes use [^2], [^3], etc. Not all Markdown renderers support this.

Mixed list with code. To add a code block under a list item, indent the block by eight spaces (or four for the list plus four for the block). Some renderers accept four spaces for the block if the list is simple. Example: a numbered step that includes a command. Write the step, then on the next line indent with spaces and type your three backticks and code so the block is part of that item.