Skip to content

Rich text

The HTML format every rich text field reads and writes, writing it in Markdown, and previewing a body.

Updated

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. Each field’s description in the 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 lists every block type, where it may sit and its props, with their JSON Schema. Before writing one, getBodySchema 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} (GET /{kind}/{id}/body). 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. readBody 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 updateAsset 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, edit the body’s blocks 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 body write 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 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 publish takes live too: name the live body you read when you staged, and a publish over one written since is refused as 409 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 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 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.

<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: 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 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.
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
}'
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:

{
  "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 (GET /{kind}/{id}/body), writing one (PUT /{kind}/{id}/body) or editing its blocks 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:

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();
  }

Type to search…

↑↓ navigate↵ selectEsc close