Components

Everything on this page is plain Markdown plus the extensions configured in mkdocs.yml. No component needs HTML beyond a wrapping <div markdown>, and none needs page-specific CSS or JavaScript.

Callouts#

Use a callout for information the reader must not miss. One per screen is plenty; a page full of callouts has none.

!!! warning "Optional title"
    Body, indented four spaces. Any Markdown works here.

Types: note, info, tip, success, warning, danger, example, quote — plus the aliases abstract, question, hint, check, caution, error, failure and bug. Use !!! note "" for a callout without a title.

Expandable sections#

Collapsed by default with ???, open by default with ???+:

??? question "Why is this collapsed?"
    Hidden until the reader opens it.

Tabs#

Tabs with the same label stay in sync across the page, and the reader's choice is remembered on other pages — pick Python here and every Python tab opens.

=== "Python"

    Content for Python.

=== "TypeScript"

    Content for TypeScript.

Code#

Code blocks#

Fences take a language, an optional title, line numbers and highlighted lines. Every block gets a copy button.

import httpx


def wallet(api_url: str, token: str) -> dict:
    """Return the account wallet."""
    response = httpx.get(
        f"{api_url}/developer/account/wallet",
        headers={"authorization": f"Bearer {token}"},
    )
    response.raise_for_status()
    return response.json()

```python title="client.py" linenums="1" hl_lines="6 7"
…
```

Code groups#

A tab set whose tabs each hold one code block becomes a code group:

wallet = httpx.get(f"{api}/developer/account/wallet", headers=auth).json()

const wallet = await (await fetch(`${api}/developer/account/wallet`, { headers })).json();

$ curl -sS "$YSRA_API_URL/developer/account/wallet" -H "authorization: Bearer $YSRA_TOKEN"

Terminal sessions#

Use the console language for commands with output. Prompts and output are styled apart, and copy takes only the commands — never the $ or the output.

$ uv run mkdocs build --strict
INFO    -  Building documentation to directory: site
INFO    -  Documentation built in 1.42 seconds
$ uv run python scripts/check_site.py
✓ 20 pages; initial CSS 10.9 kB + JS 6.5 kB gzipped

For a single command with no output, bash is fine:

export YSRA_API_URL="https://api-sandbox.ysra.ai"

Diffs, config and data#

- delivery_mode: preserve_only
+ delivery_mode: draft_pr

nav:
  - Home: index.md
  - Getting started:
      - Quickstart: getting-started/quickstart.md

Inline code#

Refer to fields, commands and /paths in backticks. Inline highlighting takes a language shebang: Decimal(wallet["available_usd"]).

Diagrams#

Mermaid fences render as diagrams in the site's own colours and follow the light and dark themes. Mermaid loads only on pages that have a diagram.

sequenceDiagram
    autonumber
    participant C as Client
    participant A as Ysra API
    participant W as Worker
    C->>A: POST /developer/sessions
    A-->>C: 201 session
    A->>W: dispatch
    W-->>A: checkpoint, evidence
    A-->>C: stream events (WebSocket)

```mermaid
sequenceDiagram
    Client->>API: POST /developer/sessions
```

Cards#

A list inside <div class="cards" markdown>. The first link in each item makes the whole card clickable.

<div class="cards" markdown>

- [**Sessions**](../developer/index.md)

    Lifecycle, checkpoints and steering.

</div>

Steps#

Level-three headings inside <div class="steps" markdown> are numbered and joined by a rail. They still appear in "On this page" and get anchors.

<div class="steps" markdown>

### Install the dependencies

Run `uv sync`.

</div>

Badges#

Beta Stable Deprecated Breaking New v1.4

**Stable**{ .badge .ok }

Tones: none, ok, warn, danger, info, accent. In the sidebar, the status: new | beta | deprecated front matter key adds a badge to a page's link.

API reference#

An endpoint line, then a definition list of parameters inside <div class="params" markdown>:

PATCH /developer/account/knowledge/{entry_id}

`PATCH`{ .patch } `/developer/account/knowledge/{entry_id}`
{ .endpoint }

<div class="params" markdown>

`expected_version` `integer`{ .type } **required**{ .required }
:   The `version` you last read.

</div>

Methods: .get, .post, .put, .patch, .delete.

Tables#

Wide tables scroll inside their frame instead of squeezing columns. Align a column with :--, :-: or --: in the separator row.

Text#

• Keyboard keys: Cmd+K or Ctrl+K opens search; / works too.
• Highlight with ==text==: decimal strings, never floats.
• Insertions and deletions: added and removed.
• Abbreviations are defined once and explained on hover: the API returns JSON.
• Footnotes collect at the end of the page.¹
• Task lists:
  • Build with --strict
  • Publish a second version with mike

Images#

Standard Markdown images are lazy-loaded and framed. Add a caption with a /// caption block:

Links to headings#

Every heading has an anchor: hover it and click the # to copy a link. Link to a heading on another page with its slug — for example the wallet ledger. The build fails if the anchor does not exist.