Known limitations
What Wit does not do yet, or does with a documented rough edge. Every row is
re-verified against the current build. Where a fixture pins the behaviour, it is
cited.
Parsing and authoring
Parsing| Limitation | Impact | Workaround |
|---|
| greedy pipes-bind ordering | a pipes call with no same-line close binds to the next close | close on the same line or place pipes calls last |
| comment as first child of a container | following blocks collapse into one paragraph | blank line after the comment |
| single-line def with captures | renders the literal capture list | use the block def form |
| colon delimiter in data-def records | LSP rejects it though the CLI tolerates call sites | use the hyphen delimiter |
| at-strings in record values | emails and paths break record parsing | keep at-strings out of record values |
| inline table cells cannot be quoted | commas split a cell and quotes stay literal | avoid commas in cells or use a schema form |
| a node name opened two ways | a self-closing @x(...) plus a block @x … x@ of the same name in one file reads as unclosed | open each node name only one way |
Data and access
Data| Limitation | Impact | Workaround |
|---|
| numeric index access | @list.0 and @rec.0.field render unresolved | use each or feed the collection to a table |
| bare data-def reference | @record emits an empty wit-node placeholder | access a field or iterate |
| CSV/TSV sources have no quoted fields | a comma or tab inside a field breaks rows | emit JSON or pre-clean the data |
Rendering
Rendering| Limitation | Impact | Workaround |
|---|
| raw table cannot resolve a ref | a raw double-at table leaves rows @ref literal | use the ordinary table node |
| HTML renderer is configuration-free | one fixed HTML shape per AST kind; table and bibliography are hard-coded special cases | post-process the HTML or restyle with CSS |
| table centering is theme-only | the reset-only raw pathway does not centre tables | add your own CSS under raw |
| script output only renders in top-level prose | @scriptCall and inline percent-blocks render empty inside a node body | keep scripted output at the top level |
Tooling and platform
Tooling| Limitation | Impact | Workaround |
|---|
| PDF needs a system Chrome | no bundled engine | install Chrome or Chromium or set WIT_CHROME |
| config is JSON-only | no TOML yet | use wit.sources.json |
| LSP is stricter than the CLI | a file can check clean yet show squiggles | prefer the portable forms |
See also
Gotchas · Errors · Data model · Tables.