docs/semantic-structures.md
Semantic lists, tables, and media
Sigil Doc represents common document structures as model nodes rather than as renderer-specific markup. The same manuscript therefore produces accessible HTML, native Typst structures, deterministic plain text, and useful traversal events.
@items
@item {An unordered item}
@item
@p {A nested ordered list:}
@items[ordered: #t start: 3]
@item {Number three}
@item {Number four}
@end items
@end item
@end items
@table[caption: "Key bindings" columns: '(left center)]
@row[header: #t]
@cell {Action}
@cell {Binding}
@end row
@row
@cell {Open a file}
@cell {@code{C-x C-f}}
@end row
@end table
@video["video-id"
provider: 'cloudflare
title: "A demonstration"
print: 'omit]{}@items accepts ordered: (default #f) and start: (default 1). Each direct child must be an @item; an item may contain ordinary blocks and nested lists.
@table requires one alignment per column (left, center, or right). Rows must have exactly that many cells. The first row may use header: #t; later header rows are rejected. Captions are optional and cells may be empty.
@video is passive metadata. HTML emits a provider-neutral figure for a site theme or adapter to enhance; parsing and rendering never fetch or execute media. Providers are cloudflare, youtube, and url. Print policy is either omit or link, so a book can deliberately exclude video while retaining it on the site. The link policy preserves the destination as a clickable Typst link: YouTube IDs resolve to https://www.youtube.com/watch?v=<id>, Cloudflare Stream IDs resolve to https://iframe.videodelivery.net/<id>, and url sources are used directly.