AtlatestRenderedmarkdown

sigil-doc / tree / docssemantic-structures.md

Read the source

Readme

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.