---
title: "Rich text"
description: "The HTML format every rich text field reads and writes, writing it in Markdown, and previewing a body."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rich text

Every rich text field (a product's `description` and `what_you_get`, an entry's teaser, the texts in a body's blocks, a quiz's text) takes HTML in one closed format, and reads back in it. A write is validated and stored in a canonical form; a text outside the format is refused as `422` [`invalid`](/merchant-api/errors#invalid). Each field's description in the [reference](/merchant-api/reference) says when it is rich text and which blocks it takes.

A body's `content` (a product's, an entry's, a page's or the store's home's) is a JSON layout of blocks whose texts are rich text: the [block reference](/overview/blocks) lists every block type, where it may sit and its props, with their JSON Schema. Before writing one, <a href="/merchant-api/reference/get-body-schema/">`getBodySchema`</a> answers what a save takes for its kind of body (the store's home, a page, a product's, an event's or a portfolio's page, a lesson or an article): its block types, each block's props with their types, values and limits, which are required, and where blocks may sit. A block with an unknown type, an unknown prop or a value outside its set is refused, naming the block, the prop and what it takes, never dropped. So is a block its kind of body doesn't take, at any depth, inside a container or a text too: an event's blocks (`event-date`, `event-location`) sit only on an event's page, and a portfolio's (`portfolio-chart`, `portfolio-weights`) only on a portfolio's. A block the body already held is kept as it was.

A body's path names its target by `{kind}` and `{id}` (<a href="/merchant-api/reference/read-body/">`GET /{kind}/{id}/body`</a>). For the store's home, `{kind}` is `stores` and `{id}` is the store's own id, the same one the path starts with. In a call's arguments the home is `{ "kind": "store" }`, with the store's id as `id` or none.

## Layouts

A product, entry, page or the store's home without a body of its own shows a default layout. <a href="/merchant-api/reference/read-body/">`readBody`</a> answers what the page shows: its published body, or the default with `default.template` naming it and `asset` null. A body its page can't show shows the default too, answered with `default` set and `asset` naming that body: a layout that doesn't read, or a body of another type, except a lesson's text and an article's HTML, which show as their text. So does the home's, a page's, a product's or an article's layout none of whose blocks the page shows: blocks of a type it doesn't show (a header or footer comes from the store's settings), blocks whose props don't read, or only outlets, which only a product's page fills. A layout holding no block, or hiding all it holds, is the page's own and shows nothing; a lesson shows its layout's blocks as it reads them. A staged read answers the staged body alone, `null` when nothing is staged. A body's type changes only with a body write: a type change through <a href="/merchant-api/reference/update-asset/">`updateAsset`</a> is refused `conflict` on `mime` with the reason. A read with `default` answers the default even while the page shows its own body, with `asset` naming that body, so a page can go back to it; it takes no `staged`, and a quiz or certificate has none.

- **Templates**: `home` (a hero with the line of products, a rule and the product grid), `page` (a centered hero with the page's title and description), `lesson` and `article` (empty: an entry's title, media and header come from its own fields), and a product's by category: `series`, `blog`, `podcast`, `portfolio`, or `product` for every other category. A product's default shows its poster when its settings show it as the background, and its own pictures and videos as its cover, as a reader who may open them sees it. A poster, and a picture a product attaches as its own, is at most 15 MB: attaching or swapping in a larger one is refused `invalid`.
- **Starting from a default**: send its `content` back with `setBody`, then change it. To go back to the default over a body of its own, read it with `default` and send that. A live write names `asset` as `from` (`null` without a body); a staged write names it as `live`, and as `from` the staged body `readBody` answers with `staged` (`null` when nothing is staged). Once saved, the layout is the body's own: a picture or video attached to the product later no longer joins its cover.
- **A product's texts**: a body doesn't copy the product's `description` and `what_you_get`; it shows them where it places the `product-description` and `product-what-you-get` blocks, in its layout or inline in a text, so editing those fields changes the page only while the layout holds their blocks. A hero with an empty title shows the product's title and `subtitle`. A body without columns is saved with a main column holding an empty hero and the standard side column, which holds `product-what-you-get` where its category's default does. `product_fields` says whether the page shows each text, in either theme.
- **A product's side column**: every product's page shows its columns side by side, with at least one side column (an `aside` whose `target` is `aside`, not hidden). A save of a body showing none stores it with the standard side column after its columns, holding the category's default side blocks of the types the body holds nowhere, and a body saved before shows the same way, a customer's read answering it with that column. A save refuses a body only the added column takes past the size or block limit with a reason naming the side column. Block markup counts only in a text a block holds, never in a plain field such as a hero's title. An event's date and place cards live in a side column with the buy box: a body lacking them shows them beside the first buy box a side column shows, else at the top of the first side column, never in a main column.

## Editing blocks

Every block in a body carries an `id`, which a read answers in `content` and which stays the same across writes. To change a few blocks without sending the whole body again, <a href="/merchant-api/reference/edit-body/">edit the body's blocks</a> with a list of `edits`, applied in order, which land together or not at all:

- `update` sets the props a block's `block` JSON names (with the block's own `type`), removing one set to `null`; with `replace: true`, `block` is the whole new block, of any type. The block keeps its `id`.
- `insert` adds `block` after the block `after` names, in the list that holds it (inside a column, a container or an FAQ's answer too), or at the `start` or `end` of the body's top-level blocks with `at`; on a product page, a block that is no column starts after its columns.
- `move` takes a block, with everything it holds, to a new place, named the same way.
- `delete` removes a block, with everything it holds.

A block an edit sends with no `id`, or one it holds with none, gets a new one; the answer's `blocks` lists the id each edit touched. The body is then checked exactly as a whole <a href="/merchant-api/reference/set-body/">body write</a> is: the same blocks, limits and files. `from`, `staged`, `live` and `unpublished` work as they do there: `from` names the body you read, so an edit over a body that changed since is refused as `409` [`conflict`](/merchant-api/errors#conflict) and nothing lands; read the body again and redo the edits. A first edit of a staged body starts from the live one: send `from: null` with `staged: true` and `live` naming the live body. With `text_format: "markdown"`, a block's texts are converted as a body's are, which is why an `update` names the block's `type`.

A <a href="/merchant-api/reference/publish-body/">publish</a> takes `live` too: name the live body you read when you staged, and a publish over one written since is refused as `409` [`conflict`](/merchant-api/errors#conflict) naming no `current`, and nothing lands: read the live body again, bring its changes into the staged one and publish again.

A block id the body holds more than once, or a body that isn't a layout of blocks, can't be edited block by block: set it whole once, with a new id for all but one copy. A refusal's `context.path` points into the edit that sent what it is about (`["args", "edits", 0, "block", ...]`; just `["args", "edits", 0]` for a block an edit only moved), a refused file into the edit whose block names it, or else into the body as it would be (`["args", "target", "blocks", ...]`). An `id` or `after` naming a block the body doesn't hold is `404` [`not_found`](/merchant-api/errors#not_found) with `context.kind` `block` and the id.

## Allowed

- **Text**: `p`, `h1` (title), `h2` (heading), `h3` (subheading), `br`.
- **Marks**: `strong`, `em`, `u`, `s`, `sup`, `sub` and `code`, also read as `b` as `strong`, `i` as `em`, `del` as `s` and `strike` as `s`.
- **Links**: `a` with an `href` using `http`, `https`, `mailto`, `tel`, `ftp`, `ftps`, `callto`, `sms`, `cid`, `xmpp`, `irc` and `ircs`, or a relative path, optionally `target="_blank"`. A link's `rel` is read and never stored.
- **Color**: `color` and `background-color` on a `span`, as `#rgb` or `#rrggbb`.
- **Alignment**: `text-align` (`left`, `center`, `right` and `justify`) on a paragraph or a heading.
- **Lists**: `ul`, `ol` (with `start`), `li`; `data-checked="true"` or `"false"` on an item makes a task list.
- **Tables**: `table`, `thead`, `tbody`, `tr`, `th` and `td`, with `colspan` and `rowspan`.
- **Code**: `pre` holding one `code`, its language as `class="language-<id>"`, one of `bash`, `c`, `cpp`, `csharp`, `css`, `go`, `xml`, `java`, `javascript`, `json`, `kotlin`, `markdown`, `php`, `python`, `ruby`, `rust`, `sql`, `swift`, `typescript` and `yaml`.
- **More**: `blockquote`, `hr`, `details` (with `open`) holding its `summary` first, and `figure` with at most one `figcaption`, first or last.
- **Blocks**: images, videos, audio, slideshows, formulas, diagrams, maps, downloads and other blocks are `<block type="..." props="..."></block>` elements, their props a JSON object with its quotes escaped, as the [block reference](/overview/blocks) lists them for each type. There is no raw `img`, `video` or `iframe`.

Every other tag, attribute, style or value is refused, and so are comments, a link or a block inside a link, a figure inside a figure, and a misplaced `summary` or `figcaption`.

```html
<h1>Welcome</h1>
<p style="text-align: center">Start with <strong>the intro</strong>, then <a href="https://example.com/notes" target="_blank">read the notes</a>.</p>
<ul>
  <li data-checked="true"><p>Watch the intro</p></li>
  <li data-checked="false"><p>Take the <span style="color: #047857">quiz</span></p></li>
</ul>
<block type="image" props="{&quot;id&quot;:&quot;cover&quot;,&quot;fileId&quot;:&quot;FILE_ID&quot;,&quot;alt&quot;:&quot;The cover&quot;}"></block>
```

## Limits

A text holds at most 1 MiB of UTF-8, within its field's own limit, and its markup nests at most 32 elements deep. A text's tables cover at most 10,000 cells in all, each table counting its rows times its widest row. An image a text or a layout shows is at most 15 MB: a write that starts showing a larger one is refused `invalid` (on the file for a layout, on the text's field for any other text), while one the text showed already stays. A video, or a file only linked as a download, takes no such limit.

## Reads

A read answers the stored canonical form, wrapped in `<rich-text version="1">`: attributes in a fixed order, entities and spacing normalized, loose text in a paragraph, an empty list item, cell or quote holding an empty paragraph, and tables made rectangular. Send it back unchanged to keep a text as it is.

## Markdown

A write holding rich text also takes `text_format`: `"html"`, the default, or `"markdown"`. With `"markdown"`, every rich text field of the call is converted from Markdown (CommonMark with tables, task lists, strikethrough and links written out in full) and then validated the same way:

- Each text converts from at most 64 KiB of Markdown; send a longer one as HTML.
- Quotes nested so deep, over so many lines, that reading them would take too long are refused, such as a link definition's title across lines quoted less deeply, in quotes nested about fifteen deep or more; send such a text as HTML.
- Raw HTML in it is kept as written, so a `<block>` element works, and a text already starting with `<rich-text` is kept as it is.
- Headings past the third level become subheadings, a link's title and a table column's alignment are dropped, and an image is refused, since an image is a block.
- Display math becomes a [formula block](/overview/blocks/formula): a `$$` line opening it and another closing it (words after the opening `$$` are its first line), or a paragraph that is one `$$ ... $$` line. A `$$` nothing closes, math inside a sentence and a single `$` stay text.
- A `mermaid` code fence becomes a [diagram block](/overview/blocks/diagram) unless the diagram's rules refuse it: one of a type the store's page doesn't draw, with styling of its own, too large, with values outside a chart's axes, or one that draws nothing (such as a label left open) stays a code block. One that passes those but still can't be drawn is refused, as that diagram block written out would be.
- The texts inside a block's `props` are always HTML.

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: create-watercolor-basics' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Watercolor basics",
  "category": "course",
  "subtitle": "Paint your first landscape in six short lessons.",
  "text_format": "markdown",
  "description": "## What you learn\n\n- Mixing a palette\n- Wet on wet washes\n- **Layering** without mud",
  "listing": "primary",
  "settings": {
    "refund_policy": "14d",
    "reviews_enabled": true
  },
  "full": true
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products', {
  body: {
    "title": "Watercolor basics",
    "category": "course",
    "subtitle": "Paint your first landscape in six short lessons.",
    "text_format": "markdown",
    "description": "## What you learn\n\n- Mixing a palette\n- Wet on wet washes\n- **Layering** without mud",
    "listing": "primary",
    "settings": {
      "refund_policy": "14d",
      "reviews_enabled": true
    },
    "full": true
  },
  key: 'create-watercolor-basics',
});
```

Answers `201`, abridged:

```json
{
  "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
  "slug": "watercolor-basics",
  "title": "Watercolor basics",
  "category": "course",
  "status": "draft",
  "description": "<rich-text version=\"1\"><h2>What you learn</h2><ul><li><p>Mixing a palette</p></li><li><p>Wet on wet washes</p></li><li><p><strong>Layering</strong> without mud</p></li></ul></rich-text>",
  "tiers": [
    {
      "id": "a1c3e5f7-0b2d-4f6a-8c9e-1d3f5b7a9c0e",
      "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "rank": 1,
      "name": "Base"
    }
  ],
  "prices": []
}
```

## Refusals

A refused text answers `invalid` with `context.path` naming the field (into a body's JSON for a block's text) and `context.reason` what is wrong. When the API can say where, `context.offset` is the character it stopped at, `context.name` the tag, attribute or style it names, and `context.excerpt` quotes the text around it: for Markdown, the HTML it was converted into.

## Previews

Reading a body (<a href="/merchant-api/reference/read-body/">`GET /{kind}/{id}/body`</a>), writing one (<a href="/merchant-api/reference/set-body/">`PUT /{kind}/{id}/body`</a>) or <a href="/merchant-api/reference/edit-body/">editing its blocks</a> answers `preview`, a link to see it rendered: `url` opens the body's page on the store as a visitor sees it, even while the page or product is unpublished, until `expires_at`, 1 hour later. It needs no sign-in, so a browser or a headless renderer opens it as it is, in the store's own theme.

- A page's, a product's, the home's or an entry's draft link shows the staged body where there is one, else the live one, so a read or a write of a page's, a product's, the home's or an unpublished entry's live body while a staged one waits answers `preview: null`.
- The previewed body opens past its own gates, so treat its link like the draft itself; everything else on the page shows as it does to a visitor who holds nothing, and no customer's data shows. Its files open on its link as publishing would bind them, behind the same gates: one the page already shows keeps its own gate and free preview, served as the draft uses it and downloaded on the rules the draft sets, one the draft no longer names stops opening, or keeps no rule where you bound it to the page yourself, and one whose use publishing would refuse opens as it does live, or not at all where nothing binds it.
- A page's or the home's link opens that page alone. A product's link opens the product's page and its published entries' pages too.
- An entry's staged body, or the live body of an entry not out yet while nothing waits staged, answers a link of the entry's own: it opens that entry even while it or its product is unpublished, and its product's page and published entries beside it, as they are live and behind their gates. The draft itself is not listed among the product's entries.
- A published entry's live body answers its product's link, showing it as a visitor sees it, so behind its gate it shows locked.
- `preview` is also null for a caller who may not write the previewed page's body (`file:write` and its own write scope: a product's for a published entry's live body, the entry's own and `product:read` for its draft), for a quiz's or a certificate's body, for a store with no verified address, and while the store holds its most live links.
- Every answer makes a new link, and earlier ones keep working until they expire. An expired link shows the page as it is live, with a line in the store's bar saying the preview didn't open. An unpublished page is not found then, and the bar says so, with no live page to show, only to a member opening the store from the merchant app: read the body again for a fresh one.

To check how a body renders, open its link at a desktop width (1440 pixels) and a phone width (390), each in light and dark, as the page follows the browser's `prefers-color-scheme`. With Playwright:

```js
for (const width of [1440, 390])
  for (const colorScheme of ['light', 'dark']) {
    const page = await browser.newPage({ viewport: { width, height: 900 }, colorScheme });
    await page.goto(body.preview.url);
    await page.screenshot({ path: `body-${width}-${colorScheme}.png`, fullPage: true });
    await page.close();
  }
```

Source: https://docs.sherpo.io/merchant-api/rich-text/index.mdx
