# Zoom Canvas Doc XML Content Format

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

This document describes the XML-based content format used by Zoom Canvas docs. It provides a reference for developers using the Zoom Canvas Open API to programmatically create, read, and manipulate document content.

Document content is represented as a tree consisting of:

-   **Block elements**: Define document structure (for example, paragraphs, headings, lists, and tables).
-   **Inline styles**: Define the appearance and semantics of text within block elements.

---

## Document Root

All documents must include a `<document>` root element with a `title` attribute.

```xml
<document title="My Document Title">
  <!-- blocks go here -->
</document>
```

## Block Elements

Block elements are the top-level structural units of a document. They cannot be nested inside inline styles or text placeholders.

## Horizontal Divider

Inserts a horizontal rule.

```xml
<hr/>
```

## Headings

Use up to four levels of headings.

```xml
<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
```

Heading content may include inline styles (see [Inline Styles](/docs/canvas/doc-xml-content-format/#inline-styles)).

## Plain Text

A basic text block (paragraph equivalent):

```xml
<text>This is a paragraph of plain text.</text>
```

## Lists

Zoom Canvas supports three list types: bulleted, ordered, and to-do.

> **Important:**
>
> -   Do not use standard HTML list tags (`<ul>`, `<ol>`, `<li>`). They are not supported by the renderer.

-   Avoid unnecessary nesting. If an outer list adds no semantic value (no title, no description, no additional items), flatten it.

## Bulleted List

Use the `<uli>` tag. Each `<uli>` element represents one bullet item. Items may contain text and nested blocks.

```xml
<uli>First item</uli>
<uli>Second item</uli>
<uli>Third item with nested content
  <uli>Nested bullet</uli>
</uli>
```

## Ordered List

Use the `<oli>` tag. The first item may include a start attribute to set the initial counter.

```xml
<oli start="1">First item</oli>
<oli>Second item</oli>
<oli>Third item</oli>
```

## To-Do List

Use the `<todo>` tag with a checked attribute ("true" or "false").

```xml
<todo checked="false">Incomplete task</todo>
<todo checked="true">Completed task</todo>
```

## Quote

A block-level quotation that can contain other block elements.

```xml
<quote>
  <text>This is a quoted passage.</text>
</quote>
```

## Callout

A highlighted block (similar to an admonition or alert) that can contain other block elements.

```xml
<callout>
  <text>This is an important notice.</text>
</callout>
```

## Code Block

A block of preformatted code. The language attribute specifies the syntax highlighting language (lowercase).

```xml
<code-block language="python">def hello():
    print("Hello, world!")</code-block>
```

**Important**:
The opening `<code-block>` tag must appear on the same line as the first line of code, and the closing `</code-block>` tag must appear on the same line as the last line of code. There must be no leading or trailing blank lines inside the block. Special characters within the code must be HTML-escaped.

## Mermaid Diagram

Mermaid diagrams are authored as code blocks with language="mermaid". They are rendered as visual diagrams.

```xml
<code-block language="mermaid">graph TD
    A["Start"] --> B["Process"]
    B --> C["End"]</code-block>
```

**Tip**: Defensively escape or quote all node labels to avoid conflicts with Mermaid syntax characters.

## Math Block

Renders a block-level mathematical expression (LaTeX syntax).

```xml
<math-block>E = mc^{2}</math-block>
```

## Table of Contents

Inserts an auto-generated table of contents derived from all `<h1>`,`<h2>`, and `<h3>` headings in the document.

```xml
<toc/>
```

This is a self-closing element. You can only add or remove it — it has no configurable attributes.

## Columns

Arranges content into a multi-column layout. Each `<column>` may contain any block elements.

```xml
<columns>
  <column>
    <text>Left column content</text>
  </column>
  <column>
    <text>Right column content</text>
  </column>
</columns>
```

## Table

Tables use a subset of HTML table syntax. Cells may contain block elements, but only lists, quotes, and callouts can be nested inside table cells.

```xml
<table>
  <tbody>
    <tr>
      <td colspan="2">Merged header cell</td>
    </tr>
    <tr>
      <td>Row 1, Col 1</td>
      <td>Row 1, Col 2</td>
    </tr>
  </tbody>
</table>
```

**Attributes** on `<td>`.

| Attribute |  Type  | Default | Description                       |
| :-------- | :----: | ------: | :-------------------------------- |
| `rowspan` | number |       1 | Number of rows the cell spans.    |
| `colspan` | number |       1 | Number of columns the cell spans. |

**Note**: When editing a table, you must replace the entire `<table>` element — partial updates are not supported.

## Unknown Blocks

If you encounter a block element that is not listed in this specification, do not attempt to create or edit it. If you need to include it in output, return it exactly as-is, preserving its ID attribute.

## Inline Styles

Inline styles are used within text content (anywhere a text placeholder appears). They are divided into two categories based on nesting behavior.

## Nestable Container Styles

These styles can wrap other inline styles and plain text, and can be nested within each other.

| Style           |               Syntax                |    Example Output |
| :-------------- | :---------------------------------: | ----------------: |
| Bold            |             <b>text</b>             |       <b>text</b> |
| Italic          |             <i>text</i>             |       <i>text</i> |
| Underline       |             <u>text</u>             |       <u>text</u> |
| Strikethrough   |             <s>text</s>             |       <s>text</s> |
| Text color      |   <h color="rgb(R,G,B)">text</h>    |      colored text |
| Text background | <h background="rgb(R,G,B)">text</h> | highligheted text |

Nesting example:

```xml
<b><i>Bold and italic</i></b>
```

The `<h>` tag supports both color and background attributes simultaneously:

```xml
<h color="rgb(255,255,255)" background="rgb(0,128,255)">White text on blue</h>
```

## Atomic Styles

Atomic styles cannot contain other inline styles. They can appear inside container styles or directly in text.

## Mention Date

Inserts an interactive date reference:

```xml
<mention-date date="2025-11-02"/>
```

Attributes:

| Attribute |     Type     | Default |
| :-------- | :----------: | ------: |
| `date`    | `YYYY-MM-DD` |     Yes |

## Mention Datetime

Inserts an interactive date-and-time reference:

```xml
<mention-datetime date="2025-11-03" time="14:30"/>
```

Attributes:

| Attribute |     Type     | Default |
| :-------- | :----------: | ------: |
| `date`    | `YYYY-MM-DD` |     Yes |
| `time`    |   `HH:MM`    |     Yes |

### Linked

A standard hyperlink:

```
<a href="https://example.com">Link text</a>
```

### Timer

Renders a countdown timer:

```
<timer duration="600000"/>
```

Attributes:

| Attribute |  Type  |                         Description |
| :-------- | :----: | ----------------------------------: |
| Duration  | Number | Countdown duration in milliseconds. |

## Inline Code

Renders monospaced inline code:

```xml
<code>console.log(&quot;hello&quot;)</code>
```

> Special characters inside `<code>` must be HTML-escaped (e.g., `"` → `&quot;`, `<` → `&lt`).

## Syntax Rules and Constraints

1. **Text vs. Blocks**: Text placeholders accept plain text and inline styles only. Block elements cannot appear inside inline styles or text placeholders.
2. **Block containers**: Container placeholders (such as `<quote>`, `<callout>`, `<column>`, `<td>`) accept one or more block elements.
3. **Tag matching**: Every opening tag must have a matching closing tag (or be self-closing). Mismatched tags (e.g., `<uli></oli>`) are invalid.
4. **XML escaping**: All plain text inside tags must be XML-escaped. Use `&amp`; for `&`, `&lt`; for `<`, `&gt`; for `>`, `&quot`; for `"`, and `&apos` for `'`.
5. **Use only documented tags**: Do not introduce custom tags or attributes beyond those described in this specification.

```xml
<document title="Sprint 12 Retrospective">
  <toc/>
  <h1>Sprint 12 Retrospective</h1>
  <text><b>Date:</b> <mention-date date="2025-06-15"/></text>
  <h2>Action Items</h2>
  <todo checked="true">Migrate auth service to v2 API</todo>
  <todo checked="false">Update monitoring dashboards</todo>
  <h2>Discussion Notes</h2>
  <quote>
    <text>Deployment frequency improved by 40% this sprint.</text>
  </quote>
  <text>
    For implementation details, see the
    <a href="https://docs.example.com/deploy">deployment guide</a>.
  </text>
  <h2>Architecture Overview</h2>
  <code-block language="mermaid">graph LR
    A["Client"] --> B["API Gateway"]
    B --> C["Auth Service"]
    B --> D["Core Service"]</code-block>
</document>
```