Block parser for markdown-magic - Parse comment blocks in markdown and other files
npm install comment-block-parserA standalone block parser for parsing comment blocks in markdown and other file types. Extracted from markdown-magic.
``bash`
npm install comment-block-parser
Parse comment blocks from the command line.
`bashParse file (syntax auto-detected from extension)
comment-block-parser ./file.md
comment-block-parser ./src/index.js
$3
`
--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.
As an example, it matches
html comments like this`html
contents inside
`and returns
`js
{
type: 'blockType',
options: { ...parsedArgs },
openValue: "<-- matchWord type [...args] -->",
contentValue: 'contents inside',
closeValue: '',
rawArgs: "[...args]",
blockValue: "<-- closeMatchWord -->"
}
`Usage
`js
const { parseBlocks, getBlockRegex } = require('comment-block-parser')// Parse markdown comment blocks
const content =
Stuff inside the block
const result = parseBlocks(content, {
open: 'docs',
close: '/docs'
})
console.log(result.blocks)
/*
// Result
[
{
index: 1,
type: 'inlineExample',
options: { foo: { rad: 'bar' } },
openValue: "",
contentValue: '99',
closeValue: '',
rawArgs: "foo={{ rad: 'bar' }}",
rawContent: '99',
blockValue: "99"
},
{
index: 2,
type: 'fooBar',
options: { isCool: true },
openValue: '\n',
contentValue: 'Stuff inside the block',
closeValue: '\n',
rawArgs: 'isCool',
rawContent: 'Stuff inside the block',
blockValue: '\nStuff inside the block\n'
}
]
*/
`
Parse comment blocks from content string.
Parameters:
- content (string) - The content to parseoptions
- (object) - Parser optionsopen
- (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 backreferencesyntax
- (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
Get regex patterns for matching blocks.
Parameters:
- options (object) - Regex optionssyntax
- (string) - File syntax typeopenText
- (string) - Opening delimiter textcloseText
- (string) - Closing delimiter textallowMissingTransforms
- (boolean) - Allow missing transform keys
Returns: Object with blockPattern, openPattern, and closePattern regex objects
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.)close
2. not provided AND open differs from default 'block'
`js/ MyComponent name="test" /
const content =
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' }
`
`js/ Header title="Hello" /
const content =
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'
`
`js/* Gen_Users enabled -->
const content =
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.
`
Close tags must match the open tag exactly:
`js`
/ ComponentA /
content
/ /ComponentB / // DOES NOT MATCH - close doesn't match open
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.
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',
})
`
`bashSingle component
comment-block-parser --open MyComponent --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 = 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' }
`$3
`js
const result = parseBlocks(content, {
syntax: 'md',
open: 'header|footer', // match multiple comment types
close: false
})
`$3
This matches single comments without a closing comment.
E.g.
`html
``bash
Match single comments with --no-close
comment-block-parser --no-close --open config ./file.mdWith match word
comment-block-parser --no-close widget ./file.mdWith 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 (#`)MIT