Markup · .not & .md

输入与状态

lexer 处理 Unicode 字符，parser 处理 token。token 保存 kind 和 UTF-8 源码范围，文本按范围从原始源码取得。空格、tab、换行与注释作为 trivia 保留在 CST 中；每条解析规则明确决定如何消费它们。

调用参数和注解的圆括号按深度维护字面量状态；调用 body 使用 Markup 正文规则。lexer 独立产生完整 token 流，parser 将失败的调用入口返回文字时仍使用这份 token 流。

lex Whitespace -> [` ` U+0009]+;
lex Newline -> (U+000D U+000A) | U+000A | U+000D;
lex Eq -> `=`+;
lex Backtick -> U+0060+;
lex Ident -> first:UnicodeChar @{ alphabetic(first) or first == "_" }
              (c:UnicodeChar @{ alphanumeric(c) or c in {"_", "-"} })*;

UnicodeChar 是一个 Unicode scalar；alphabetic / alphanumeric 使用 Rust 字符的 Unicode 字母 / 字母数字判断。Eq 和 Backtick 描述 Markup 正文中的连续标记；Ident 用于调用路径与字面量状态。Code 复用 Ident，但箭头的优先级见 Code 词法。String 与 Number 见 Types，Escape 见 Builtin 的 text 小节。

WS、NL、LINE_COMMENT、BLOCK_COMMENT、EQ、BACKTICK、IDENT、STR、NUMBER、TEXT、ESCAPE 分别表示对应 token kind。scanner 中的 CamelCase 名与大写别名表示同一 kind，例如 LBracket 与 LBRACKET。DOT 是整个 . token；其他标点别名在相应词法状态下表示单字符 token。连续 = 与反引号各组成一个正文 token，-、+、* 逐字符组成 token。

普通正文中的引号、冒号与逗号属于 Text；进入字面量状态后才按 String、Colon、Comma 等规则识别。只有已形成 STR 的字符串才屏蔽其中的括号。

注释

下面的词法 scanner 使用 UTF-8 字节偏移；ASCII 注释标记占两个字节。它们返回扫描结果，由 lexer 据此生成 token。

lex scanner LineComment(mode) -> { end } | Miss {
  start = cursor
  若 source[start..] 不以 "//" 开头，返回 Miss
  若 mode == Markup 且 start 前一个源码字符为 ":"，返回 Miss
  end = start 之后首个 LF 的字节位置；没有 LF 时为 source.len
  若 source[end - 1] == CR，end -= 1
  返回 { end }
}

lex scanner BlockComment -> { end, closed } | Miss {
  若 source[cursor..] 不以 "/*" 开头，返回 Miss
  p = cursor + 2；depth = 1
  循环至 source.len：
    "/*"：depth += 1；p += 2
    "*/"：depth -= 1；p += 2
           若 depth == 0，返回 { end: p, closed: true }
    其他：p 前进一个字节
  返回 { end: source.len, closed: false }
}

块注释可以嵌套；未闭合的块注释仍形成 trivia token，parser 消费它时产生 Syntax 诊断。行注释终止于 LF 或文件末尾，终点前紧邻的 CR 留给 Newline；单独的 CR 不终止行注释。

正文中的 // 仅在紧随冒号时享有 URL 豁免，因此 https://example 可作为普通文字。调用参数、注解 payload 与 Code 的字面量扫描不使用此豁免，URL 参数应写成 String。单独的斜杠属于 Text。

共用 token 规则

syntax Trivia -> WS | NL | LINE_COMMENT | BLOCK_COMMENT;
syntax TokenKind(k) -> t:ANY @{ t.kind == k };
syntax End(ctx) -> &NL | @{ limit(cursor, ctx) };
syntax BlankLine -> WS? NL;
syntax ItemBody(ctx) -> BlockRun(ctx, Item);

ANY 消费一个 token。End 只判断当前位置是否为 NL 或有效区间末尾，不消费输入；EOF 表示有效区间末尾的观察结果，lexer 不额外生成 EOF token。

位置和容器

token 位置与源码字节位置分别使用。kind(p) 在 p 达到 limit 时返回 EOF；column(p) 根据该 token 的源码起点计算列数，普通 Unicode scalar 计一列，tab 到下一个四列边界。行首判断使用源码中最近的 LF / CR，而非只查找独立的 NL token。

limit(p, ctx) = p >= ctx.limit
body_close(p, ctx) = ctx.in_body and kind(p) == RBracket
line_start(p) = 最近 LF / CR 之后至 token p 起点的源码仅含空格或 tab
block_start(p, ctx) =
  p == ctx.body_start
  or line_start(p) and (
    column(p) == 0
    or ctx.block_indent > 0 and column(p) >= ctx.block_indent
  )
can_open(p, ctx) = kind(p + 1) not in {EOF, Whitespace, Newline}
can_close(p, ctx) = p > 0 and kind(p - 1) not in {EOF, Whitespace, Newline}
always_true = 恒真谓词
always_false = 恒假谓词

不同边界承担不同职责：

调用 body 设置 in_body，继承外层 limit；列表项临时收窄 limit，并设置正文缩进和 body_start。表格单元格临时收窄 limit、设置 in_body=false，使单元格中的独立 RBracket 可以作为文字。离开容器后恢复外层上下文。

换行是否结束块

predicate block_end(p, ctx) {
  要求 kind(p) == Newline
  q = p + 1；跳过从 q 开始的 Whitespace
  i = 跳过前导空白得到的缩进列数
  若 kind(q) in {EOF, Newline} 或 i < ctx.block_indent，返回 true
  若 table_start(q, ctx)，返回 true
  若非 block_start(q, ctx)，返回 false
  按 kind(q) 判断：
    Eq：kind(q + 1) == Whitespace
    Backtick：当前 run 长度至少 3
    Minus / Plus：kind(q + 1) == Whitespace，或 Divider 前缀成立
    At：true
    其他：false
}

table_start 与 Divider 前缀由 Builtin 的 table / divider 小节定义。block_end 是纯判断；At 分支只判断下一行以 At 开始，payload 的合法性留给后续解析。

正常行内序列中的单 NL 是软换行；空行、块起点和显式反斜杠换行结束相应序列。正文空白与换行的降糖见 Builtin 的 paragraph 小节。

块序列

BlockRun 按下列顺序循环分派，每轮先检查 limit 与 body_close。Document 在文件末尾结束；Body 和 Item 还会在有效的 RBracket 处结束。已消费的 trivia 保留在所属容器的 CST 中。

syntax algorithm BlockRun(ctx, container) {
  循环至 limit，或 container != Document 且 body_close(cursor, ctx)：
    container == Item 且当前为 WS / NL / LINE_COMMENT / BLOCK_COMMENT：消耗一个 token
    NL：消耗一个 token
    EQ 且下一 token 为 WS：Heading
    BACKTICK 且 run 长度至少 3：RawBlock
    Divider 前缀成立：Divider
    MINUS / PLUS 且下一 token 为 WS：List
    table_start(cursor, ctx)：Table
    WS 且后续仅为 WS，直至 NL 或 EOF：消耗 WS
    WS 且 block_indent > 0 且 container == Body：消耗 WS
    LINE_COMMENT / BLOCK_COMMENT：消耗一个 token
    AT 且 block_annotation(cursor, ctx)：BlockAnnotation
    BACKSLASH NL：ExplicitBreak
    其他：InlineRun(ctx, block_end, None)
}

container 为 Document、Body 或 Item；Heading、RawBlock、Divider、List、Table 与 ExplicitBreak 的具体规则见 Builtin。Item 消费正文缩进；Document 保留非空行的前导空白并交给行内分派。块路径产生 BlockAnnotation，行内路径产生 Annotation；两者共用 Annotation AST 视图，lowering 按节点 kind 记录 side annotation。

块分派使用当前位置的前缀。Heading、RawBlock、List 的入口没有统一的 line_start 检查；Divider、Table 及换行后的块边界判断使用 block_start。通常独占行的块标记位于列 0，但不能把“所有块标记必须在源码列 0”作为 parser 的统一条件，例如 /* comment */= Title 仍可在文档入口形成 Heading。

行内序列

InlineRun 只在当前位置为 NL 时调用 stop；active 表示包围它的行内结构的闭合约定。

syntax algorithm InlineRun(ctx, stop, active) {
  循环：
    limit：停止
    NL 且 stop(cursor, ctx)：停止
    NL：消耗一个 token
    body_close(cursor, ctx)：停止
    active_closes(active, cursor, ctx)：停止
    BACKSLASH NL：停止
    BACKTICK：RawInline
    STAR / UNDERSCORE / TILDE：Strong / Emph / Strike
    DOLLAR：Math
    BANG LBRACKET：Embed
    LBRACKET LBRACKET：WikiLink
    LBRACKET：Link
    HASH：CodeCall
    AT LPAREN 或 AT BANG LPAREN：Annotation
    其他：消耗一个原始 token
}

active_closes(None, p, ctx) = false
active_closes(Flanked(k), p, ctx) = kind(p) == k and can_close(p, ctx)
active_closes(Single(k), p, ctx) = kind(p) == k
active_closes(Pair(k), p, ctx) = kind(p) == k and kind(p + 1) == k

函数的返回级别不参与 syntax 分派。名称和签名在 Resolve 确定，Resolve 按类型校验内容片段，Shape 归组 section。未形成语法构造的原始 token 由 text 降糖；普通行内 At 只有紧随合法注解起始前缀时才进入 Annotation。

合法形式

syntax CodeCall(ctx) ->
  `#` name:Path args:Args(ctx) body:CallBody(ctx)?
  | `#` name:Path body:CallBody(ctx)
  | `#` name:Path;
syntax Path -> segment:IDENT (DOT segment:IDENT)*;
syntax Args(ctx) ->
  LPAREN Trivia* (Argument (Trivia* COMMA Trivia* Argument)* Trivia* COMMA?)?
  Trivia* RPAREN;
syntax Argument -> key:ArgKey COLON Trivia* value:Value | value:Value;

Path、Args、CallBody 的边界必须紧邻，路径中的段与 . 也必须紧邻。#name(args) 和 #name[body] 是具名调用，#node[body] 是显式透明调用。裸 #name 解析为引用；独立 Markup 在检查时拒绝引用插值，Code 字面量可拼接内容值。匿名调用不属于语言入口。

Value 和 ArgKey 由 Types 定义。具名参数的冒号紧邻 key，允许参数尾逗号；lowering 按源码顺序保存位置与具名参数的表达式，由 Resolve 按签名绑定为 fields。重复具名 key 产生诊断，恢复时后者覆盖。内容通过唯一的调用 body 挂载为 children；参数中出现 [body] 可被 parser 保留供诊断，BlockContent 参数的限制见 Types。

CST 将简单名称保存在 Path 节点，成员访问以嵌套 MemberExpr 保存；CodeCall.callee 返回目标表达式。parser 保留任意段数；Context 沿 import 绑定解析到函数。CodeCall 是 CST / AST 名称，其源码语法属于 Markup。

平衡探测

Balanced 在当前位置的开括号处探测，仅对指定的一种括号计数。cross_blocks 决定是否允许越过 block_end；外层 limit 始终有效。

scanner Balanced(open_kind, close_kind, cross_blocks; ctx)
  -> { end, status, close } | Miss {
  若 kind(cursor) != open_kind，返回 Miss
  p = cursor；depth = 0
  循环至 ctx.limit：
    若非 cross_blocks 且 kind(p) == Newline 且 block_end(p, ctx)，
      返回 { end: p, status: BlockEnd, close: none }
    若 cross_blocks 且 probe OpaqueClose(p, ctx) 成功，
      p = 该结果的 close + 1；继续
    若 kind(p) == open_kind，depth += 1
    若 kind(p) == close_kind：
      depth -= 1
      若 depth == 0，返回 { end: p + 1, status: Closed, close: p }
    p += 1
  返回 { end: ctx.limit, status: Unclosed, close: none }
}

这些是纯探测的结果，调用方按 status 决定消费和恢复。STR、注释和 Escape 中的括号没有独立 token，不参与计数；正文里的普通引号本身不会屏蔽括号。

OpaqueClose 导入 Builtin 的 link 小节定义，只跳过完整的行内 raw / math payload。原生 fenced RawBlock 使用自己的块解析规则；外层平衡探测不会把跨行 fence 当成同一种不透明片段。

入口、body 与恢复

调用入口依次完成以下探测：

1. 在 # 后探测完整 Path；路径最后的 . 缺少名称段时，前缀失败。

2. 若紧邻 LPAREN，以 cross_blocks=false 探测 Args；仅 Closed 继续。

3. 若紧邻 LBRACKET，以 cross_blocks=true 探测 body，并保留状态。

4. 名称后接完整 Args 或完整 body 时形成 CodeCall；只有 Path 时形成引用。

CallBody 的解析流程为：

syntax algorithm CallBody(ctx) {
  open = cursor
  frame = probe Balanced(LBracket, RBracket, true; ctx)
  若 frame == Miss 或 frame.status != Closed，返回 Miss
  根据 Types 的 flank 规则确定 body flavor
  若 flavor 为行内，检查 open + 1 至 frame.close 内的换行
  消耗 LBRACKET，临时设置 ctx.in_body=true，继承 ctx.limit
  块 flavor：BlockRun(ctx, Body)
  行内 flavor：InlineRun(ctx, always_false, Single(RBracket))
  恢复外层 in_body，在正文停止的位置消费收尾 token
}

flavor 来自括号两端内侧的空白，与内容函数的返回类型分别确定。行内 body 的换行若使 block_end 成立，parser 产生 Syntax 诊断（inline content cannot contain a blank line），并继续以行内规则解析；该检查还会命中标题等块起点。

frame.close 用于判断 flavor 和检查换行；它不通过 within 设置正文的新 limit。正文停止条件来自 in_body、active、显式反斜杠换行及外层容器，收尾消费发生在实际停止位置。

失败入口返回的是首 token，余下范围仍可能形成其他语法构造。解析消费继续保留原始源码，trivia 自身的诊断也照常产生。

解析边界

MarkdownFrontend 独立解析 .md、.markdown、.notmd 与 .nmd，使用 rushdown AST 并输出共享 Expr。Builtin 中的 MD.* 表示 AST 模式，描述到内容函数的映射。前端接口、注册和源码位置映射见 文档前端。

Markdown 扩展支持 @(dict)、@!(dict)、#name(args)[body]、包限定调用与透明 #node[body]。[正文] 是行内槽；两端内侧均留白的 [ 正文 ] 是块槽，可以包含空行、标题、列表、引用和代码块。位置映射将移除容器前缀后的局部位置还原为原始源码范围。

Wiki 链接

Markdown 与原生 Markup 均支持 [[target]] 和 [[target|显示文本]]，target 按普通链接路径解析。target 去掉首尾空白，其余文字原样保留；显示文本按 Markdown 行内规则解析，省略时显示 target。

Wiki 链接不能跨行，未闭合的括号保留为普通文字；代码与数学 payload 内不识别链接，转义的开括号不触发 Wiki 链接。GFM 表格仍以未转义的管道符分列，带显示文本的链接在单元格中写作 [[page.not\|显示文本]]。

调用与注解的探测

Markdown 扩展扫描调用头时用共用字面量 lexer 屏蔽 String / 注释中的圆括号；扫描 body 时按 Markdown 的转义、反引号代码片段、代码围栏与行内数学片段屏蔽方括号。它使用 Markdown 容器提供的源码范围，原生 Balanced / BlockRun 的 token 上下文只用于原生 Markup。

独占行的注解产生块级 side annotation，紧邻元素的注解产生行内 side annotation；两者都在 Shape 之后按源码位置挂载（见“注解”一节）。模块注解仅允许位于文档开头；标题前的注解在 Materialize 时落到它开启的 Section。扩展节点未闭合时保留原始文字并产生 Syntax 诊断，非法字面量产生对应的源码诊断。

# 标题 仍为 Markdown 标题，普通 #tag 和邮件地址仍为文字。参数与属性字符串保持不透明；代码、数学 payload 和转义中的注解 / 调用不执行。

文字与输出

1. 普通文字、链接地址与 embed 字段的标点转义和字符引用只解码一次；raw / math 不解码。

2. decode_once 从左到右读取原输入，输出不再参与解码；decode_optional 对 none 保留 none，否则调用 decode_once。

3. 单换行、双空格换行、空行与显式分段的共享行为见 Builtin 的 paragraph；列表编号和 lazy continuation 见 list / item。

4. 行内 HTML 标签忽略并保留周围普通文字，HTML 块整体跳过。