---
title: "Bodies and rich text"
description: "The layouts a product, a lesson or a page shows, and the rich text format their texts use."
---

> 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.

# Bodies and rich text

What a product, an entry (a lesson or an article), a custom page or the store's home shows is its **body**: a layout of blocks, some of which hold **rich text**. You read a body with [`GET /v1/stores/{store}/body`](/customer-api/reference/read-body), or with `include=body` on the product, entry or page read. Without a body of its own, a page still shows a [default layout](#default-layouts), which the read answers in its place.

## Bodies

```bash
curl --globoff 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/body?target[kind]=entry&target[id]=<entry id>' \
  --header 'Authorization: Bearer ctk_...'
```

`target` names whose body: `{ "kind": "store" }` for the store's home, or a `product`, `entry` or `page` with its `id`.

```json title="readBody 200"
{
  "id": "<body id>",
  "role": "body",
  "access": "unlocked",
  "requires": { "kind": "tier", "rank": 1, "product_id": "<product id>" },
  "words": 412,
  "content": "{\"blocks\":[{\"id\":\"intro\",\"type\":\"markdown\",\"content\":\"<rich-text version=\\\"1\\\"><h2>Welcome</h2><p>Start here.</p></rich-text>\"},{\"id\":\"lesson-video\",\"type\":\"video\",\"fileId\":\"<file id>\"}]}",
  "files": {
    "<file id>": {
      "id": "<file id>",
      "kind": "video",
      "mime": "video/mp4",
      "name": "lesson-1.mp4",
      "bytes": 48213900,
      "width": 1920,
      "height": 1080,
      "duration": 754,
      "pages": null,
      "status": "ready",
      "url": null,
      "attachment_id": "<attachment id>",
      "unlocks": null
    }
  }
}
```

- `default` is `null` for the page's own body.
- `content` is a JSON string. Parse it: it's an object whose `blocks` is the layout, each block an object with its `id`, its `type` and its props. Containers hold more blocks.
- `access` is `unlocked`, or `locked` when the customer may not read it yet. A locked body answers its `requires` and `words`, but no `content`: show what unlocks it instead ([A customer's library](/customer-api/library#access)).
- `files` lists every file the layout names, by the `fileId` a block holds. A public file has its lasting `url`, and a public image its smaller copies as `resized`, for a [responsive image](/customer-api/files#responsive-images); a private one has `url: null` and an `attachment_id` you [open](/customer-api/files) when you show it. A file kept back by its own rules lists what `unlocks` it.
- A body still being prepared answers `409` [`conflict`](/customer-api/errors#conflict) on `status` (`pending`): ask again shortly.

### Default layouts

A page with no body of its own, or with one it can't show, shows a default layout instead, and the body read answers that default. A body it can't show is a layout that doesn't read, or a body of another type; a lesson's text and an article's HTML show as their text.

```json title="readBody 200"
{
  "default": { "template": "page" },
  "attachment": null,
  "mime": "application/vnd.sherpo.blocks+json",
  "access": "unlocked",
  "requires": { "kind": "everyone" },
  "content": "{\"blocks\":[{\"id\":\"default-hero\",\"type\":\"hero\",\"title\":\"About us\",\"alignment\":\"center\",\"highlights\":[],\"additionalContent\":[],\"lineProducts\":{\"id\":\"default-line\",\"type\":\"line-products\",\"hidden\":true},\"hidden\":false}]}",
  "words": null,
  "files": {}
}
```

- `default.template` names the default:
  - `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, since an entry's title, media and header come from its own fields;
  - a product's, by category: `series`, `blog`, `podcast`, `portfolio`, or `product` for every other category.
- `attachment` names the body the page shows the default for, or is `null` without one.
- The store's home and a product's page also show their default to a customer their own body is kept from.
- A product's default shows its poster when its settings show it as the background. Its cover is the product's own pictures and videos the customer may open, all listed in `files`.
- A default has no gate of its own. It is `locked`, with `content: null`, only when the page itself is kept from the customer, and its `words` are `null`.
- A front-end that can show none of a page's own blocks asks for its default instead with `fallback=true`: the body read then answers the default whatever the page's body, `attachment` naming that body.

### Blocks

Every block type a body holds, its props and their JSON Schema are in the [block reference](/overview/blocks), with where each one sits: a lesson's body takes fewer types than an article's, a page's or the store's home (though one may still hold a page's block it held before), and a product's page has its own. A block with `hidden: true` isn't shown, and a `markdown` block holds a rich text in its `content`.

A `formula` block holds a display formula's TeX in `tex`: render it with a TeX renderer such as KaTeX, or show its source.

A `diagram` block holds a diagram's Mermaid source in `source`, a type the store's page draws (a flowchart, sequence, state, class, ER or XY chart diagram): render it with a Mermaid renderer, or show its source.

An `audio` block plays the file its `fileId` names, in an `<audio>` or a player of your own. Where the customer may play it, its file in `files` carries `audio.waveform`: the recording's loudness from start to end as 256 levels from 0 to 255, in base64, to draw as bars the customer seeks on. It's `null` until the wave is drawn after upload, so show a plain bar until then. A private recording streams through its `attachment_id` as a video does ([Files and media](/customer-api/files#a-video-or-audio-file-with-a-token)): ask for its URL on the first play rather than when the page shows, as each URL asked for counts as a play, then with `renew: true` as it nears `expires_at`, which keeps it one play. Its `audio` also lists the chapters, summary and transcript the merchant published as `outputs`, read through `audio.attachment_id` ([A video's or audio file's chapters, summary and transcript](/customer-api/files#a-videos-or-audio-files-chapters-summary-and-transcript)), and their subtitles as `tracks`.

A `slideshow` block shows the PDF its `fileId` names a page at a time, as a lesson's slides are shown, with no download. Its file in `files` carries an `attachment_id` even when it is public, and `pages`: ask for its URL with `intent: "view"` when it shows, then read it whole, as a PDF viewer does ([Files and media](/customer-api/files)). A public PDF's `url` is readable from any origin too.

A `map` block shows a place: `latitude` and `longitude`, an optional `venue` and `address`, and `openInMaps`, which shows a link to the seller's `mapUrl`, or to OpenStreetMap at the point when it has none. The store draws the map itself, so it is listed in the read's `maps` beside `files`, one entry per point the body names, matched by `latitude` and `longitude` (both rounded to 6 decimals, as the block stores them): a `light` and a `dark` picture of the place, each a public `url` with its `width`, `height` and smaller copies as `resized` ([responsive images](/customer-api/files#responsive-images)), and the `attribution` to show over it, linking to `attribution_url`. Show the picture for the page's theme, the place's pin at its centre. A point is missing from `maps` until its map is drawn, shortly after the body is saved: show the venue and address alone until then.

Render a block type you don't know as nothing: new types may be added.

## Rich text

Every rich text field (a product's description, an entry's teaser, the texts a body's blocks hold, a quiz's text) comes back as HTML in one closed format, as stored when it was written, so you can render it as it is or map each element to a component of your own. It's wrapped in `<rich-text version="1">`.

```html
<rich-text version="1"><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><details><summary>Why it works</summary><p>Short lessons stick.</p></details></rich-text>
```

### What it holds

- **Text**: `p`, `h1` (Title), `h2` (Heading), `h3` (Subheading), `br`.
- **Marks**: `strong`, `em`, `u`, `s`, `sup`, `sub`, `code` (a text written with `b`, `i`, `del` or `strike` is stored as `strong`, `em` and `s`); links (`a`) to `http`, `https`, `mailto`, `tel`, `ftp`, `ftps`, `callto`, `sms`, `cid`, `xmpp`, `irc`, `ircs` or a relative path, optionally with `target="_blank"`. A link's `rel` (`noopener`, `noreferrer`, `nofollow`) is read when written but never stored, so add your own.
- **Style**: `color` and `background-color` on a `span`, as `#rgb` or `#rrggbb`; `text-align` (`left`, `center`, `right`, `justify`) on a paragraph or heading.
- **Structure**: `ul`, `ol` (`start`), `li` (`data-checked="true"` or `"false"` for a task list), tables (`table`, `thead`, `tbody`, `tr`, `th`, `td`, with `colspan` and `rowspan`), code blocks (`pre` holding one `code`, `class="language-<id>"` with an id among `bash`, `c`, `cpp`, `csharp`, `css`, `go`, `xml`, `java`, `javascript`, `json`, `kotlin`, `markdown`, `php`, `python`, `ruby`, `rust`, `sql`, `swift`, `typescript`, `yaml`), `blockquote`, `hr`, `details` (`open`) with its `summary` first.
- **Figures**: a `figure` holds any of the above, with at most one `figcaption`, first or last.
- **Blocks**: images, videos, audio, slideshows, formulas, diagrams, maps, downloads and the other blocks sit in a text as `<block type="…" props="…"></block>` elements, their props a JSON object with its quotes escaped, the same props a body's block has ([block reference](/overview/blocks)). There is no raw `img`, `video` or `iframe`.

```html
<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>
```

A `<block>`'s `fileId` is listed in the same read's `files`, as a body's are.

### The stored form

Texts come back in a canonical form: attributes in a fixed order, entities and spacing normalized, loose inline content in a paragraph, an empty list item, cell, quote, details or figure holding an empty paragraph, an empty list holding one empty item, tables made rectangular, and each block's props as its type reads them (defaults filled in). A text holds at most 1 MiB, nests at most 32 elements deep, and its tables cover at most 10000 cells in all.

> **Render it safely**
>
> The format allows no script, frame or event attribute, but treat it as you would any HTML you didn't write: render it through your framework's own elements, or a sanitizer allowing just the tags and attributes above.

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