AtlatestRepositorysigil-doc

sigil-doc / tree / docssemantic-structures.md

Read it rendered

1# Semantic lists, tables, and media
2
3Sigil Doc represents common document structures as model nodes rather than as
4renderer-specific markup. The same manuscript therefore produces accessible HTML,
5native Typst structures, deterministic plain text, and useful traversal events.
6
7```sigil-doc
8@items
9 @item {An unordered item}
10 @item
11 @p {A nested ordered list:}
12 @items[ordered: #t start: 3]
13 @item {Number three}
14 @item {Number four}
15 @end items
16 @end item
17@end items
19@table[caption: "Key bindings" columns: '(left center)]
20 @row[header: #t]
21 @cell {Action}
22 @cell {Binding}
23 @end row
24 @row
25 @cell {Open a file}
26 @cell {@code{C-x C-f}}
27 @end row
28@end table
30@video["video-id"
31 provider: 'cloudflare
32 title: "A demonstration"
33 print: 'omit]{}
34```
36`@items` accepts `ordered:` (default `#f`) and `start:` (default `1`). Each
37direct child must be an `@item`; an item may contain ordinary blocks and nested
38lists.
40`@table` requires one alignment per column (`left`, `center`, or `right`). Rows
41must have exactly that many cells. The first row may use `header: #t`; later
42header rows are rejected. Captions are optional and cells may be empty.
44`@video` is passive metadata. HTML emits a provider-neutral figure for a site
45theme or adapter to enhance; parsing and rendering never fetch or execute media.
46Providers are `cloudflare`, `youtube`, and `url`. Print policy is either `omit`
47or `link`, so a book can deliberately exclude video while retaining it on the
48site. The `link` policy preserves the destination as a clickable Typst link:
49YouTube IDs resolve to `https://www.youtube.com/watch?v=<id>`, Cloudflare Stream
50IDs resolve to `https://iframe.videodelivery.net/<id>`, and `url` sources are
51used directly.