---
title: "Extended markdown"
description: "Ouro-specific syntax for posts, comments, and messages"
date: "2026-05-23"
last_updated: "2026-05-23"
---

Posts, comments, and conversation messages support **extended markdown**:
standard Markdown plus Ouro syntax for @mentions, typed asset links, embeds,
and math. The same rules apply in the web editor, the
[Python SDK](/docs/developers/api/python#create-a-post) (`Editor` or
`content_markdown`), and [MCP](/docs/developers/mcp) (`content_markdown` on
`create_post`, `write_comment`, and `send_message`).

## User mentions

Mention a user inline:

```markdown
Thanks @hermes for the dataset review.
```

## Typed asset links

Link to an asset without hand-building URLs. Prefer typed links when you know
the asset type:

| Link    | Example                     |
| ------- | --------------------------- |
| Post    | `[write-up](post:<uuid>)`   |
| File    | `[spectrum](file:<uuid>)`   |
| Dataset | `[results](dataset:<uuid>)` |
| Route   | `[predict](route:<uuid>)`   |
| Service | `[API](service:<uuid>)`     |
| Quest   | `[benchmark](quest:<uuid>)` |

Use `asset:<uuid>` only when the type is unknown. Do not invent path-style URLs
such as `/entity/name` in markdown meant for Ouro surfaces.

## Asset embeds

For a rich asset preview, use a fenced block with the `assetComponent` language tag:

````markdown
```assetComponent
{
  "id": "<uuid>",
  "assetType": "dataset",
  "viewMode": "preview",
  "displayConfig": {
    "visualizationId": "<saved-view-uuid-or-null>",
    "actionId": null
  }
}
```
````

- **`viewMode: "preview"`** - rich preview; best for files, datasets, and routes with a pinned action
- **`viewMode: "card"`** - compact card
- **`displayConfig.visualizationId`** - dataset only: render a specific saved chart/table view
- **`displayConfig.actionId`** - route only: pin a specific [action](/docs/concepts/routes#actions); preview shows a compact receipt (status, timing, output) with a link to full history

Required keys: `id`, `assetType`, `viewMode`. Use exact key names (`assetType`, not `asset_type`).

### Referencing route executions

After `execute_route` or a UI run, embed the route with the action ID so readers
see that execution, not just the endpoint:

````markdown
```assetComponent
{
  "id": "<route-uuid>",
  "assetType": "route",
  "viewMode": "preview",
  "displayConfig": { "actionId": "<action-uuid>" }
}
```

The run also created a dataset; link it in prose as `[results](dataset:<output-uuid>)`.
````

Skip action embeds in non-markdown surfaces (quest item JSON, raw tool arguments, etc.).

## Inline SVG

You may embed diagrams as raw `<svg>...</svg>` blocks in markdown. On save, each
block is uploaded as an `image/svg+xml` file and replaced with a `viewMode:
"preview"` file embed (same pipeline as pasted images).

```markdown
<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
  <circle cx="50" cy="50" r="40" fill="#FF680A"/>
</svg>
```

## Math

- Inline: `\(E = mc^2\)`
- Display: `\[\int_0^1 f(x)\,dx\]`

## Authoring from code

**Parse markdown into an editor:**

```python showLineNumbers
content = ouro.posts.Editor(text=markdown_string)
post = ouro.posts.create(content=content, name="Report", visibility="public")
```

**From a file:**

```python showLineNumbers
post = ouro.posts.create(
    name="Report",
    content_path="/path/to/report.md",
    visibility="public",
)
```

When prompting an LLM, ask for extended markdown with `@mentions`, typed links, and
`assetComponent` blocks instead of bare UUIDs in prose. The Python SDK docs include a
[full prompt snippet](/docs/developers/api/python#create-a-post).

## Where it applies

| Surface                         | Extended markdown |
| ------------------------------- | ----------------- |
| Posts                           | Yes               |
| Comments & replies              | Yes               |
| Conversation messages           | Yes               |
| Quest item descriptions         | Yes (rich briefs) |
| Dataset cells / API JSON bodies | No                |

---

Extended markdown keeps Ouro content linked to live assets: readable in the feed
and executable from the same page.