AST Structure
The parser returns a SyntaxDocument that contains an abstract syntax tree (AST) of Element nodes. This page describes the element types, expressions, and shared supporting types. Serde serializes a SyntaxDocument as an element array.
Element Enum
Each parsed node is a variant of Element. The tables group the variants by use.
Basic Text
| Variant | Description |
|---|---|
Text | Plain text content |
Comment | Comment block (not rendered) |
Escape | Escaped character (\*, \[, etc.) |
Error | Source retained after a parse failure or incomplete consumption |
Text Styles
| Variant | Description |
|---|---|
Bold | **text** |
Italic | *text* |
Underline | __text__ |
Strikethrough | ~~text~~ |
Superscript | ^^text^^ |
Subscript | ,,text,, |
All text style variants share TextStyleElement, with span and children fields.
Block Elements
| Variant | Description |
|---|---|
Literal | Raw content block {{{ text }}} |
Styled | Styled block {{{ #param text }}} |
Table | Table structure {{{#table ...}}} |
List | Ordered/unordered list {{{#list ...}}} |
Fold | Collapsible section {{{#fold ...}}} |
BlockQuote | Quote block {{{#quote ...}}} |
Code | Fenced code block using backticks |
InlineCode | Inline code span using backticks |
TeX | Math expression using $...$ or $$...$$ |
Css | Raw CSS block opened by {{{#css |
EditorNote | Editor note omitted from rendered output |
Ruby | Ruby annotation {{{#ruby ...}}} |
Footnote | Footnote definition {{{#fn ...}}} |
Line Elements
| Variant | Description |
|---|---|
Header | Heading (#, ##, ..., ######) |
HLine | Horizontal rule (---) |
SoftBreak | Single newline (paragraph continues) |
HardBreak | Explicit [br] line break |
Wiki Elements
| Variant | Description |
|---|---|
Include | Include another document {{{#include ...}}} |
Category | Category assignment {{{#category ...}}} |
Redirect | Page redirect {{{#redirect ...}}} |
Let | Immutable local binding {{{#let name = value}}} |
Param | Typed template input {{{#param name: Type = value}}} |
Expr | Typed value output {{{#expr value}}} |
For | Collection iteration {{{#for item in items :: ...}}} |
Else | Alternative branch after If |
Map | Structured map content |
If | Conditional block {{{#if ... :: ...}}} |
Link and Media Elements
| Variant | Description |
|---|---|
Link | Link element [[Document]], [[Document#anchor | label]], [[https://example.com | label]] |
Media | File media element [[file:image.png | alt text]] |
ExternalMedia | External embed [[#youtube ...]], [[#spotify ...]], etc. |
Macros
| Variant | Description |
|---|---|
Variable | Variable reference [var(name)] |
Mention | User <@uuid>, discussion <#uuid>, or message <^uuid> reference |
TimeNow | Current time [now] |
Date | Current date [date] |
DateTime | Current date and time [datetime] |
Dday | D-day counter [dday(date)] |
PageCount | Page count [pagecount] or [pagecount(namespace)] |
Statistic | Typed live statistics request [stat(...)] |
Age | Age calculation [age(date)] |
Anchor | Named anchor [anchor(name)] |
Clear | Float clear macro [clear] |
FootnoteRef | Footnote list macro [fn] |
Time and statistics display nodes survive server evaluation. The HTML renderer emits inert placeholders and typed descriptors. The frontend fills them after loading cached HTML. A symbolic statistics period such as yesterday is resolved by the data host when requested. Display updates do not alter evaluated branches or references.
Common Element Fields
Many elements have the following fields. This excerpt omits fields specific to each element, such as opening and closing delimiter spans.
struct SomeElement {
pub span: Span, // UTF-8 byte offsets; end is exclusive
pub parameters: Parameters, // #key="value" pairs
pub children: Vec<Element>, // nested elements
}CssElement stores span, open_span, close_span, and a raw value. It does not carry parameters.
Span
pub struct Span {
pub start: usize, // start byte offset in source
pub end: usize, // exclusive end byte offset in source
}Source-backed elements use Span to record UTF-8 byte ranges. Synthesized elements can use Span::synthesized(). The include_locations feature includes element position fields in JSON output. The CodeMirror WASM API converts these positions to UTF-16 code units.
Parameters
pub struct Parameter {
pub span: Span,
pub key: String,
pub value: Vec<Element>, // parsed value, which can contain macros
}Parameters wraps an IndexMap<String, Parameter>. It preserves the source order of distinct names. Keyed lookup uses the last value for a repeated name. duplicates() returns the later occurrences so tools can report diagnostics. Serialization includes the keyed values.
Keys can contain Unicode letters, digits, underscores, and hyphens. Values are AST fragments. For example, a value can contain [var(name)].
Document references
Links, includes, redirects, category membership, and File media share one DocumentReference type:
pub enum DocumentReference {
Id {
document_id: Uuid,
},
Named {
namespace: DocumentNamespace,
parent_document_id: Option<Uuid>,
title: String,
},
}JSON uses kind: "id" or kind: "named". Namespace values are document, file, category, template, user, and site. Site uses only the fixed lowercase token site; the host's language-edition display name is not part of the AST namespace enum. A named root reference has a null parent. A child reference has an exact parent UUID. That scope defines identity; it does not grant inherited access.
LinkTarget::Wiki stores the reference and an optional anchor. MediaSource::File stores the File reference. Include, redirect, and category elements retain an optional parsed reference with their source children. The host resolves references and supplies current authorization decisions.
See document reference syntax for canonical UUID syntax, named scopes, and escaping.
Expression Enum
Bindings, calculations, conditions, iteration, and value output use one typed expression tree. String values contain text rather than markup elements.
| Variant | Description |
|---|---|
Or | Logical OR (||) |
And | Logical AND (&&) |
Not | Logical NOT (!) |
Comparison | Comparison (==, !=, >, <, >=, <=) |
FunctionCall | Registered pure, context, or content function |
TextLiteral | Plain quoted text |
Variable | Bare value name |
NumberLiteral | Integer value |
DecimalLiteral | Exact source decimal |
BoolLiteral | true or false |
Null | null literal |
Group | Parenthesized sub-expression |
Arithmetic | Numeric +, -, *, /, or % |
Negate | Numeric unary minus |
ListLiteral | Ordered collection |
RecordLiteral | Named fields in source order |
Access | List index or Record field access |
Conditional | Selected value (condition ? first : second) |
Coalesce | Null replacement (value ?? default) |
Operators
Comparison operators:
| Kind | Syntax |
|---|---|
Equal | == |
NotEqual | != |
GreaterThan | > |
LessThan | < |
GreaterEqual | >= |
LessEqual | <= |
Logical operators:
| Kind | Syntax |
|---|---|
Or | || |
And | && |
Not | ! |
Table Types
Tables use separate row and cell types so a conditional can produce either:
TableElement
└── children: Vec<TableRowItem>
├── Row(TableRowElement)
│ └── children: Vec<TableCellItem>
│ ├── Cell(TableCellElement)
│ └── Conditional(ConditionalTableCells)
└── Conditional(ConditionalTableRows)TableElement
Selected fields:
pub struct TableElement {
pub span: Span,
pub parameters: Parameters,
pub children: Vec<TableRowItem>,
}TableRowItem
pub enum TableRowItem {
Row(TableRowElement),
Conditional(ConditionalTableRows),
}TableCellItem
pub enum TableCellItem {
Cell(TableCellElement),
Conditional(ConditionalTableCells),
}List Types
Lists can contain items and conditional item groups:
ListElement
└── children: Vec<ListContentItem>
├── Item(ListItemElement)
└── Conditional(ConditionalListItems)ListElement
Selected fields:
pub struct ListElement {
pub span: Span,
pub kind: ListKind,
pub start: Option<u32>, // None uses the default ordered-list start
pub parameters: Parameters,
pub children: Vec<ListContentItem>,
}ListKind is Unordered, OrderedNumeric, OrderedAlphaLower, OrderedAlphaUpper, OrderedRomanLower, or OrderedRomanUpper. A line marker such as 5. or c., or a #start="3" parameter, can set the start value. Unordered lists ignore it.
ListContentItem
pub enum ListContentItem {
Item(ListItemElement),
Conditional(ConditionalListItems),
}Mention Types
pub enum MentionType {
Message, // <^uuid>
Discussion, // <#uuid>
User, // <@uuid>
}Parsing records the UUID and mention kind. Host data adapters resolve readable labels and destinations. Parsing does not send notifications. See mentions.
JSON Serialization Example
Given this input:
# Hello **World**
A paragraph with *italic* text.The following JSON shows selected fields. It omits position and other element metadata:
[
{
"Header": {
"level": 1,
"children": [
{ "Text": { "value": "Hello " } },
{ "Bold": { "children": [{ "Text": { "value": "World" } }] } }
]
}
},
{ "HardBreak": {} },
{
"Text": { "value": "A paragraph with " }
},
{
"Italic": {
"children": [{ "Text": { "value": "italic" } }]
}
},
{
"Text": { "value": " text." }
}
]Each element is an object whose key is its variant name. Element position fields appear only when include_locations is enabled.
Live statistic periods also carry a validated date or a range with from and until calendar dates. A range includes its start and excludes its strictly later end. They remain display descriptors and do not request calculation facts.