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.

[dataset:<uuid>] (and the same form for post/file/route/service/quest/action) is also accepted when the label is omitted. Prefer [label](dataset:<uuid>) so the link has a readable name.

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 view. Create the view first (usually with a prompt); then paste its ID here. Without it, the embed uses the dataset's default inferred chart.
• 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.).

Callouts

Set a paragraph apart as a boxed aside with a GitHub-style alert: a blockquote whose first line names the kind.

> [!WARNING]
> These energies are uncorrected. Don't compare them across functionals.

The kinds are NOTE, TIP, IMPORTANT, WARNING, and CAUTION. Posts read back as markdown keep the same syntax. In the web editor, add one from the slash menu.

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.