# `RichText`

A structured document: a list of paragraphs, headings, quotes and list items.

Use it to hold content from a block editor. `markup.rich_to_html` gives [`Html`](/docs/types/type-html.md). For text someone types by hand, use [`Markdown`](/docs/types/type-markdown.md).

## Shape

A list of [`RichTextBlock`](/docs/types/type-rich-text-block.md).

## Example

```jadpo
var example: RichText = [
    RichTextBlock.paragraph {
        spans: [
            RichTextSpan { text: "Fresh soup" marks: [] link: none }
        ]
    }
]
assert example == example
```

## Good to know

- It is flat: nothing nests inside anything else.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it.

## In JSON

An array of its items, in a request, a response or `json.write`:

```json
[{"tag":"heading","level":2,"spans":[{"text":"Soups","marks":[]}]},{"tag":"paragraph","spans":[{"text":"Made ","marks":[]},{"text":"daily","marks":["strong"]}]}]
[{"tag":"bullet_item","level":1,"spans":[{"text":"Leek","marks":[]}]},{"tag":"bullet_item","level":1,"spans":[{"text":"Tomato","marks":[]}]}]
[]
```

## Details

<details>
<summary>Text form, storage, how it is shown, and operations</summary>

`RichText` is in the group Text formats, and has been in Jadpo since 0.1.0.

### Text form

It has no single text form, so `text.from` and `text.parse` don't take it.

### How it is stored

It is stored in one column named for the field, of type `jsonb`. `[{"tag":"bullet_item","level":1,"spans":[{"text":"Leek","marks":[]}]},{"tag":"bullet_item","level":1,"spans":[{"text":"Tomato","marks":[]}]}]` is stored as `'[{"tag":"bullet_item","level":1,"spans":[{"text":"Leek","marks":[]}]},{"tag":"bullet_item","level":1,"spans":[{"text":"Tomato","marks":[]}]}]'::jsonb`.

### How it is shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `[{"tag":"heading","level":2,"spans":[{"text":"Soups","marks":[]}]},{"tag":"paragraph","spans":[{"text":"Made ","marks":[]},{"text":"daily","marks":["strong"]}]}]` | `"Soups\nMade daily"` |
| `[{"tag":"bullet_item","level":1,"spans":[{"text":"Leek","marks":[]}]},{"tag":"bullet_item","level":1,"spans":[{"text":"Tomato","marks":[]}]}]` | `"Leek\nTomato"` |
| `[]` | `""` |

### Operations

- `markup.rich_to_html(rich: RichText) -> Html`: `rich` written as HTML, each block its element and each mark its element inside its link, then made safe as every `Html` is, which changes nothing: a `RichText` holds only what the sanitiser keeps.

It also takes `text.format`, `json.read`, `json.write` and `==`. [How every standard type behaves](/docs/every-standard-type-meets-one-contract.md) says how they work.

</details>