# comment-block-parser

> Block parser for markdown-magic - Parse comment blocks in markdown and other files

Latest version **1.6.4** (published 2026-06-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install comment-block-parser
pnpm add comment-block-parser
yarn add comment-block-parser
bun add comment-block-parser
```

Provides the command `comment-block-parser`.

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.6.4 |
| Published | 2026-06-23 |
| First published | 2025-06-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.0.0 |
| Dependencies | 3 |
| Unpacked size | 79.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 871 |
| Author | David Wells |
| Maintainers | davidwells |
| Keywords | markdown, parser, comment-blocks, regex, parsing |

## Links

- npm: https://www.npmjs.com/package/comment-block-parser
- Repository: https://github.com/DavidWells/markdown-magic
- Homepage: https://github.com/DavidWells/markdown-magic#readme
- Issues: https://github.com/DavidWells/markdown-magic/issues
- npm.io page: https://npm.io/package/comment-block-parser

## Dependencies (3)

- [mri](https://npm.io/package/mri.md) ^1.2.0
- [dedent](https://npm.io/package/dedent.md) ^1.6.0
- [oparser](https://npm.io/package/oparser.md) ^3.1.1

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.6.4 (latest) — 2026-06-23
- 1.6.1 — 2026-06-23
- 1.6.0 — 2026-05-30
- 1.5.4 — 2026-01-19
- 1.5.2 — 2026-01-11
- 1.5.1 — 2026-01-11
- 1.5.0 — 2026-01-11
- 1.4.0 — 2026-01-09
- 1.1.3 — 2026-01-08
- 1.1.2 — 2025-12-30
- 1.1.1 — 2025-11-12
- 1.1.0 — 2025-10-25
- 1.0.7 — 2025-06-24
- 1.0.6 — 2025-06-18
- 1.0.5 — 2025-06-18
- … 5 more at https://npm.io/package/comment-block-parser/versions

## README

# Comment Block Parser

A standalone block parser for parsing comment blocks in markdown and other file types. Extracted from [markdown-magic](https://github.com/DavidWells/markdown-magic).

## Installation

```bash
npm install comment-block-parser
```

## CLI

Parse comment blocks from the command line.

```bash
# Parse file (syntax auto-detected from extension)
comment-block-parser ./file.md
comment-block-parser ./src/index.js

# Parse with custom open/close words
comment-block-parser auto ./file.md                    # open=auto, close=/auto
comment-block-parser --open docs --close /docs ./file.md

# Pattern mode (--open without --close)
comment-block-parser --open MyComponent --syntax js ./file.js
comment-block-parser --open "CompA|CompB" --syntax js ./file.js

# Parse from stdin
cat file.md | comment-block-parser
echo "<!-- block foo -->content<!-- /block -->" | comment-block-parser

# Extract specific data with jq
cat file.md | comment-block-parser | jq '.blocks[0].options'
```

### CLI Options

```
--open             Opening pattern (literal word or regex pattern, default: block)
--close            Closing pattern (if omitted with regex open, uses /name backreference)
--no-close         Match single comments only (no close tag required)
--syntax           Comment syntax: md, js, jsx, yaml, sql, toml (auto-detected from file)
--parseType        Treat first arg after open keyword as transform type
--help, -h         Show help
--version, -v      Show version
```

## Example

The library works with a variety of [syntaxes](#supported-syntaxes).

As an example, it matches `html` comments like this

```html
<!-- matchWord blockType [...args] -->
contents inside
<!-- closeMatchWord -->
```

and returns

```js
{
  type: 'blockType',
  options: { ...parsedArgs },
  openValue: "<-- matchWord type [...args] -->",
  contentValue: 'contents inside',
  closeValue: '<!--/docs-->',
  rawArgs: "[...args]",
  blockValue: "<-- closeMatchWord -->"
}
```

## Usage

```js
const { parseBlocks, getBlockRegex } = require('comment-block-parser')

// Parse markdown comment blocks
const content = `
<!-- docs inlineExample foo={{ rad: 'bar' }}-->99<!--/docs-->

<!-- docs fooBar isCool -->
Stuff inside the block
<!--/docs-->
`

const result = parseBlocks(content, {
  open: 'docs',
  close: '/docs'
})

console.log(result.blocks)
/*
// Result
[
  {
    index: 1,
    type: 'inlineExample',
    options: { foo: { rad: 'bar' } },
    openValue: "<!-- docs inlineExample foo={{ rad: 'bar' }}-->",
    contentValue: '99',
    closeValue: '<!--/docs-->',
    rawArgs: "foo={{ rad: 'bar' }}",
    rawContent: '99',
    blockValue: "<!-- docs inlineExample foo={{ rad: 'bar' }}-->99<!--/docs-->"
  },
  {
    index: 2,
    type: 'fooBar',
    options: { isCool: true },
    openValue: '<!-- docs fooBar isCool -->\n',
    contentValue: 'Stuff inside the block',
    closeValue: '\n<!--/docs-->',
    rawArgs: 'isCool',
    rawContent: 'Stuff inside the block',
    blockValue: '<!-- docs fooBar isCool -->\nStuff inside the block\n<!--/docs-->'
  }
]
*/
```

## API

### `parseBlocks(content, options)`

Parse comment blocks from content string.

**Parameters:**
- `content` (string) - The content to parse
- `options` (object) - Parser options
  - `open` (string) - Opening word or regex pattern (default: 'block')
  - `close` (string) - Closing word or pattern. If omitted and `open` is regex-like or differs from default, uses pattern mode with backreference
  - `syntax` (string) - File syntax type (default: 'md')
  - `firstArgIsType` (boolean) - Treat first arg after open word as transform type (default: false)

**Returns:** Object with parsed blocks and regex patterns

### `getBlockRegex(options)`

Get regex patterns for matching blocks.

**Parameters:**
- `options` (object) - Regex options
  - `syntax` (string) - File syntax type
  - `openText` (string) - Opening delimiter text
  - `closeText` (string) - Closing delimiter text
  - `allowMissingTransforms` (boolean) - Allow missing transform keys

**Returns:** Object with `blockPattern`, `openPattern`, and `closePattern` regex objects

## Pattern Mode

Pattern mode allows matching component-style blocks where the open tag name is dynamic and the close tag must match via backreference.

**When pattern mode activates:**
1. `open` contains regex chars (`|`, `[`, `*`, `+`, etc.)
2. `close` not provided AND `open` differs from default 'block'

### Single Component

```js
const content = `/* MyComponent name="test" */
widget content here
/* /MyComponent */`

const result = parseBlocks(content, {
  syntax: 'js',
  open: 'MyComponent',  // no close = pattern mode
})

// result.blocks[0].type === 'MyComponent'
// result.blocks[0].options === { name: 'test' }
```

### Multiple Components (OR pattern)

```js
const content = `/* Header title="Hello" */
header content
/* /Header */

/* Footer year="2024" */
footer content
/* /Footer */`

const result = parseBlocks(content, {
  syntax: 'js',
  open: 'Header|Footer',  // matches either
})

// result.blocks[0].type === 'Header'
// result.blocks[1].type === 'Footer'
```

### Wildcard Patterns

```js
const content = `/* Gen_Users enabled -->
user list
/* /Gen_Users */

/* Gen_Products disabled */
product list
/* /Gen_Products */`

const result = parseBlocks(content, {
  syntax: 'js',
  open: 'Gen_[A-Za-z]+',
})

// Matches Gen_Users, Gen_Products, Gen_Anything, etc.
```

### Backreference Enforcement

Close tags must match the open tag exactly:

```js
/* ComponentA */
content
/* /ComponentB */  // DOES NOT MATCH - close doesn't match open
```

### Explicit Open and Close Patterns

When both `open` and `close` are provided as patterns:

```js
const result = parseBlocks(content, {
  syntax: 'js',
  open: 'START_[A-Z]',
  close: 'END_[A-Z]',
})
// Matches START_A...END_A, START_B...END_B, etc.
```

### RegExp Objects and Regex Literals

The `open` option accepts RegExp objects directly or regex literal strings (`/pattern/flags`):

```js
// RegExp object
const result = parseBlocks(content, {
  syntax: 'js',
  open: /CompA|CompB/,
})

// Regex literal string
const result = parseBlocks(content, {
  syntax: 'js',
  open: '/CompA|CompB/',
})

// With flags (parsed but flags not applied to block matching)
const result = parseBlocks(content, {
  syntax: 'js',
  open: '/Widget/i',
})
```

### CLI Pattern Mode

```bash
# Single component
comment-block-parser --open MyComponent --syntax js ./file.js

# OR pattern
comment-block-parser --open "CompA|CompB" --syntax js ./file.js

# Wildcard
comment-block-parser --open "Gen_[A-Za-z]+" --syntax js ./file.js

# Regex literal string
comment-block-parser --open "/CompA|CompB/" --syntax js ./file.js
```

## Single Comment Mode

Single comment mode matches individual comments without requiring a close tag. Use `close: false` to enable this mode.

```js
const content = `
<!-- config debug=true -->
some content here
<!-- config env="prod" -->
more content
`

const result = parseBlocks(content, {
  syntax: 'md',
  open: 'config',
  close: false  // single comment mode
})

// result.blocks.length === 2
// result.blocks[0].options === { debug: true }
// result.blocks[1].options === { env: 'prod' }
```

### With Pattern Matching

```js
const result = parseBlocks(content, {
  syntax: 'md',
  open: 'header|footer',  // match multiple comment types
  close: false
})
```

### CLI Single Comment Mode

This matches single comments without a closing comment.

E.g.

```html
<!-- config foo="bar" optionTwo=22 -->
```

```bash
# Match single comments with --no-close
comment-block-parser --no-close --open config ./file.md

# With match word
comment-block-parser --no-close widget ./file.md

# With pattern
comment-block-parser --no-close --open "header|footer" ./file.md
```

## Supported Syntaxes

- `md` / `markdown` / `html` - HTML comments (`<!-- -->`)
- `js` / `json` - JavaScript comments (`/* */`)
- `jsx` / `mdx` - JSX comments (`{/* */}`)
- `yml` / `yaml` - YAML comments (`##`)
- `sql` - SQL comments (`/* */` and `--`)
- `toml` - TOML comments (`#`)

## License

MIT

---
_Source: https://npm.io/package/comment-block-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._