# markdown

Formatted text with headings, lists, links, bold and code, written inline or read from a row, such as a ticket's body.

Write `text` (Markdown, up to 64 KB), or `source` and `column`: the first row of that source, that column's
Markdown. Exactly one of the two. Fenced code is drawn escaped and unhighlighted. Inline HTML is shown as text,
never run. When the source has no rows the block shows its empty state.

Category: content. Tier 1. Contract version 1.

## When to use

- A record's own long text, such as the body of the ticket the address names.
- A short runbook or policy with a list and a link.
- Text that needs bold, a list or code, which `text` would show as written.

## When to use another block

- One plain sentence. Use [`text`](/catalog/text.md).
- A warning or a confirmation a person must notice. Use [`callout`](/catalog/callout.md).
- Rows with the same columns, such as tickets. Use [`grid`](/catalog/grid.md).

## Props

- `id` (name: a-z, 0-9 and -): The block's id: its Markdown anchor and its actions' route (`/act/<id>/<action>`). Default `<type>-<n>`, n counting blocks of this type depth-first from 1.
- `text` (text ≤ 65536): The Markdown; or `source` and `column`.
- `source` (a source of the screen): The source whose first row holds the Markdown; with `column`.
- `column` (column): The column of that row holding the Markdown.

## Data

Reads the first row of `source`, when the Markdown is not written inline.

Shape: one row with a text `column` of Markdown.

## Actions

None: this block only shows.

## States

- **ready**: the source's rows, drawn
- **empty**: the source has no rows: an Empty part saying why and what comes next
- **error**: the source failed: "We couldn't load …" naming the block's rows, the source's sentence and Try again; the page still answers 200

## Examples

### The ticket's body, from its row

```yaml
markdown: { source: ticket, column: body }
```

As an agent reads it:

```markdown
<a id="markdown-1"></a>

## VPN drops every 20 minutes

Reported from the portal by **M. Okafor**. The Network agent matched a known pattern (idle timeout on the
split-tunnel profile), pushed the corrected profile and replied.

```

### A short runbook

```yaml
markdown:
  text: |
    ### Before you hand a ticket back
    - Read what the agent already tried in the timeline.
    - Reply to the requester **before** you change the status.
    - Close it as `Closed by agent` only if the agent's fix holds.
```

As an agent reads it:

```markdown
<a id="markdown-1"></a>

### Before you hand a ticket back
- Read what the agent already tried in the timeline.
- Reply to the requester **before** you change the status.
- Close it as `Closed by agent` only if the agent's fix holds.

```

### A policy with a link

```yaml
markdown:
  id: data-policy
  text: |
    Ticket data stays in the **EU region**. Agents may not send it to outside email.
    The full policy is in the [compliance screen](/a/service-desk/compliance).
```

As an agent reads it:

```markdown
<a id="data-policy"></a>

Ticket data stays in the **EU region**. Agents may not send it to outside email.
The full policy is in the [compliance screen](/a/service-desk/compliance).

```

## Invalid

```yaml
markdown: { text: '**Hold**', source: ticket, column: body }
```

Answers: `markdown: write text, or source and column, one of the two`

## Composition

- Sits in: screen, card, columns
- Pairs with: timeline, approval, callout
- A screen of reading belongs on its own screen; keep inline Markdown to a few short paragraphs.
- Apple HIG: Use typographic hierarchy for long text; keep paragraphs short and links descriptive.

## Telemetry

markdown.view, markdown.link

JSON Schema: [/catalog/markdown.schema.json](/catalog/markdown.schema.json)