# Writing in Markdown

> The Markdown PlaybookOps documents understand, for every kind of content: headings, checklists, tables, callouts, toggles, images, video, mentions and links.

PlaybookOps stores every document as Markdown. What you send to [create or change a document](https://developers.playbookops.ai/guides/documents) is exactly what the editor opens, so anything on this page round-trips: people can edit your document in the app, and you can read it back and patch it again.

It's [GitHub-flavored Markdown](https://github.github.com/gfm/) with a few additions for callouts, toggles, alignment, media and mentions. Where it differs from GitHub, this page says so.

> **Start from the app**
> The quickest way to see the Markdown for something is to make it in the editor and read the document back with `GET /v1/documents/{id}`. The `content` you get is the source.

## Structure

The document's title is its own field, so the body doesn't need to repeat it. Start with a short introduction, then use `##` headings for the main parts.

```markdown
A one-paragraph summary of what this is for and who uses it.

## Before you start

## Steps

### Taking the call

### Logging it

## If something goes wrong
```

- Headings go from `#` to `######`. The toolbar offers four levels, so stick to `##`, `###` and `####` for documents people will edit.
- `##` headings are the sections that [patches](https://developers.playbookops.ai/guides/documents#edits) and the in-app assistant work with. A section includes the smaller headings under it.
- Keep heading names unique where you can. Patches can still reach a repeated name by its path, like `Day two > Steps`.

## Paragraphs and line breaks

A blank line starts a new paragraph. A single line break is kept as a line break, unlike on GitHub, so you can write an address or a short poem line by line.

```markdown
Send returns to:
Acme Warehouse
12 Dock Road

This starts a new paragraph.
```

The editor saves a line break as two spaces at the end of the line. Both forms mean the same thing.

## Text styles

| Style | Markdown |
| --- | --- |
| Bold | `**bold**` |
| Italic | `*italic*` |
| Strikethrough | `~~struck~~` |
| Inline code | `` `code` `` |
| Underline | `<u>underlined</u>` |
| Highlight | `<mark>highlighted</mark>` |
| Colored highlight | `<mark data-color="green">…</mark>`, also `blue`, `pink` or `purple` |

There's no font color. Emoji work as they are (✅ 🚚), but `:shortcodes:` stay as text.

## Lists and checklists

```markdown
- Bullets start with a dash
  - Indent two spaces to nest
- Another point

1. Numbered steps
2. Count themselves
   - Indent three spaces under a number

- [ ] An open checklist item
- [x] A done one
  - [ ] Checklists nest too
```

When someone ticks an item in the editor, it's saved as `[x]`.

## Quotes

```markdown
> Every refund over $500 needs a manager's approval.
> A second line stays in the same quote.
```

## Code

Fence code with three backticks and name the language for coloring.

~~~markdown
```bash
curl https://example.com/health
```
~~~

The editor offers `bash`, `shell`, `powershell`, `python`, `javascript`, `typescript`, `jsx`, `tsx`, `json`, `yaml`, `sql`, `html`, `xml`, `css`, `scss`, `markdown`, `dockerfile`, `java`, `go`, `rust`, `c`, `cpp`, `php`, `ruby`, `swift` and `kotlin`. Use fences rather than indenting code by four spaces.

## Tables

```markdown
| Plan | Refund window | Who approves |
| --- | --- | --- |
| Monthly | 30 days | Support |
| Annual | 60 days | **Finance** |
```

Tables need a header row. Cells hold one line of text with styles, links and mentions, but not lists or several paragraphs. Column alignment (`:---:`) isn't kept once someone edits the document in the app.

## Dividers

A line with `---` on its own, with a blank line above it, draws a divider. Without the blank line it turns the line above into a heading.

## Callouts

Callouts box a note, tip or warning. Open with `:::` and the type, close with `:::` on its own line.

```markdown
:::note
Refunds go back to the original payment method.
:::

:::caution
Don't refund a payment that's still disputed in Stripe.

1. Check the Disputes tab first
2. If there's a dispute, hand it to Finance
:::
```

| Type | Use it for |
| --- | --- |
| `note` | Useful context |
| `tip` | A better way to do something |
| `info` | Background or a reference |
| `caution` | Something that can go wrong |
| `danger` | Something that can't be undone |

A callout can hold anything: paragraphs, lists, tables, code, even another callout. Other types, titles like `:::note[Heads up]` and GitHub's `> [!NOTE]` aren't supported; the title is dropped when the document is edited, and `> [!NOTE]` stays a plain quote.

## Toggles

A toggle hides detail until someone opens it. Put a blank line after `<summary>` and before `</details>`.

```markdown
<details>
<summary>What if the customer paid by bank transfer?</summary>

Ask Finance to send the refund. It takes 3 to 5 working days.

</details>
```

`<details open>` starts it open. The summary is plain text; the body is any Markdown.

## Alignment

Center, right-align or justify paragraphs and headings by wrapping them:

```markdown
:::center
## Welcome to the team

We're glad you're here.
:::
```

Use `center`, `right`, `justify` or `left`. It applies to text, not images or tables, and works inside callouts.

## Links

```markdown
[Stripe dashboard](https://dashboard.stripe.com)
```

Links to other sites open in a new tab. Links to things in PlaybookOps open in the app and show as a chip with the item's live name. Write them as paths, without the domain:

| Link to | Markdown |
| --- | --- |
| A document | `[Refund policy](https://developers.playbookops.ai/playbooks/PLAYBOOK_ID?content=document&contentId=DOCUMENT_ID)` |
| A project | `[Spring launch](https://developers.playbookops.ai/projects/PROJECT_ID)` |
| An item or task | `[Call the venue](https://developers.playbookops.ai/projects/PROJECT_ID?task=ITEM_ID)` |
| A workflow | `[Onboarding](https://developers.playbookops.ai/workflows/WORKFLOW_ID)` |
| A course | `[New starter course](https://developers.playbookops.ai/learning/COURSE_ID)` |
| A flowchart, video or file | `/playbooks/PLAYBOOK_ID?content=flowchart&contentId=ID`, with `image`, `audio`, `video`, `pdf`, `word_document` or `powerpoint` in place of `flowchart` |

The `url` fields the API returns are full links. Drop the `https://app.playbookops.ai` part to get the path.

## Mentions

Mention a person or a group to notify them and show their name as a chip:

```markdown
Questions go to [@Ana Ruiz](mention://user/PERSON_ID) or [@Support team](mention://group/GROUP_ID).
```

- Get people's ids from `GET /v1/people`.
- The name after `@` is what people see on the chip, so use their current name. Leave out `[`, `]`, `(` and `)`.
- People are notified the first time they're mentioned in a document, when you create it or when a change adds them. They must be active members of your organization; other ids are left as text and nobody is notified.

## Images

```markdown
![The refund screen in Stripe](https://example.com/screenshots/refund.png "Refund screen")
```

- Use a public `https` link. It shows in the app and is included when someone exports the document to PDF or Word.
- Images uploaded in the app live in private storage. When you read a document you get temporary links to them; send them back as they are and they keep working.
- There's no size or alignment option. Images fit the page width.

## Video and audio

```markdown
::media{kind="video" src="https://www.youtube.com/watch?v=VIDEO_ID" title="How to issue a refund"}

::media{kind="audio" src="https://example.com/calls/refund-call.mp3" title="A good refund call"}
```

- `kind` is `video` or `audio`, and `src` must be `https`.
- YouTube, Vimeo and Loom links play in their own player. Other links play as a file, so point them at the video or audio file itself.
- Put each one on its own line. PDF and Word exports don't play media, and show the line as text.

## Not supported

These have no Markdown in PlaybookOps yet. They're kept as text, so nothing is lost, but they won't look special:

- Diagrams, like Mermaid. A `mermaid` code block shows as code; make a flowchart in the playbook and [link to it](#links) instead.
- Math, footnotes, columns and text color.
- Embedded pages (`<iframe>`), scripts and styles, which are removed when the document is shown. Other HTML beyond `<u>`, `<mark>` and `<details>` may show, but the editor drops it the first time someone saves.
- Image sizes, and column alignment in tables.

## After someone edits in the app

The editor saves the same content in a standard form, so the Markdown you read back may differ slightly from what you sent, with the same meaning:

- Line breaks become two trailing spaces.
- Table cells are padded so the columns line up, and column alignment is dropped.
- Callout titles are dropped, and `++underline++` becomes `<u>underline</u>`.

So read before you patch, and match on headings with `replace_section` rather than long `replace_text` strings that span formatting.

## A complete example

```markdown
Use this when a customer asks for their money back. It covers who can get a refund, how to send it, and what to tell them.

## Who can ask

Anyone who paid in the last **30 days**.

:::note
Refunds over $500 need a manager's approval. Ask [@Bea Okafor](mention://user/PERSON_ID).
:::

| Plan | Refund window |
| --- | --- |
| Monthly | 30 days |
| Annual | 60 days |

## How to refund

1. Find the payment in [Stripe](https://dashboard.stripe.com)
2. Refund it to the original payment method
3. Reply using the template below

![The refund button in Stripe](https://example.com/refund-button.png)

::media{kind="video" src="https://www.loom.com/share/VIDEO_ID" title="Walkthrough"}

## Before you close the ticket

- [ ] Refund sent
- [ ] Customer told
- [ ] Ticket tagged `refund`

<details>
<summary>Reply template</summary>

Hi NAME, we've refunded your payment. It should reach you within 5 to 10 working days.

</details>

:::caution
Never refund a payment that's in dispute. See the [disputes process](https://developers.playbookops.ai/playbooks/PLAYBOOK_ID?content=document&contentId=DOCUMENT_ID).
:::
```

The longest document you can send is 500,000 characters.
