Markdown Cheat Sheet

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. Tables, task lists, and strikethrough come from GitHub Flavored Markdown, usually shortened to GFM.

# Project notes
## Decisions
### Open questions

Ship the **parser** before the *editor*.

`AGENTS.md` is ~~optional~~ required.

- Capture the source
- Extract Markdown
  - Keep headings
  - Remove navigation

1. Review
2. Publish

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

![A useful alt description](diagram.png)

> Good context records the decision, not just the final code.
>
> It should still make sense next week.

Use `keep search` inline.

```ts
const context = await keep.search(query)
```

const context = await keep.search(query)

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.

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.

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 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 for setup commands, tests, and conventions that coding agents need. An Agent Skill 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.

# Context API

Search project decisions from any agent.

## Install

```sh
pnpm add @example/context
```

## Usage

1. Connect your project.
2. Search before making a decision.
3. Save the handoff when the task ends.

# Agent instructions

## Setup commands

- Install: `pnpm install`
- Test: `pnpm test`

## Code style

- Use TypeScript strict mode.
- Reuse components from `src/components/ui`.

## Before handoff

Run lint, typecheck, and tests.

---
name: release-check
description: Check a release before publishing. Use for version bumps and changelogs.
---

# Release check

1. Read the current version.
2. Run the test suite.
3. Verify the changelog entry.

## Edge cases

- Stop if the working tree contains unrelated changes.

---
title: "Connect your agent"
description: "Give an agent access to shared project context."
icon: "plug"
---

# Connect your agent

<Steps>
  <Step title="Create an API key">
    Choose the read-only scope.
  </Step>
  <Step title="Add the MCP server">
    Paste the generated config.
  </Step>
</Steps>

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 is common in blogs and documentation systems.
• A docs page often begins with YAML frontmatter. Mintlify 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:

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.

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 and URL to Markdown converter turn common sources into clean text. The token counter shows how much context that text will use, and the Markdown for Agents checker tests whether a website serves Markdown directly.