---
title: "Markdown Cheat Sheet | Keep"
description: "Learn Markdown with interactive examples for headings, formatting, lists, links, code blocks, tables, Mermaid diagrams, READMEs, agent instructions, skills, and MDX docs."
canonical: "https://keep.md/blog/markdown-cheat-sheet"
language: "en"
---

# Markdown Cheat Sheet

Learn Markdown with interactive examples for headings, formatting, lists, links, code blocks, tables, Mermaid diagrams, READMEs, agent instructions, skills, and MDX docs.

August 9, 2026Ian Nuttall

Markdown is plain text with a small set of punctuation for structure and formatting. The source stays readable, even before a renderer turns it into HTML, a document, or an interface. That is why the same format works for GitHub READMEs, technical documentation, blog posts, notes, and instructions for AI agents.

Use this page as a quick reference, or work through the playgrounds to learn what each pattern does. The core examples follow [CommonMark](https://spec.commonmark.org/0.31.2/). Tables, task lists, and strikethrough come from [GitHub Flavored Markdown](https://github.github.com/gfm/), usually shortened to GFM.

## Markdown headings

Start a heading with one to six hash characters followed by a space. Use one H1 for the page title, H2 headings for the main sections, and H3 headings beneath them. A clear heading hierarchy makes a long document easier for people, screen readers, search engines, and agents to navigate.

| Level | Markdown syntax | Typical use |
| --- | --- | --- |
| H1 | `# Page title` | The document title |
| H2 | `## Main section` | A major topic |
| H3 | `### Subsection` | A topic within a section |
| H4 | `#### Detail` | A deeper reference section |
| H5 | `##### Small heading` | Rarely needed |
| H6 | `###### Smallest heading` | Rarely needed |

Do not remove the space after `#`. `##Setup` is ordinary text in CommonMark, while `## Setup` is a heading.

## Bold, italic, strikethrough, and inline code

Wrap text with punctuation to add emphasis. These marks can appear inside paragraphs, list items, headings, and table cells.

| Result | Markdown syntax | Support |
| --- | --- | --- |
| **Bold** | `**Bold**` | CommonMark |
| *Italic* | `*Italic*` | CommonMark |
| ***Bold and italic*** | `***Bold and italic***` | CommonMark |
| ~Strikethrough~ | `~~Strikethrough~~` | GFM |
| `Inline code` | `` `Inline code` `` | CommonMark |

Use inline code for file names, commands, settings, function names, and short values. It protects the punctuation inside the backticks from being interpreted as more Markdown.

## Lists and task lists

Start an unordered list with `-`, `*`, or `+`. Dashes are the easiest to scan. Start an ordered list with a number and a full stop. Indent a nested item so the parser knows it belongs to the item above.

```
- Capture the source
- Extract the useful text
  - Keep the title
  - Remove the navigation

1. Review the result
2. Save it
3. Share it with the agent
```

GitHub task lists add a checkbox after the list marker:

```
- [x] Record the decision
- [ ] Update the documentation
- [ ] Tell the next agent what changed
```

Task lists are a GFM extension. They work on GitHub and in many developer tools, but they are not part of the CommonMark core.

## Links, images, and blockquotes

A Markdown link puts the visible label in square brackets and the destination in parentheses:

```
[Read the Keep docs](https://keep.md/docs)
```

Images use the same pattern with an exclamation mark at the start. The text in square brackets becomes the image alternative, so describe the useful information in the image rather than its file name.

```
![A three-step flow from source to shared context](agent-flow.png)
```

Start a blockquote with `>`. Add the marker to blank quoted lines when a quote contains several paragraphs.

```
> The raw text should still make sense before it is rendered.
>
> That is the useful constraint Markdown gives you.
```

## Markdown code blocks

Use single backticks for inline code and fenced code blocks for several lines. A fence is three or more backticks above and below the code. Put a language after the opening fence to enable syntax highlighting when the renderer supports it.

````
```ts
const context = await keep.search('deployment decision')
```
````

If the code itself contains three backticks, wrap it with four backticks. The outer fence only closes when the renderer reaches another fence of the same length.

## Markdown table syntax

A table uses pipes for columns and a separator row of dashes beneath the headings. Colons in the separator row control alignment: `:---` aligns left, `:---:` centres, and `---:` aligns right.

The source for a basic table looks like this:

```
| File | Purpose | Owner |
| --- | --- | --- |
| AGENTS.md | Project instructions | Team |
```

Tables are part of GFM, not CommonMark. For long prose, lists and headings are usually easier to read in raw text. Use a table when readers need to compare the same fields across several rows.

## Mermaid diagrams in Markdown

[Mermaid](https://mermaid.js.org/intro/syntax-reference.html) turns a fenced text definition into a flowchart, sequence diagram, state diagram, timeline, or several other diagram types. GitHub, many documentation systems, and a growing number of Markdown tools render Mermaid directly.

Wrap Mermaid source in a fenced code block with `mermaid` as the language:

````
```mermaid
flowchart LR
  A["Fetch page"] --> B["Extract Markdown"]
  B --> C["Save context"]
```
````

Mermaid is useful in agent-facing documents because the diagram remains editable text. An agent can rename a step or insert a branch without editing an image. Support still depends on the renderer, so keep the surrounding explanation complete enough to stand on its own.

## Markdown for READMEs, agent instructions, skills, and docs

Markdown now carries more than formatted prose. A repository can use an [AGENTS.md file](https://agents.md/) for setup commands, tests, and conventions that coding agents need. An [Agent Skill](https://agentskills.io/specification) uses a `SKILL.md` file with YAML frontmatter followed by instructions. Documentation systems use frontmatter for page metadata, while MDX can place interactive components inside Markdown content.

The practical distinction is simple:

-   `README.md` explains the project to a person arriving for the first time.
-   `AGENTS.md` gives coding agents commands and repository-specific rules.
-   `SKILL.md` packages instructions for a repeatable task and includes metadata that tells agents when to use it.
-   `.mdx` combines Markdown with components. [MDX](https://mdxjs.com/docs/what-is-mdx/) is common in blogs and documentation systems.
-   A docs page often begins with YAML frontmatter. [Mintlify pages](https://www.mintlify.com/docs/organize/pages), for example, can use `.md` or `.mdx`, with fields such as `title`, `description`, and `icon` controlling page metadata.

Frontmatter sits between two lines containing three dashes at the very top of the file:

```
---
title: Connect your agent
description: Give an agent access to shared project context.
---
```

Frontmatter is not part of CommonMark. The application reading the file decides which fields it supports.

## CommonMark, GFM, and tool-specific Markdown

There is no single renderer that supports every feature called Markdown. Treat the syntax in three layers:

| Layer | Examples | Where it works |
| --- | --- | --- |
| CommonMark | Headings, emphasis, lists, links, images, quotes, code | The broadest baseline |
| GitHub Flavored Markdown | Tables, task lists, strikethrough, autolinks | GitHub and many developer tools |
| Tool-specific extensions | Mermaid, footnotes, math, callouts, JSX components | Only where the chosen renderer supports them |

When portability matters, write the important meaning with CommonMark and treat extensions as an enhancement. A Mermaid diagram should have an explanatory paragraph. A custom callout should not be the only place a warning appears.

## Markdown quick reference

Use this searchable Markdown cheat sheet when you know the result you want but cannot remember the punctuation. Copying a row gives you valid starter syntax without opening a separate editor.

| Element | Markdown syntax | Use |
| --- | --- | --- |
| Heading 1 | `# Heading 1` | One page title |
| Heading 2 | `## Heading 2` | Main sections |
| Heading 3 | `### Heading 3` | Subsections |
| Bold | `**bold text**` | Strong emphasis |
| Italic | `*italic text*` | Light emphasis |
| Strikethrough | `~~removed text~~` | GitHub Flavored Markdown |
| Inline code | `` `const value = 1` `` | Commands, files, and identifiers |
| Link | `[label](https://example.com)` | Named links |
| Image | `![alt text](image.png)` | Images with accessible text |
| Blockquote | `> Quoted text` | Quotes and callouts |
| Bullet list | `- List item` | Unordered items |
| Numbered list | `1. List item` | Ordered steps |
| Task list | `- [x] Complete - [ ] Open` | GitHub tasks |
| Fenced code | ` ```ts const ready = true ``` ` | Multiline code with a language |
| Horizontal rule | `---` | A thematic break |
| Table | `| Name | Value | | --- | --- | | Keep | Markdown |` | GitHub tables |
| Footnote | `A claim.[^1] [^1]: The source.` | Supported by some renderers |
| Escape | `\*literal asterisks\*` | Show punctuation literally |

## Common Markdown mistakes

### Missing spaces after markers

Write `# Heading` rather than `#Heading`, and `- Item` rather than `-Item`. The space separates the marker from the content.

### Breaking a list with inconsistent indentation

Indent nested items consistently. If a paragraph or code block belongs to a list item, it needs enough indentation to stay inside that item.

### Forgetting blank lines around blocks

Blank lines make the raw file clearer and avoid parser differences around lists, blockquotes, and code blocks. Put a blank line before and after a fenced block.

### Assuming every extension works everywhere

Tables, task lists, Mermaid, footnotes, math, callouts, and MDX components depend on the renderer. Check the target platform before using an extension as the only way to communicate something important.

### Using vague link or image text

`[Click here](...)` hides the destination from a scanning reader. Name the resource instead. Image alt text should explain what the image contributes, not say “image” or repeat the file name.

## Markdown cheat sheet FAQ

### What is the difference between Markdown and GitHub Flavored Markdown?

CommonMark defines a widely supported Markdown baseline. GitHub Flavored Markdown builds on that baseline with tables, task lists, strikethrough, and automatic links. Many developer tools support GFM, but not every Markdown renderer does.

### How do I preview a Markdown file?

GitHub renders `.md` files automatically. Code editors such as VS Code include a Markdown preview, and documentation systems render files as pages. The exact output depends on the renderer and its enabled extensions.

### Can Markdown include HTML?

CommonMark allows raw HTML blocks and inline HTML, but many applications sanitize or disable them for security. Prefer Markdown syntax when it can express the same structure.

### Is Mermaid part of Markdown?

No. Mermaid is a separate diagram syntax commonly embedded in a fenced Markdown code block. It only becomes a visual diagram when the destination supports Mermaid rendering.

### Which Markdown file should an AI coding agent read?

Use `AGENTS.md` for repository setup, tests, code conventions, and handoff requirements. Use a `SKILL.md` file for a reusable capability that an agent should activate for a matching task. Keep the project README focused on helping humans understand and use the project.

If you are preparing existing material for an agent, the [PDF to Markdown converter](https://keep.md/tools/pdf-to-markdown) and [URL to Markdown converter](https://keep.md/tools/url-to-markdown) turn common sources into clean text. The [token counter](https://keep.md/tools/token-counter) shows how much context that text will use, and the [Markdown for Agents checker](https://keep.md/tools/markdown-for-agents) tests whether a website serves Markdown directly.

## Stop re-explaining your project to every AI agent.

Automatically Keep decisions, handoffs, plans, context, and todos in one shared AI notepad that every local or cloud agent remembers.

[Start for free](https://app.keep.md/signup)

[Read the docs](https://keep.md/docs)