Skip to content

v2.0.0

Choose a tag to compare

View all tags
@kitschpatrol kitschpatrol released this 01 Apr 20:51
· 22 commits to main since this release
v2.0.0
2d7f068

Commits

  • 2d7f068 Release: 2.0.0
  • 8dd9dc4 Update shared-config to fix knip lint error on windows.
  • 71caf8f Matrix CI.
  • fc28fa2 Quiet logging.
  • c58b93f Release: 2.0.0-preview.4
  • f250f53 Move rules back to a field on options for consistency with other Remark plugins.
  • 070c4c3 Update readme.
  • e1df73a Release: 2.0.0-preview.3
  • 7976013 In compound rules, warnings instead of errors on failed sub-rules.
  • b8a5ac1 Release: 2.0.0-preview.2
  • c2d17ee Feature: Pass the file path and any parsed frontmatter alongside MDAST tree to rules via new context argument.
  • 364da65 Remove legacy check logic from rule invocation.
  • 5930154 Release: 2.0.0-preview.1
  • 014d55f Prep for preview release.
  • 2313f33 Add tests.
  • 6a06e46 Breaking: Move deepMergeDefined to mdat.
  • 0afb639 Migrate to lognow.
  • b633825 Breaking: Remove validation feature and mdat-util-mdat-check, merge basic keyword checks into expand step.
  • 1136788 Upgrade from Zod 3 to 4.
  • 00083dd Breaking: Rename applicationOrder option to just order. Note collision with 1.0 option key.
  • 8055579 Breaking: Limit valid argument syntax. Feature: Support for primitive arguments.
  • 70bc76c Breaking: Remove meta comment feature.
  • 84777a5 Feature: Ignore comment-prefixed comments.
  • 6222f44 Breaking: Remove keyword prefix feature. No prefix support.
  • 968f4cc Breaking: Remove closing tag cusotmization feature. Hard coding /.
  • f0e9e8f Breaking: Remove "required" validation feature.
  • cec60ca Breaking: Remove order validation feature.

Migrating from 1.x to 2.x

Version 2.0 simplifies and solidifies the API by removing several configuration options and validation features that added complexity without sufficient benefit. The core expansion behavior is unchanged — the plugin still matches HTML comments to rules and expands them — but the way you configure it has changed.

Simplified options

In 1.x, the plugin accepted an options object with multiple fields to customize parsing and generation:

// 1.x
remark().use(remarkMdat, {
  rules: { title: () => '# My Title' },
  addMetaComment: true,
  closingPrefix: '/',
  keywordPrefix: 'mm-',
  metaCommentIdentifier: '+',
})

In 2.x, the configuration options for parsing and generation have been removed. The Options object now contains only a rules field:

// 2.x
remark().use(remarkMdat, {
  rules: { title: () => '# My Title' },
})

If you were importing MdatOptions, MdatExpandOptions, MdatCheckOptions, or MdatCleanOptions, replace them with Options (for plugin configuration) or Rules (for the rules record).

Removed options

The following plugin options have been removed entirely:

Removed option Migration
addMetaComment Remove. Auto-generated warning comments are no longer supported.
metaCommentIdentifier Remove. The <!--+ ... +--> meta comment syntax is gone.
closingPrefix Remove. The closing prefix is now always / (e.g. <!-- /keyword -->).
keywordPrefix Remove. Keyword prefixing / namespacing is no longer supported.

Removed rule properties

Removed property Migration
required Remove. All rules are treated equally. Missing comments produce a warning instead of an error.
order Remove. The 1.x order property enforced comment position in the document. In 2.x, order controls processing priority only (default: 0).

Changed rule properties

Changed property Migration
applicationOrder Change to order.

Removed validation utility

The mdast-util-mdat-check utility and its export mdatCheck have been removed. Validation logic (missing rules, empty content, rule errors) is now handled inline during expansion by mdatExpand, which reports issues as VFile messages. Use reporterMdat to format and display these messages.

Rule function signature change

In 1.x, rule content functions received the mdast tree directly as the second argument:

// 1.x
const rules = {
  toc: (_options, tree) => generateTocFromTree(tree),
}

In 2.x, the second argument is a RuleContext object containing the tree, parsed frontmatter, and file path:

// 2.x
const rules = {
  toc: (_options, context) => generateTocFromTree(context.tree),
}

Stricter argument syntax

In 1.x, the argument parser was very permissive — parentheses were optional, bare key-value pairs were auto-wrapped in braces, and space-separated arguments worked:

<!-- greeting name: "Alice" -->
<!-- greeting {name: "Alice"} -->
<!-- greeting({name: "Alice"}) -->

In 2.x, arguments must use function-call syntax with parentheses. The content inside the parentheses is parsed as JSON5:

<!-- greeting({name: 'Alice'}) -->

Bare or space-separated arguments like <!-- greeting name: "Alice" --> will no longer be parsed — the extra text after the keyword is ignored and the rule receives an empty {} options object.

As a trade-off for the stricter syntax, primitive values are now supported as arguments: <!-- repeat(3) -->, <!-- show("hello") -->.

Comment-style comments are ignored

HTML comments using code-style prefixes (<!-- // ... -->, <!-- # ... -->, <!-- /* ... */ -->) are now ignored by the parser, so you can use them for regular comments alongside mdat keywords without triggering warnings. This replaces 1.x parser configuration options like keywordPrefix.

Compound rule error handling

In 1.x, a failing sub-rule in a compound rule (array of rules) caused the entire expansion to fail. In 2.x, individual sub-rule failures are reported as warnings and skipped — the expansion only fails if every sub-rule fails.

Removed export: deepMergeDefined

The deepMergeDefined utility has been moved to the mdat package. If you were importing it from remark-mdat, import it from mdat instead.

Full Changelog: v1.2.5...v2.0.0

Assets 4
Loading