Files
marqdo-cli/spec/markdown-profile.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

6.2 KiB

Marqdo Markdown Profile v1

Status: frozen (marqdo.md.v1); product baseline 3.0.0-beta.1. Changes require an ADR, updated goldens and a profile id bump.

Profile id: marqdo.md.v1 Parser: comrak =1.0.0, default-features = false CommonMark baseline: 0.31.2

Semantic mapping notice (RFC-LANG-0002). The Markdown profile is unchanged by the breaking syntax revision: the same CommonMark/GFM AST and byte spans are produced. What changed is the separate Markdown→program mapping in spec/mapping.md (heading @exec/@knowledge modes, unified Strong/Emph/inline Code payloads, keyword control flow). Do not bump this profile id for a semantic-mapping-only change.

1. Why a profile

Markdown is the syntax of the language. Any parser behaviour that can change the AST can change program meaning, so the parser version and every extension flag are part of the language version, not an implementation detail. Marqdo never maintains a second Markdown parser and never decides semantics from raw text with regular expressions.

2. Frozen parser options

Enabled extensions:

Option Value Consequence
extension.table true GFM tables produce table/table_row/table_cell nodes.
extension.strikethrough true ~~x~~ produces strikethrough. Strikethrough is never an executable carrier and its content is inert in both modes.
extension.tasklist true - [x]/- [ ] items carry a checkbox flag on the item node.
extension.math_dollars true $...$ and inline $$...$$ produce math; standalone $$ fences with math_dollars_block produce math_block.
extension.math_dollars_block true Multi-line $$ display math is a block node.
extension.front_matter_delimiter Some("---") YAML front matter is recognised only at the start of the document.

Disabled (must stay false): autolink, footnotes, inline_footnotes, description_lists, multiline_block_quotes, alerts, ofm_callouts, superscript, subscript, underline, highlight, insert, spoiler, subtext, shortcodes, wikilinks_*, grid_table, greentext, ofm_*, block_directive, header_attributes, fenced_code_attributes, inline_code_attributes, link_attributes, cjk_friendly_emphasis, phoenix_heex, tasklist_in_table, relaxed_tasklist_matching, relaxed_autolinks; parse options smart, ignore_setext, escaped_char_spans stay false.

The unit test profile::tests::profile_options_are_frozen asserts this table.

3. Byte spans and source maps

Every AST node carries a half-open byte span [start, end) into the original UTF-8 file. Spans are produced from the parser's line/column positions (byte columns) with a line index, so multi-byte characters are handled correctly.

  • # 数学 has span covering exactly # 数学 (8 bytes).
  • A UTF-8 BOM is tolerated at offset 0. The BOM is stripped before parsing and all spans are re-based onto the original file (the first character after the BOM starts at byte 3 in that case).
  • Spans of container nodes cover their full source region; inline spans cover the inline source, not the surrounding markers.
  • The source map is used for diagnostics and IDE navigation only. No semantics is derived from the source text.

4. Front matter

YAML front matter is recognised only when the parser reports a front_matter node, i.e. the document starts with --- (after an optional BOM) and a closing --- or ... line exists. A --- later in the document is a thematic break or a Setext heading underline, never front matter.

The parser node keeps the raw delimiters; Marqdo extracts the YAML body and parses it exactly once with serde_yaml. Supported semantics:

  • import: mapping from local alias to module address (see references.md). Imports are explicit; nothing is inferred.
  • Any other key is metadata for tools and is ignored by the interpreter.
  • Invalid YAML is a diagnostic (frontmatter.invalid), never silently dropped.
  • Front matter never executes.

5. AST view

marqdo inspect --ast --json prints this tree:

{
  "kind": "document",
  "span": {"start": 0, "end": 20},
  "children": [
    {"kind": "heading", "level": 2, "setext": false, "span": {"start": 0, "end": 7},
     "children": [{"kind": "text", "span": {"start": 3, "end": 7}, "literal": "阶乘"}]}
  ]
}

Rules:

  • Node kinds mirror the profile; task list items are item nodes with "task": true|false so that node type still determines list structure. GFM task items replace the parser's item node; the profile normalises them back to item plus the checkbox flag.
  • Literal payloads are kept on inert leaves: text, code, code_block, math, math_block, html_block, html_inline, front_matter, and the raw payload of unmodelled nodes.
  • link/image embed url and title; heading embeds level and setext; list embeds ordered, optional start and tight; table embeds column alignments; table_row embeds header; inline code embeds ticks (delimiter length) so payload offsets can be mapped back to exact source bytes (a code span's source span includes its backticks).
  • Unmodelled parser nodes are preserved as {"kind":"other","tag":"..."} with their children and raw literal. They are inert for the language.
  • Attribute order in JSON is fixed by the serializer and goldens are regenerated only with an explicit update command.

6. Structural equivalence

Program semantics depend on node type and position, not on source spelling:

  • **x** and __x__ are both strong and behave identically.
  • *x* and _x_ are both emph.
  • ## name and a Setext level-2 heading are both heading with level: 2. (setext is recorded for inspection only.)
  • Ordered list delimiters 1. / 1) and bullet markers -/*/+ produce the same list/item structure; role does not depend on the marker.
  • Tight versus loose lists (tight) only affects rendering; it does not change program semantics.

7. Contract with readers

A .mq.md file is rendered normally by any CommonMark/GFM renderer (math needs a math extension). Rendering never triggers execution. Code fences and math remain inert Code/Formula values until an explicit call.