mdast Comment Marker Parser

3.0.0 · active · verified Sun Apr 19

mdast-comment-marker is a utility for parsing structured markers from comments within an mdast (Markdown Abstract Syntax Tree) document. It's currently at version 3.0.0 and follows a release cadence tied to major ecosystem updates like Node.js versions and mdast/MDX specifications. This package differentiates itself by providing a robust way to extract 'processing instructions' or metadata embedded in HTML or MDX comments, such as `` or `/* zone foo */`. It handles various parameter types including booleans, numbers, and strings, making it suitable for tools like remark-lint or mdast-zone, which utilize these markers for configuration or content manipulation. It is ESM-only and requires Node.js 16 or later.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module ...mdast-comment-marker/index.js from ... not supported.
```
cause Attempting to use `require()` with an ESM-only package.

fix Change `const { commentMarker } = require('mdast-comment-marker');` to `import { commentMarker } from 'mdast-comment-marker';`.
```
TypeError: commentMarker is not a function
```
cause Incorrect import statement (e.g., default import instead of named) or attempting to use a CommonJS default import after the ESM transition.

fix Ensure you are using a named import: `import { commentMarker } from 'mdast-comment-marker';`

Warnings

breaking Version 3.0.0 changed the minimum Node.js requirement to Node.js 16 or higher.
Fix: Ensure your Node.js environment is at version 16 or newer. Update Node.js if necessary.
breaking The package transitioned to ESM only (ES Modules) starting from version 2.0.0. CommonJS `require()` is no longer supported.
Fix: Migrate your codebase to use ES Module `import` syntax. If in a CommonJS environment, consider a bundler or `import()` dynamic imports.
breaking Version 3.0.0 removed support for MDX 1 comments. If you were parsing MDX 1 specific comment syntax, this will no longer work.
Fix: Update your MDX tooling to MDX 2 or later, and ensure your comment syntax adheres to MDX 2 conventions.
breaking The `commentMarker` function now returns `undefined` instead of `null` when no valid marker is found in the input node.
Fix: Update your code to check for `undefined` instead of `null` when evaluating the return value of `commentMarker`.
breaking Version 3.0.0 updated its dependency on `@types/mdast`. You might need to update `@types/mdast` in your project to ensure compatibility.
Fix: Run `npm install @types/mdast@latest` or `yarn add @types/mdast@latest` to update your type definitions.
breaking Version 3.0.0 started using the `exports` field in `package.json`. This can break direct imports of non-exported (private) API paths.
Fix: Always use the public API paths as documented. Avoid importing from deep paths within the package unless explicitly exported.

Install

npm install mdast-comment-marker npm
yarn add mdast-comment-marker yarn
pnpm add mdast-comment-marker pnpm

Imports

commentMarker
wrong:
```
const { commentMarker } = require('mdast-comment-marker')
```
correct:
```
import { commentMarker } from 'mdast-comment-marker'
```
mdast-comment-marker is an ESM-only package since v2.0.0, requiring `import` syntax.
Marker
```
import type { Marker } from 'mdast-comment-marker'
```
Type import for the `Marker` interface, representing the parsed comment structure.
MarkerParameters
```
import type { MarkerParameters } from 'mdast-comment-marker'
```
Type import for the `MarkerParameters` interface, detailing the parsed key-value attributes.

Quickstart

This quickstart demonstrates how to use `commentMarker` to parse different types of comment nodes (HTML and MDX) into structured marker objects, including handling various parameter types.

import { commentMarker } from 'mdast-comment-marker';

// Example 1: Basic HTML comment marker
console.log(commentMarker({ type: 'html', value: '<!--foo-->' }));

// Example 2: HTML comment marker with various parameters
console.log(commentMarker({
  type: 'html',
  value: '<!--foo bar baz=12.4 qux="test test" quux=\'false\'-->'
}));

// Example 3: MDX Flow Expression comment marker
console.log(commentMarker({
  type: 'mdxFlowExpression',
  value: '/* lint disable heading-style */'
}));

// Example 4: A comment that does not parse as a marker
console.log(commentMarker({ type: 'html', value: '<!doctype html>' }));

view raw JSON →