Getting Started | API Reference

yume-dsl-rich-text has three tag forms. Memorize this diagram and you're good:

┌─ Inline ───────────────────────────────────────┐
│  $$bold(Hello $$italic(world)$$)$$             │
│                                                │
│  → Opens and closes within text flow           │
│  → Content parsed recursively (nesting!)       │
│  → Most common: bold, italic, links            │
│                                                │
│  Shorthand (1.3): $$bold(Hello italic(world))$$│
│  → Requires implicitInlineShorthand            │
│  → Closed by `)` alone, no `$$` wrapper        │
└────────────────────────────────────────────────┘

┌─ Raw ─────────────────────────────────────┐
│  $$code(typescript)%                      │
│  const x = 1;                             │
│  %end$$                                   │
│                                           │
│  → Content NOT parsed, kept verbatim      │
│  → Close marker %end$$ must be on own line│
│  → For code blocks, math, etc.            │
└───────────────────────────────────────────┘

┌─ Block ───────────────────────────────────┐
│  $$info(Note)*                            │
│  This is $$bold(important)$$ info.        │
│  *end$$                                   │
│                                           │
│  → Content parsed recursively (like inline)│
│  → Close marker *end$$ must be on own line│
│  → For callouts, warnings, collapsibles   │
└───────────────────────────────────────────┘

Allowed: a-z, A-Z, 0-9, _, -. First character can't be a digit or -.

✅ bold  myTag  h1  code_block  custom-tag
❌ 1tag  -tag

Want colons, dots, etc.? → Custom Tag Name Characters

$$tagName(content)$$

The most common form. Content is parsed recursively, tags can nest:

$$bold(Hello $$italic(beautiful)$$ world)$$

→ bold wrapping an italic — totally valid. Nest as deep as you want (default limit: 50 levels).

Since 1.3 — requires implicitInlineShorthand option enabled.

Inside an inline argument context, registered tag names can use a shorter name(...) form — no $$ prefix needed:

$$bold(Hello italic(world))$$

is equivalent to:

$$bold(Hello $$italic(world)$$)$$

Rules:

• Only works inside inline args, never at top level.
• Full DSL syntax ($$tag(...)$$) always takes priority over shorthand.
• Literal parentheses in shorthand args must be escaped: \( and \).
• Only tags registered in handlers (and supporting inline form) are recognized as shorthand.

The parser is a stack-top-priority stepping state machine. It scans characters left to right, always checking against the topmost frame's close token. Two core rules:

1. Nearest match: the topmost frame gets first dibs on every token. If it matches, the frame closes. If not, the token is treated as text and the scanner moves on. No lookahead, no future prediction.
2. Longer token wins at the same position: when the shorthand close token ()) is a prefix of the full endTag ()$$), and the full endTag matches at the current position, endTag takes priority — the shorthand yields and degrades to plain text. This is local lexical disambiguation, not syntactic lookahead.

The shorthand close token ) is a prefix of the full close token )$$. Without disambiguation, the shorthand would split )$$ into ) + $$, breaking the outer tag's close token atomicity.

$$bold(bold(hi)$$)$$
                ^
shorthand bold('s ) happens to be part of )$$
→ if shorthand takes ), )$$ is broken, outer $$bold(...) can never close
→ disambiguation: )$$ fully matches, shorthand yields, "bold(hi" degrades to text
→ outer $$bold(...) closes normally ✅

$$bold(bold(hi $$italic(world)$$))$$

$$bold(     -> push bold (wants )$$)
bold(       -> push shorthand (wants ))
hi          -> text
$$italic(   -> push italic (wants )$$)
world       -> text
)$$         -> italic closes
)           -> shorthand wants ), next chars are )$$ not $$
             -> current position is NOT )$$ -> shorthand closes normally
)$$         -> bold closes

Result: bold -> [shorthand bold -> [text "hi ", italic("world")]]. All three layers close correctly.

$$bold(bold(hi $$italic(world)$$)$$

Note the tail: world + )$$ (italic close) + )$$ (bold close).

$$bold(     -> push bold (wants )$$)
bold(       -> push shorthand (wants ))
hi          -> text
$$italic(   -> push italic (wants )$$)
world       -> text
)$$         -> italic closes
)$$         -> shorthand wants ), but )$$ fully matches
             -> yields, "bold(" degrades to text, bold rescans from argStartI
hi          -> text (bold rescanning)
$$italic(   -> push italic (wants )$$) (bold re-encounters same segment)
world       -> text
)$$         -> italic closes (first )$$)
)$$         -> bold closes (second )$$)

Result: bold's children are "bold(hi " + italic("world"). The shorthand degraded to text, italic was re-parsed, and the two )$$ close italic and bold respectively.

$$bold(a(b(c)))$$

$$bold(   -> push bold (wants )$$)
a(        -> push shorthand a (wants ))
b(        -> push shorthand b (wants ))
c         -> text
)         -> b closes (next chars are ))$$, not $$)
)         -> a closes (next chars are )$$, not $$)
)$$       -> bold closes

Each ) doesn't overlap with )$$, so nearest match applies cleanly at every level.

All outputs below are from real parseRichText + extractText runs.

Note: in default syntax, shorthand is only active inside inline-arg context; the switch only affects name(...).

Note: malformed-input recovery is intentionally local (local success/local failure at nearest boundaries), and is not guaranteed to be byte-for-byte identical to historical versions.

Input:

=bold<天気がbold<いlink<baidu.com>=>から>=散歩しましょう

Expected (current spec):

天気がbold<いlink<baidu.com>から>=散歩しましょう

Intuitively, link<baidu.com> looks like a well-formed shorthand tag. But applying the rules:

1. The >= after baidu.com is a complete endTag — not "link's > followed by a stray =".
2. Full close wins — >= is indivisible and belongs to the outer =bold<...>=, which closes.
3. The inner bold< and link< have no independent close token → local degradation to text.

If > were allowed to win instead (letting link close), the shorthand would close and return to root context — but root cannot host shorthand, so the entire deduction chain becomes self-contradictory. EndTag priority is not a preference; it is the only logically consistent rule.

To make link close normally, just insert a space between > and = so they don't form an endTag:

=bold<天気がbold<いlink<baidu.com> =>から>=散歩しましょう

Rules are explicit; the user is in control.

See ParseOptions — implicitInlineShorthand for configuration.

$$tagName(arg)%
raw content — not parsed
even $$fake(tags)$$ are kept as-is
%end$$

arg in parentheses is an optional parameter (e.g., language name for code). %end$$ must be on its own line.

Example — code block:

$$code(typescript)%
function greet(name: string) {
    return `Hello, ${name}!`;
}
%end$$

Handler receives: arg = "typescript", content = "function greet(name: string) {...}".

$$tagName(arg)*
content is parsed recursively — other tags work inside
*end$$

*end$$ must be on its own line. For larger structural containers.

Example — info callout:

$$info(Note)*
This is $$bold(important)$$ information.
*end$$

Inside any tag's parentheses, | separates parameters:

$$link(Click here | https://example.com)$$
$$link(Click here | https://example.com | _blank)$$

Works in raw/block tags too:

$$code(typescript | line-numbers)%
const x = 1;
%end$$

Use parsePipeArgs / PipeArgs in your handler to split them.

Use \| for a pipe that shouldn't be treated as a separator:

$$tag(a\|b | c)$$
→ two params: "a|b" and "c"

Backslash \ is the default escape character. Escaping only works for tokens that have structural meaning in the current context — if a token has no special meaning at the current position, the backslash is kept as-is.

In default syntax, tagOpen = (, tagClose = ), endTag = )$$. Note that $$ is the tagPrefix, not an independent token — it cannot be escaped.

Note: At root level, \|, \\, \%end$$, \*end$$ etc. are not escaped — the backslash is kept verbatim, because these tokens have no structural meaning at root.

The escape character itself can be changed via SyntaxConfig.escapeChar. See Custom Syntax.

The parser never crashes or throws on malformed input. All unexpected patterns degrade to literal plain text, with errors reported when possible.

All degradation behavior is derived from two core rules — no special cases:

1. Nearest match — the topmost stack frame gets first dibs on every token. A close token belongs to the nearest matching frame. No skipping, no lookahead.
2. Full close wins — when a short token (e.g. )) is a prefix of a longer token (e.g. )$$), and the longer token fully matches at the current position, the longer token wins.

From these two rules, one degradation strategy follows: local error, local degradation.

• Correctly written parts keep their structure; only the layer that is actually broken degrades to plain text.
• The blast radius of an error is precisely contained to the nearest layer — parent and sibling nodes are unaffected.
• The parser never guesses user intent and never attempts heuristic "maximize salvage" recovery — determinism is preferred over cosmetically nicer output.

Example — shorthand yields to protect the outer structure:

$$bold(bold(hi)$$)$$

The )$$ after bold(hi is both the shorthand's ) and the outer bold's )$$. Full close wins → )$$ belongs to the outer bold; the shorthand bold( has no close token and degrades to plain text. The outer bold closes normally; its content is bold(hi. The trailing )$$ is a stray close marker.

If ) were allowed to win instead, the shorthand would close and split )$$ into ) + $$, destroying the outer bold's close token — the entire tree collapses.

When a handler only declares some forms, writing an undeclared form → entire markup degrades to literal text, no error.

// handler only declares raw
code: { raw: (arg, content) => ... }

// user writes inline form → degrades to plain text
$$code(hello world)$$
→ plain text output: "$$code(hello world)$$"

Decision rules (supportsInlineForm table, first match wins top-to-bottom):

This is the most common gotcha. To nest a raw or block tag inside an inline argument, the handler must also declare inline.

The inline argument scanner advances character-by-character and checks every nested tag against supportsInlineForm before pushing a child frame. Only tags that pass this check enter the child frame; only inside the child frame can the parser see )% or )* to switch to the raw / block branch.

                    ┌── must pass supportsInlineForm ──┐
                    │                                   │
$$bold( ... $$code(arg)%...%end$$ ... )$$
              │
              └── code only has raw, no inline
                  → can't enter child frame → entire $$code(...)%...%end$$ becomes plain text

// ❌ code only has raw → degrades to plain text when nested inside inline args
const handlers = {
    bold: { inline: (tokens) => ({ type: "bold", value: tokens }) },
    code: { raw: (arg, content) => ({ type: "code", value: content }) },
};

// $$bold(before $$code(ts)%const x = 1;%end$$ after)$$
// → code section inside bold becomes plain text

// ✅ code also declares inline → parser enters child frame, then sees )% and switches to raw
const handlers = {
    bold: { inline: (tokens) => ({ type: "bold", value: tokens }) },
    code: {
        inline: (tokens) => ({ type: "code", value: tokens }),  // ← add this
        raw: (arg, content) => ({ type: "code", value: content }),
    },
};

Note: The inline handler doesn't need complex logic — it's just a "ticket" to let the parser push a child frame for that tag. If your tag doesn't semantically need an inline form, the inline handler can return a fallback output (e.g., echo the text as-is).

Same applies to block tags nested inside inline arguments — they also need inline declared:

// ✅ warn declares inline + block → can nest block form inside inline args
warn: {
    inline: (tokens) => ({ type: "warn", value: tokens }),
    block: (arg, content) => ({ type: "warn", value: content }),
}

When depth exceeds depthLimit (default 50), the tag head degrades to plain text with a DEPTH_LIMIT error. Outer tags are unaffected.

// with depthLimit: 3
$$a($$b($$c($$d(too deep)$$)$$)$$)$$
                 ^^^^^^^^^^^^^^^^
                 degrades to plain text "$$d(too deep)$$"

Shorthand form also respects depthLimit (fixed in 1.3.1).

When brackets inside the argument region don't balance (e.g., raw parentheses in content, or a missing close bracket), the fast argument-close scanner fails. In this case:

• The tag does not degrade entirely to plain text
• A forced inline child frame scans character-by-character for the real close token ()$$)
• Only the innermost unbalanced tag is affected; outer tags are preserved

$$bold(Hello $$italic(world)$$)$$
→ normal parse ✅

$$bold(Hello $$italic(world)$$ )$$
                               ^ extra space but brackets balance → normal ✅

$$bold(some text with ( inside)$$
                       ^ raw bracket → forced inline fallback → bold still closes correctly ✅

Tag opened but no close marker found before EOF:

• inline: content falls back to plain text, reports INLINE_NOT_CLOSED
• raw: content falls back to plain text, reports RAW_NOT_CLOSED
• block: content falls back to plain text, reports BLOCK_NOT_CLOSED
• shorthand: content falls back to plain text, reports SHORTHAND_NOT_CLOSED (and may co-occur with INLINE_NOT_CLOSED when outer full-form also remains unclosed)

$$bold(never closed
→ plain text: "$$bold(never closed"
→ error: INLINE_NOT_CLOSED

%end$$ / *end$$ not on its own line:

$$code(ts)%
const x = 1;  %end$$     ← not at line start
%end$$                     ← correct position

Reports RAW_CLOSE_MALFORMED / BLOCK_CLOSE_MALFORMED, content falls back to plain text.

)$$ appearing without a matching open:

Hello )$$ world
→ plain text: "Hello )$$ world"
→ error: UNEXPECTED_CLOSE