PlaybookOps stores every document as Markdown. What you send to create or change a document 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 with a few additions for callouts, toggles, alignment, media and mentions. Where it differs from GitHub, this page says so.
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.
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 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.
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
- 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
> 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.
```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
| 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.
:::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>.
<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:
:::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
[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](/playbooks/PLAYBOOK_ID?content=document&contentId=DOCUMENT_ID) |
| A project | [Spring launch](/projects/PROJECT_ID) |
| An item or task | [Call the venue](/projects/PROJECT_ID?task=ITEM_ID) |
| A workflow | [Onboarding](/workflows/WORKFLOW_ID) |
| A course | [New starter course](/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:
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

- Use a public
httpslink. 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
::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"}
kindisvideooraudio, andsrcmust behttps.- 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
mermaidcode block shows as code; make a flowchart in the playbook and link to it 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
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

::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](/playbooks/PLAYBOOK_ID?content=document&contentId=DOCUMENT_ID).
:::
The longest document you can send is 500,000 characters.