| part_of | id:org/kv2bv2m | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| title | Twig | |||||||||||
| author | adammharris | |||||||||||
| created | 2026-07-08 22:39:41 -0700 | |||||||||||
| updated | 2026-08-13 15:50:04 -0700 | |||||||||||
| contents |
|
|||||||||||
| config | .config/prov.yaml | |||||||||||
| registry | registry.yaml | |||||||||||
| id | 9tz497d |
A sister project to fig.
While fig parses configuration files like JSON, YAML, and TOML,
Twig parses document files, like HTML, Markdown, and Djot.
In this way, Twig is comparable to Pandoc, but Twig has different design goals:
-
In Twig, the goal isn't just to be a converter, but to expose the abstract syntax tree of a document, so that precise operations can be performed on it, similarly to how
figallows editing of config files. -
Twig intends to primarily support "round-trippable" formats. This means no first-class support for for "presentation" formats, such as PDF. And no special handling for bibliographies/citations.
The following languages are implemented:
- Djot — 100% conformant with the djot.js corpus: all 265 cases that define an HTML expectation pass. The 6 remaining cases assert against djot.js's internal AST-dump debug format (not HTML); their parser behaviours are covered directly by native AST unit tests instead.
- Markdown (fully CommonMark 0.31.2 conformant — 652/652 spec examples passing), in three named dialects:
markdown(twig's default, CommonMark plus the common extensions),commonmark(strict), andgfm(GitHub-Flavored, with its HTML conventions) - HTML (generic-markup parser + serializer; forgiving document-oriented tree construction)
- XML (generic-markup parser + serializer, strict; every element's attribute region is recorded, so an element's attributes can be rewritten in place by node id — the one gesture a tree-shaped editor needs, and the one XML supports), with
svgas a named dialect so a.svgfile is recognised on sight - AsciiDoc — every block and inline shape the official ASG schema (draft-01) enumerates, plus tables, footnotes, superscript and the other constructs the schema does not model yet; the vendored AsciiDoc TCK passes 13/13 and twig's own schema-validated corpus 137/137. Parses, renders, serializes (
-o asciidoc) and authors.
Twig is written in Rust, with no -sys crate and no native toolchain, and is
laid out as fig is: a kit, a core that
names no language, and one crate per language
(proposal).
crates/twig-kitistwig-kit: what languages share (the tree, spans, the spelling table, the generic HTML printer and theLanguagetrait). It depends on nothing.crates/twigistwig-doc, the core (librarytwig): the editor, the registry, conversion and diagnostics. Its registry starts empty, and it has no language features.- One crate per language, each on the kit alone, with a default
twigfeature that addsregister()andformat():twig-markdown(markdown,commonmark,gfm),twig-djot,twig-html,twig-xml(xml,svg) andtwig-asciidoc.twig-rstis a parser and its conformance harness, not yet a registered format. crates/twig-cliistwig-doc-cli, thetwigcommand-line tool (cargo install twig-doc-cli), with every language registered.crates/twig-capibuilds the C ABI declared inbindings/c/include/twig.h, with every language registered under itsTWIG_FORMAT_*code.bindings/typescriptis@diaryx/twigon npm: that C ABI compiled to WebAssembly and wrapped for TypeScript and JavaScript, in Node, Bun, Deno and the browser (guide).twig-doc's one feature,fig(on by default), reads and edits a document's frontmatter and endmatter through fig 7 (twig::meta), in place, with comments and fences kept, and has every parse read a document as its frontmatter'stwigsettings ask (proposal).
cargo build --release # target/release/twig
cargo test --workspace
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.