> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# annotate

> Reference for the `annotate` schema.

## Referenced In

* [Markup definition](/reference/schemas/markup-definition)
* [test](/reference/schemas/test)
* [Resolved context](/reference/schemas/resolved-context)

## Fields

| Field    | Type                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                   | Default |
| :------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| annotate | object([annotate](/reference/schemas/annotate)) | Required. Adds, updates, or clears annotations that stay on screen until something clears them. Unlike a screenshot's own `annotations` — which live only for that capture — these are drawn into the page, so they appear in recordings and in any screenshot taken while they're up. Annotations added here persist across steps and across navigation until an `annotate` step clears them, their `duration` elapses, or the context ends. | —       |

## Examples

```json
{
  "annotate": {
    "add": [
      {
        "outline": "#submit-button"
      }
    ]
  }
}
```

```json
{
  "annotate": {
    "add": [
      {
        "id": "step-counter",
        "badge": "#username",
        "label": "1"
      },
      {
        "id": "guide",
        "callout": "#username",
        "label": "Pick your identity provider first",
        "position": "right",
        "track": true
      }
    ]
  }
}
```

```json
{
  "annotate": {
    "add": [
      {
        "id": "redact-api-keys",
        "blur": {
          "selector": ".api-key"
        },
        "all": true,
        "track": true,
        "transition": {
          "enter": "none"
        }
      }
    ]
  }
}
```

```json
{
  "annotate": {
    "update": [
      {
        "id": "step-counter",
        "badge": "#metadata-url",
        "label": "2"
      }
    ]
  }
}
```

```json
{
  "annotate": {
    "add": [
      {
        "outline": "#usage-meter",
        "duration": 3500,
        "transition": {
          "enter": "draw",
          "exit": "fade",
          "durationMs": 400
        }
      }
    ]
  }
}
```

```json
{
  "annotate": {
    "clear": [
      "guide"
    ]
  }
}
```

```json
{
  "annotate": {
    "clear": true
  }
}
```