Skip to content

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 ​

VariantDescription
TextPlain text content
CommentComment block (not rendered)
EscapeEscaped character (\*, \[, etc.)
ErrorSource retained after a parse failure or incomplete consumption

Text Styles ​

VariantDescription
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 ​

VariantDescription
LiteralRaw content block {{{ text }}}
StyledStyled block {{{ #param text }}}
TableTable structure {{{#table ...}}}
ListOrdered/unordered list {{{#list ...}}}
FoldCollapsible section {{{#fold ...}}}
BlockQuoteQuote block {{{#quote ...}}}
CodeFenced code block using backticks
InlineCodeInline code span using backticks
TeXMath expression using $...$ or $$...$$
CssRaw CSS block opened by {{{#css
EditorNoteEditor note omitted from rendered output
RubyRuby annotation {{{#ruby ...}}}
FootnoteFootnote definition {{{#fn ...}}}

Line Elements ​

VariantDescription
HeaderHeading (#, ##, ..., ######)
HLineHorizontal rule (---)
SoftBreakSingle newline (paragraph continues)
HardBreakExplicit [br] line break

Wiki Elements ​

VariantDescription
IncludeInclude another document {{{#include ...}}}
CategoryCategory assignment {{{#category ...}}}
RedirectPage redirect {{{#redirect ...}}}
LetImmutable local binding {{{#let name = value}}}
ParamTyped template input {{{#param name: Type = value}}}
ExprTyped value output {{{#expr value}}}
ForCollection iteration {{{#for item in items :: ...}}}
ElseAlternative branch after If
MapStructured map content
IfConditional block {{{#if ... :: ...}}}
VariantDescription
LinkLink element [[Document]], [[Document#anchor | label]], [[https://example.com | label]]
MediaFile media element [[file:image.png | alt text]]
ExternalMediaExternal embed [[#youtube ...]], [[#spotify ...]], etc.

Macros ​

VariantDescription
VariableVariable reference [var(name)]
MentionUser <@uuid>, discussion <#uuid>, or message <^uuid> reference
TimeNowCurrent time [now]
DateCurrent date [date]
DateTimeCurrent date and time [datetime]
DdayD-day counter [dday(date)]
PageCountPage count [pagecount] or [pagecount(namespace)]
StatisticTyped live statistics request [stat(...)]
AgeAge calculation [age(date)]
AnchorNamed anchor [anchor(name)]
ClearFloat clear macro [clear]
FootnoteRefFootnote 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.

rust
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 ​

rust
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 ​

rust
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:

rust
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.

VariantDescription
OrLogical OR (||)
AndLogical AND (&&)
NotLogical NOT (!)
ComparisonComparison (==, !=, >, <, >=, <=)
FunctionCallRegistered pure, context, or content function
TextLiteralPlain quoted text
VariableBare value name
NumberLiteralInteger value
DecimalLiteralExact source decimal
BoolLiteraltrue or false
Nullnull literal
GroupParenthesized sub-expression
ArithmeticNumeric +, -, *, /, or %
NegateNumeric unary minus
ListLiteralOrdered collection
RecordLiteralNamed fields in source order
AccessList index or Record field access
ConditionalSelected value (condition ? first : second)
CoalesceNull replacement (value ?? default)

Operators ​

Comparison operators:

KindSyntax
Equal==
NotEqual!=
GreaterThan>
LessThan<
GreaterEqual>=
LessEqual<=

Logical operators:

KindSyntax
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:

rust
pub struct TableElement {
    pub span: Span,
    pub parameters: Parameters,
    pub children: Vec<TableRowItem>,
}

TableRowItem ​

rust
pub enum TableRowItem {
    Row(TableRowElement),
    Conditional(ConditionalTableRows),
}

TableCellItem ​

rust
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:

rust
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 ​

rust
pub enum ListContentItem {
    Item(ListItemElement),
    Conditional(ConditionalListItems),
}

Mention Types ​

rust
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:

sevenmark
# Hello **World**

A paragraph with *italic* text.

The following JSON shows selected fields. It omits position and other element metadata:

json
[
  {
    "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.