remark-parse
Advanced tools
The remark-parse package is a plugin for the Remark processor that parses Markdown content into a syntax tree. It is part of the unified ecosystem, which provides a way to parse, transform, and stringify content using abstract syntax trees (ASTs).
Parsing Markdown
This feature allows you to parse Markdown content and transform it into an abstract syntax tree (AST). The code sample demonstrates how to use remark-parse with the remark library to parse a simple Markdown string.
const remark = require('remark');
const parse = require('remark-parse');
remark().use(parse).process('# Hello world!', function(err, file) {
if (err) throw err;
console.log(file);
});Extensible Markdown Parsing
remark-parse can be extended with plugins to handle custom Markdown syntax. In this example, the 'remark-math' plugin is used to parse mathematical expressions within the Markdown content.
const remark = require('remark');
const parse = require('remark-parse');
const math = require('remark-math');
remark().use(parse).use(math).process('Euler's identity: $e^{i\pi} + 1 = 0$', function(err, file) {
if (err) throw err;
console.log(file);
});markdown-it is a Markdown parser with a similar goal to remark-parse, but it is implemented differently. It is often used for its speed and extensibility with plugins, and it can output HTML directly instead of an AST.
marked is another Markdown parser that is known for being fast and lightweight. It is less extensible than remark-parse but can be a good choice for simpler use cases where a full AST is not required.
Parser for unified. Parses markdown to mdast syntax trees. Used in the remark processor but can be used on its own as well. Can be extended to change how markdown is parsed.
Announcing the unified collective! 🎉 Read more about it on Medium »
🥇 ZEIT |
🥇 Gatsby |
🥉 Compositor |
Holloway |
You? |
npm:
npm install remark-parse
var unified = require('unified')
var createStream = require('unified-stream')
var markdown = require('remark-parse')
var html = require('remark-html')
var processor = unified()
.use(markdown, {commonmark: true})
.use(html)
process.stdin.pipe(createStream(processor)).pipe(process.stdout)
processor.use(parse[, options])Configure the processor to read markdown as input and process
mdast syntax trees.
optionsOptions are passed directly, or passed later through processor.data().
options.gfmhello ~~hi~~ world
GFM mode (boolean, default: true) turns on:
options.commonmarkThis is a paragraph
and this is also part of the preceding paragraph.
CommonMark mode (boolean, default: false) allows:
( and )) around for link and image titles)) as an ordered list markerCommonMark mode disallows:
# Hash headings) without spacing after opening hashes
or and before closing hashesUnderline headings\n---) when following a paragraph< and >)>), for lists, code, and thematicBreakoptions.footnotesSomething something[^or something?].
And something else[^1].
[^1]: This reference footnote contains a paragraph...
* ...and a list
Footnotes mode (boolean, default: false) enables reference footnotes and
inline footnotes. Both are wrapped in square brackets and preceded by a caret
(^), and can be referenced from inside other footnotes.
options.blocks<block>foo
</block>
Blocks (Array.<string>, default: list of block HTML elements)
exposes let’s users define block-level HTML elements.
options.pedanticCheck out some_file_name.txt
Pedantic mode (boolean, default: false) turns on:
_alpha_) and importance (__bravo__) with underscores
in words*, -, +)commonmark is also turned on, ordered lists with different
markers (., ))parse.ParserAccess to the parser, if you need it.
Most often, using transformers to manipulate a syntax tree produces the desired output. Sometimes, mainly when introducing new syntactic entities with a certain level of precedence, interfacing with the parser is necessary.
If the remark-parse plugin is used, it adds a Parser constructor
to the processor. Other plugins can add tokenizers to the parser’s prototype
to change how markdown is parsed.
The below plugin adds a tokenizer for at-mentions.
module.exports = mentions
function mentions() {
var Parser = this.Parser
var tokenizers = Parser.prototype.inlineTokenizers
var methods = Parser.prototype.inlineMethods
// Add an inline tokenizer (defined in the following example).
tokenizers.mention = tokenizeMention
// Run it just before `text`.
methods.splice(methods.indexOf('text'), 0, 'mention')
}
Parser#blockTokenizersAn object mapping tokenizer names to tokenizers. These
tokenizers (for example: fencedCode, table, and paragraph) eat
from the start of a value to a line ending.
See #blockMethods below for a list of methods that are included by
default.
Parser#blockMethodsArray of blockTokenizers names (string) specifying the order in
which they run.
newlineindentedCodefencedCodeblockquoteatxHeadingthematicBreaklistsetextHeadinghtmlfootnotedefinitiontableparagraphParser#inlineTokenizersAn object mapping tokenizer names to tokenizers. These tokenizers
(for example: url, reference, and emphasis) eat from the start
of a value. To increase performance, they depend on locators.
See #inlineMethods below for a list of methods that are included by
default.
Parser#inlineMethodsArray of inlineTokenizers names (string) specifying the order in
which they run.
escapeautoLinkurlhtmllinkreferencestrongemphasisdeletioncodebreaktextfunction tokenizer(eat, value, silent)tokenizeMention.notInLink = true
tokenizeMention.locator = locateMention
function tokenizeMention(eat, value, silent) {
var match = /^@(\w+)/.exec(value)
if (match) {
if (silent) {
return true
}
return eat(match[0])({
type: 'link',
url: 'https://social-network/' + match[1],
children: [{type: 'text', value: match[0]}]
})
}
}
The parser knows two types of tokenizers: block level and inline level. Block level tokenizers are the same as inline level tokenizers, with the exception that the latter must have a locator.
Tokenizers test whether a document starts with a certain syntactic entity. In silent mode, they return whether that test passes. In normal mode, they consume that token, a process which is called “eating”. Locators enable tokenizers to function faster by providing information on where the next entity may occur.
Node? = tokenizer(eat, value)boolean? = tokenizer(eat, value, silent)eat (Function) — Eat, when applicable, an entityvalue (string) — Value which may start an entitysilent (boolean, optional) — Whether to detect or consumelocator (Function)
— Required for inline tokenizersonlyAtStart (boolean)
— Whether nodes can only be found at the beginning of the documentnotInBlock (boolean)
— Whether nodes cannot be in blockquotes, lists, or footnote
definitionsnotInList (boolean)
— Whether nodes cannot be in listsnotInLink (boolean)
— Whether nodes cannot be in linksvaluevaluetokenizer.locator(value, fromIndex)function locateMention(value, fromIndex) {
return value.indexOf('@', fromIndex)
}
Locators are required for inline tokenization to keep the process performant. Locators enable inline tokenizers to function faster by providing information on the where the next entity occurs. Locators may be wrong, it’s OK if there actually isn’t a node to be found at the index they return, but they must skip any nodes.
value (string) — Value which may contain an entityfromIndex (number) — Position to start searching atIndex at which an entity may start, and -1 otherwise.
eat(subvalue)var add = eat('foo')
Eat subvalue, which is a string at the start of the
tokenized value (it’s tracked to ensure the correct
value is eaten).
subvalue (string) - Value to eat.add.
add(node[, parent])var add = eat('foo')
add({type: 'text', value: 'foo'})
Add positional information to node and add it to parent.
node (Node) - Node to patch position on and insertparent (Node, optional) - Place to add node to in
the syntax tree. Defaults to the currently processed nodeThe given node.
add.test()Get the positional information which would be patched on
node by add.
add.reset(node[, parent])add, but resets the internal location. Useful for example in
lists, where the same content is first eaten for a list, and later
for list items
node (Node) - Node to patch position on and insertparent (Node, optional) - Place to add node to in
the syntax tree. Defaults to the currently processed nodeThe given node.
In rare situations, you may want to turn off a tokenizer to avoid parsing
that syntactic feature. This can be done by replacing the tokenizer from
your Parser’s blockTokenizers (or blockMethods) or inlineTokenizers
(or inlineMethods).
The following example turns off indented code blocks:
remarkParse.Parser.prototype.blockTokenizers.indentedCode = indentedCode
function indentedCode() {
return true
}
Preferably, just use this plugin.
FAQs
remark plugin to add support for parsing markdown input
The npm package remark-parse receives a total of 3,639,757 weekly downloads. As such, remark-parse popularity was classified as popular.
We found that remark-parse demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.