# Markdown template

> Build reading pages with rich blocks, live data and forms.

Kind: reference · ~8 min · Verified v0.260.0 · Next: [Markdown forms](https://pr-2373-stg.superartifacts.app/docs/markdown-forms.md)

## What you can make

`markdown-viewer` turns one Markdown source into a reading page. Use prose, images,
video/audio, charts, stats, tabs, columns, details, sortable tables, code, Mermaid diagrams,
math, live CMS values and forms in the same document. The user chooses the template:
use **slideshow** for a deck and **kpi-board** for a dashboard when those are requested.

## Needs

A connected agent at `superartifacts.app/mcp`, your source and permission to publish.
Owners/Editors edit source. CMS blocks need authorized collection grants; forms derive
their response policy from the Markdown. Read [forms](https://pr-2373-stg.superartifacts.app/docs/markdown-forms.md) before collecting personal data.

## Prompts

**Prose.** Make a reading page from my notes with headings, callouts and footnotes.

```prompt
Make a reading page from my notes with headings, callouts and footnotes. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Images.** Add my images with alt text and captions.

```prompt
Add my images with alt text and captions. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Media.** Add my video with captions and a transcript, and my audio recording.

```prompt
Add my video with captions and a transcript, and my audio recording. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Charts.** Add a CSV chart and stat row from the numbers I provide.

```prompt
Add a CSV chart and stat row from the numbers I provide. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Layout.** Group alternate instructions in tabs, comparisons in columns/cards and optional context in details.

```prompt
Group alternate instructions in tabs, comparisons in columns/cards and optional context in details. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Tables.** Add a sortable comparison table; keep numbers numeric.

```prompt
Add a sortable comparison table; keep numbers numeric. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Code.** Add named code fences, a Mermaid diagram with accessible title and the math I provide.

```prompt
Add named code fences, a Mermaid diagram with accessible title and the math I provide. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Cms.** Show the authorized collection as a live table, field, total and boolean toggle. Ask which collection I authorize.

```prompt
Show the authorized collection as a live table, field, total and boolean toggle. Ask which collection I authorize. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Forms.** Add an autosaving feedback form, with a required rating and optional comment.

```prompt
Add an autosaving feedback form, with a required rating and optional comment. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Listen.** Prepare the page for Listen: clear headings, labels and readable media transcripts.

```prompt
Prepare the page for Listen: clear headings, labels and readable media transcripts. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Edit.** Publish source I can edit in Page mode, retaining the same artifact for revisions.

```prompt
Publish source I can edit in Page mode, retaining the same artifact for revisions. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

**Export.** Check Word and PDF export, including readable static fallbacks for live data.

```prompt
Check Word and PDF export, including readable static fallbacks for live data. Use markdown-viewer; read https://superartifacts.app/docs/markdown-template.md and its catalog first. Ask for missing source and authorized collections. Publish privately, derive form policy from directives without policy.fields, and check the result before sharing.
```

## Block catalog

Quote every attribute value. Leaf blocks start with `::`; containers use `:::` and
close with the same colon count. Nested containers need more colons than their parent.
Ordinary Markdown remains the fallback. Unknown attributes show a visible reason.
The [machine catalog](https://pr-2373-stg.superartifacts.app/markdown-catalog.json) is the complete agent reference.
It includes a working example for each block and the default and limit for every option.

### video

| Block | Attributes (quoted values) |
| --- | --- |
| `video` | `src`, `poster`, `captions`, `title`, `ratio` |

````markdown
::video[Demo]{src="demo.mp4" captions="en.vtt"}
````

### audio

| Block | Attributes (quoted values) |
| --- | --- |
| `audio` | `src`, `poster`, `captions`, `title`, `ratio` |

````markdown
::audio[Recording]{src="voice.mp3"}
````

### stat

| Block | Attributes (quoted values) |
| --- | --- |
| `stat` | `value`, `change`, `trend`, `note` |

````markdown
::stat[Revenue: 42]{value="42"}
````

### chart

| Block | Attributes (quoted values) |
| --- | --- |
| `chart` | `type`, `title`, `x`, `y`, `labels`, `unit`, `format` |

````markdown
:::chart{type="bar" title="Count"}
```csv
month,count
Jan,4
```
:::
````

### columns

| Block | Attributes (quoted values) |
| --- | --- |
| `columns` | None |

````markdown
:::columns
::::card[Decision]
Keep the plan.
::::
:::
````

### card

| Block | Attributes (quoted values) |
| --- | --- |
| `card` | None |

````markdown
:::card[Decision]
Keep the plan.
:::
````

### tabs

| Block | Attributes (quoted values) |
| --- | --- |
| `tabs` | None |

````markdown
:::tabs
::::tab[Read]
Read the guide.
::::
:::
````

### tab

| Block | Attributes (quoted values) |
| --- | --- |
| `tab` | None |

````markdown
::::tab[Read]
Read the guide.
::::
````

### details

| Block | Attributes (quoted values) |
| --- | --- |
| `details` | None |

````markdown
:::details[Context]
More detail.
:::
````

### sortable

| Block | Attributes (quoted values) |
| --- | --- |
| `sortable` | None |

````markdown
:::sortable
| Name | Count |
| --- | ---: |
| Oak | 4 |
:::
````

### data-table

| Block | Attributes (quoted values) |
| --- | --- |
| `data-table` | `collection`, `dataset`, `fields`, `audience`, `where`, `sort`, `limit`, `editable` |

````markdown
::data-table[Tasks]{collection="tasks" fields="title"}
````

### form

| Block | Attributes (quoted values) |
| --- | --- |
| `form` | `dataset` |

````markdown
:::form[Name]{dataset="answers"}
::field-text[Name]{name="name"}
________
:::
````

### answers

| Block | Attributes (quoted values) |
| --- | --- |
| `answers` | `fields` |

````markdown
::answers[Your answers]{fields="name"}
````

### data-field

| Block | Attributes (quoted values) |
| --- | --- |
| `data-field` | `collection`, `entry`, `field`, `editable` |

````markdown
::data-field[Title]{collection="tasks" entry="123e4567-e89b-42d3-a456-426614174000" field="title"}
````

### data-stat

| Block | Attributes (quoted values) |
| --- | --- |
| `data-stat` | `collection`, `fn`, `field`, `where` |

````markdown
::data-stat[Tasks]{collection="tasks" fn="count"}
````

### data-toggle

| Block | Attributes (quoted values) |
| --- | --- |
| `data-toggle` | `collection`, `entry`, `field`, `editable` |

````markdown
::data-toggle[Done]{collection="tasks" entry="123e4567-e89b-42d3-a456-426614174000" field="done"}
````

## Reading, editing and exports

| Topic | Behaviour |
| --- | --- |
| The contents pill appears from two match | The contents pill appears from two matching headings; `toc` hides it and `tocDepth` sets its depth (default 3). Listen below the title uses installed local voices: play/pause, paragraph skips, speed, settings and Close. Backgrounding pauses; editing or printing stops speech. Code, math and diagrams use labels. |
| Editing | In the editor, Page mode edits paragraphs, headings, lists, table cells and code. Done/blur commits; Escape cancels. Unsupported blocks, including forms and CMS bindings, open Edit source. Source Undo does not undo CMS writes. See [document editing](https://pr-2373-stg.superartifacts.app/docs/documents.md). |
| Exports | Save before exporting. Word keeps rich blocks, media posters/links and transcripts; unsupported math/diagrams keep source. PDF opens all panels, up to 200 pages. Live CMS exports use authored snapshots; keep private data out of those snapshots. Form exports show blank fields; saved answers stay out. |

## Data access and limits

| Topic | Behaviour |
| --- | --- |
| CMS access | CMS data loads on open or Refresh. Owners/Editors edit when `editable="true"` and the server grants writes; readers see published masked data read-only. Use authorized `policy.collections`, never invented grants. Missing access/offline keeps authored fallback; offline CMS edits are not replayed. A source save preserves grants; an empty list clears them. |
| Limits | Charts: 500 rows, eight series, 65,536 CSV bytes; bar, line, area, stacked, pie, donut. Pie/donut require non-negative values; zero totals show an empty chart. CMS: 200 rows/table, 12 fields, 32 bindings and four collections. Aggregates above 1,000 entries are refused. Directives: four nesting levels, 65,536 bytes each. Source: 400,000 characters. Bundle media: 5 MiB/file, 10 MiB total; larger media needs a hosted HTTPS link. Video never autoplays. YouTube/Vimeo remain links. Tiles fetch no media or live data. These document limits differ from [form upload limits](https://pr-2373-stg.superartifacts.app/docs/markdown-forms.md). |

## Check it worked

Open the published page on a phone and desktop. Expand tabs/details, sort a table,
play media with captions, try Listen and save an edit. Verify fallback text without
CMS access and inspect Word/PDF. If a block fails, check the catalog's quoted attributes;
keep readable fallback text while correcting it.
