---
updatedAt: 2026-09-18T20:51:54.000Z
agentTools:
  siteIndex: https://docs.readme.com/llms.txt
  siteSearch: https://docs.readme.com/agentSearch?query=term1%20term2
  projectIndex: https://docs.readme.com/main/llms.txt
  projectSearch: https://docs.readme.com/main/agentSearch?query=term1%20term2
---

# Editor Blocks

Every block you can add to a page in the ReadMe editor, with the three ways to insert each one and the Markdown it produces in Raw Mode

Every block available in the ReadMe editor is listed here with the exact label you'll see on screen, what it does, and the Markdown shortcut that inserts it while typing. Blocks that carry their own options (Callout, Image, Code, and the four layout components) link to the page that documents those options.

## Three Ways to Insert a Block

| Method            | How                                                                                                                              | When to use it                                                                                                           |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Insert panel      | Click the Blocks icon (the four small squares where the top-right one is slightly separated) located in the upper-right toolbar. | Placing a block precisely between existing content                                                                       |
| `/menu`           | Type `/`on an empty line, then type to filter.  Press Return to insert.                                                          | Keeping your hands on the keyboard.  This is the only menu that lists every block, including headings, lists, and embeds |
| Markdown shortcut | Type the Markdown syntax at the start of a line.  The editor converts it as you type.                                            | Fastest for headings, lists, callouts, dividers, and code.                                                               |

The Insert panel and the `/` menu contain different sets. The Insert panel holds the thirteen blocks below plus your project's Reusable Content and Custom Components. The `/` menu adds headings, lists, links, blockquotes, and four more embed types. Reusable Content and Custom Components are project-specific, so they are not documented on this page; see [Reusable Content](https://docs.readme.com/main/docs/reusable-content) and [Custom Components.](https://docs.readme.com/main/docs/building-custom-mdx-components)

## Blocks

Labels are exactly as they appear in the `/` menu.  Where the Insert panel uses a different label, it is noted.&#x20;

### Text and Structure

<Table>
  <thead>
    <tr>
      <th>
        Block
      </th>

      <th>
        What it does
      </th>

      <th>
        Markdown shortcut
      </th>

      <th>
        Raw Mode
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Heading 1
      </td>

      <td>
        Top-level section heading
      </td>

      <td>
        `#`
      </td>

      <td>
        `# Heading`
      </td>
    </tr>

    <tr>
      <td>
        Heading 2
      </td>

      <td>
        Section heading.  Appears in the page's table of contents
      </td>

      <td>
        `##`
      </td>

      <td>
        `## Heading`
      </td>
    </tr>

    <tr>
      <td>
        Heading 3
      </td>

      <td>
        Subsection heading.  Appears in the page's table of contents.
      </td>

      <td>
        `###`
      </td>

      <td>
        `### Heading`
      </td>
    </tr>

    <tr>
      <td>
        Bulleted List
      </td>

      <td>
        Unordered list
      </td>

      <td>
        `-`
      </td>

      <td>
        `- item`
      </td>
    </tr>

    <tr>
      <td>
        Numbered List
      </td>

      <td>
        Ordered List
      </td>

      <td>
        `1.`
      </td>

      <td>
        `1. item`
      </td>
    </tr>

    <tr>
      <td>
        Checklist
      </td>

      <td>
        Task list with checkboxes
      </td>

      <td>
        `- [ ]`
      </td>

      <td>
        `- [ ] item`
      </td>
    </tr>

    <tr>
      <td>
        Blockquote
      </td>

      <td>
        Indented quotation
      </td>

      <td>
        `>`
      </td>

      <td>
        `> text`
      </td>
    </tr>

    <tr>
      <td>
        Divider
      </td>

      <td>
        Horizontal rule between sections
      </td>

      <td>
        `- - -`
      </td>

      <td>
        `- - -`
      </td>
    </tr>

    <tr>
      <td>
        Link
      </td>

      <td>
        Inserts a hyperlink. Also available as Add Link on the selection toolbar.
      </td>

      <td>
        None
      </td>

      <td>
        `[text](url)`
      </td>
    </tr>

    <tr>
      <td>
        Callout
      </td>

      <td>
        Highlighted box for information or warnings. Icon and color are configurable.
      </td>

      <td>
        `> 📘`
      </td>

      <td>
        ```
        <Callout icon="📘" theme="info">
          ### hello world
        </Callout>
        ```
      </td>
    </tr>

    <tr>
      <td>
        Code
      </td>

      <td>
        Code block with a language selector.
      </td>

      <td>
        \`\`\`
      </td>

      <td>
        \`\`\`text
        \`\`\`
      </td>
    </tr>

    <tr>
      <td>
        Table
      </td>

      <td>
        Grid of rows and columns.
      </td>

      <td>
        None
      </td>

      <td>
        ```
        | Item | Category | Price |
        | :--- | :---: | ---: |
        | Apples | Fruit | $2.50 |
        | Broccoli | Vegetable | $1.99 |
        | Almond Milk | Dairy Alternative | $3.49 |
        ```
      </td>
    </tr>

    <tr>
      <td>
        Image
      </td>

      <td>
        Uploaded or linked image with alt text, caption, and frame options.
      </td>

      <td>
        `! [ ] (url)`
      </td>

      <td>
        `! [alt] (url)`
      </td>
    </tr>

    <tr>
      <td>
        Custom HTML
      </td>

      <td>
        Raw HTML rendered in place. `< script >` tags are stripped.
      </td>

      <td>
        None
      </td>

      <td>
        ```
        <HTMLBlock>
          {`hello world`}
        </HTMLBlock>
        ```
      </td>
    </tr>

    <tr>
      <td>
        Recipe
      </td>

      <td>
        Embeds a Recipe from your project's Recipes section.
      </td>

      <td>
        None
      </td>

      <td>
        ```
        <Recipe slug="recipe-title-1" title="Recipe Title 1" />
        ```
      </td>
    </tr>

    <tr>
      <td>
        Mermaid Diagram
      </td>

      <td>
        Text-defined flowchart, sequence diagram, or other Mermaid chart. Labeled Mermaid Diag… in the Insert panel when truncated. See [Creating Mermaid Diagrams](https://docs.readme.com/main/docs/creating-mermaid-diagrams)
      </td>

      <td>
        None
      </td>

      <td>
        ```
        mermaid flowchart LR 
        A --- B[fa:fa-spinner B] 
        B --> C[fa:fa-check C] 
        B --> D[fa:fa-ban D]
        ```
      </td>
    </tr>
  </tbody>
</Table>

## Components

These four are MDX components. Their props are documented on [Built-in Components.](https://docs.readme.com/main/docs/built-in-components)

| Block     | What it does                                               |
| --------- | ---------------------------------------------------------- |
| Accordion | Collapsible section with a title                           |
| Cards     | Grid of linked cards with an icon, title, and description. |
| Columns   | Side-by-side column layout                                 |
| Tabs      | Tabbed Content panels                                      |

## Embeds

| Block       | What it embeds                  | In the Insert Panel |
| ----------- | ------------------------------- | ------------------- |
| YouTube     | A YouTube video by URL          | Yes                 |
| GitHub Gist | A public Gist by URL            | No                  |
| PDF         | A PDF viewer by URL             | No                  |
| JSFiddle    | A JSFiddle by URL               | No                  |
| iFrame      | Any embeddable URL in an iframe | No                  |

## AI and Reuse

| Item             | What it does                                                                         |
| ---------------- | ------------------------------------------------------------------------------------ |
| Generate with AI | First item in the `/`menu. Press Tab to draft content in place with Agent Owlbert    |
| Reuse Content    | Inserts an existing Reusable Context block.  Shortcut: `<`                           |
| New Content      | Creates a new Reusable Content block from the current position                       |
| Glossary term    | Type << to search and insert a term from your Glossary.  Not listed in the `/` menu. |

## Selection Toolbar

Select any text to open the toolbar. From left to right:

| Control                                                | Action                                                         | Shortcut |
| ------------------------------------------------------ | -------------------------------------------------------------- | -------- |
| Turn into (shows the current block type, such as Text) | Converts the block to another type, such as a heading or list. | None     |
| Bold                                                   | Bold                                                           | `⌘B`     |
| Italic                                                 | Italic                                                         | `⌘I`     |
| Strikethrough                                          | Strikethrough                                                  | None     |
| Blockquote                                             | Converts the block to a blockquote.                            | None     |
| List                                                   | Converts the block to a bulleted, numbered, or check list.     | None     |
| Add link                                               | Wraps the selection in a link.                                 | None     |
| Inline code                                            | Formats the selection as inline code.                          | None     |
| Edit with AI                                           | Opens the AI editor on the selection.                          | None     |

## Block Handle Menu

Hover any block and click the ≡ handle at its left edge. The handle also drags the block to a new position.

| Item           | Action                              |
| -------------- | ----------------------------------- |
| Copy           | Copies the block                    |
| Duplicate      | Inserts an identical block below    |
| Turn into      | Converts the block to another type  |
| Make Reusable  | Saves the block as Reusable Content |
| Add Line Above | Inserts an empty paragraph above    |
| Add Line Below | Inserts an empty paragraph below    |
| Delete         | Removes the block                   |

## What the Editor Does Not Do

The editor does not merge Raw Mode edits with rich-text edits. Turning on Raw Mode from the page's ⋮ menu locks the page for other editors until you turn it off. The Editor indicator in the bottom bar (for example, Editor: MDX-ish) shows which syntax the page is using.&#x20;

# Sibling pages

* [Page Settings](https://docs.readme.com/main/docs/page-settings.md)
* [Creating Mermaid Diagrams](https://docs.readme.com/main/docs/creating-mermaid-diagrams.md)