WORK-640
ID:WORK-640Status:ready

Upgrade Markdoc from 0.4.0 to 0.5.10

Every package pins "@markdoc/markdoc": "0.4.0" exactly: packages/runes, transform, content, svelte, editor, cli, language-server, plugins/places, site and plan-site. 0.4.0 was released in December 2023; 0.5.10 in September 2026, eleven releases later. Nothing in the plan or the git history records why the version is pinned. SPEC-123 and WORK-556 only call it "the pinned 0.4.0".

The 0.4.0 → 0.5.10 source was read, not run. The changes that matter here:

Worth having:

Priority:mediumComplexity:moderateMilestone:v0.42.0Source:SPEC-170
claude/v0-42-0-planning-ata7nd View source

Criteria completion

Criteria completion: 0 of 8 (0%) checked; tracking started on Oct 22, no incremental history yet0%25%50%75%100%Oct 22Oct 28

Tracking started Oct 22 — check back for trends.

Relationships

Implements 1
Related 7
Branches 5
claude/v0-42-0-planning-ata7nd current ready
claude/v0-42-0-planning-t31f5e donemain donechangeset-release/main readyclaude/site-changelog-readability-k4p902 readyclaude/v041-plan-runes-keep-content ready
History 2
  1. abc833f
    Created (ready)by bjornolofandersson
  2. 7d3951e
    Content editedby Claude
    WORK-640: upgrade Markdoc from 0.4.0 to 0.5.10

Acceptance Criteria

  • Every @markdoc/markdoc pin is 0.5.10, and the lockfile is regenerated with npm, not edited by hand
  • The AST of every tracked .md file is compared before and after the upgrade; every difference is listed in the resolution and explained
  • npm test, npx refrakt contracts --check (both contract copies) and npm run seo:baseline:check pass, or every change they report is explained as a fix
  • New validation findings from the stricter if and table checks are listed, and each is fixed in content or recorded as a breaking change for third-party sites
  • A test asserts that a schema validator's error with its own location reaches refrakt validate with that location, not the whole node's range
  • A test round-trips an image src with two parentheses and a blockquote with two paragraphs through Markdoc.format unchanged
  • The changeset describes the behaviour changes for authors (the if condition check, table errors)
  • The reason for pinning an exact Markdoc version is written down (in RELEASING.md or a short ADR), so the next upgrade knows what to check

Approach

  1. Upgrade the pins together in one change; mixed Markdoc versions across packages would give two parsers.
  2. Before installing, capture the AST of every tracked .md file with 0.4.0, then compare after. This is the same comparison SPEC-170 used for allowIndentation.
  3. Land this before SPEC-170's shared parse(), so it is built once, on the current version.

References

  • SPEC-170: indentation; this upgrade lands first.
  • ADR-034: source locations, which the validator change improves.
  • WORK-556: Markdoc validation routed into the pipeline.
  • SPEC-123: an earlier parse behaviour confirmed against 0.4.0, to re-check.
  • SPEC-145 D30: expansion-time if evaluation should match Markdoc's own condition rules, including the new type check.