Extended markdown

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 (Editor or content_markdown), and MCP (content_markdown on create_post, write_comment, and send_message).

User mentions

Mention a user inline:

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:

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:

```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; 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:

```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).

<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:

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

From a file:

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.

Where it applies

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