mdast-util-hidden
This is a small mdast utility for hiding nodes from transformers by mapping them to Hidden pseudo-node instances.
This is a low level project used by remark-ignore and remark-renumber-references.
Due to the nature of the unified ecosystem, this package is ESM only and cannot be
require
'd.
npm install mdast-util-hidden
Suppose we have the following Markdown file example.md
:
# Hello
Some _emphasis_, **importance**, and `code`.
# Goodbye
Represented by the following AST (with position
data omitted for brevity):
{
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [{ "type": "text", "value": "Hello" }]
},
{
"type": "paragraph",
"children": [
{ "type": "text", "value": "Some " },
{
"type": "emphasis",
"children": [{ "type": "text", "value": "emphasis" }]
},
{ "type": "text", "value": ", " },
{
"type": "strong",
"children": [{ "type": "text", "value": "importance" }]
},
{ "type": "text", "value": ", and " },
{ "type": "inlineCode", "value": "code" },
{ "type": "text", "value": "." }
]
},
{
"type": "heading",
"depth": 1,
"children": [{ "type": "text", "value": "Goodbye" }]
}
]
}
Then running the following JavaScript:
import fs from 'node:fs';
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { visit, SKIP } from 'unist-util-visit';
import { hide } from 'mdast-util-hidden';
const doc = fs.readFileSync('example.md');
const tree = unified().use(remarkParse).parse(doc);
visit(tree, 'heading', (node, index, parent) => {
if (index !== undefined && parent !== undefined) {
// β¦ Other stuff
hide({ nodes: [node], index, parent });
// Do not traverse node, continue with the next node at index + 1
return [SKIP, index + 1];
}
});
console.dir(tree, { depth: null });
Yields:
{
"type": "root",
"children": [
{
"type": "hidden",
"hiddenChildren": [
{
"type": "heading",
"depth": 1,
"children": [{ "type": "text", "value": "Hello" }]
}
]
},
{
"type": "paragraph",
"children": [
{ "type": "text", "value": "Some " },
{
"type": "emphasis",
"children": [{ "type": "text", "value": "emphasis" }]
},
{ "type": "text", "value": ", " },
{
"type": "strong",
"children": [{ "type": "text", "value": "importance" }]
},
{ "type": "text", "value": ", and " },
{ "type": "inlineCode", "value": "code" },
{ "type": "text", "value": "." }
]
},
{
"type": "hidden",
"hiddenChildren": [
{
"type": "heading",
"depth": 1,
"children": [{ "type": "text", "value": "Goodbye" }]
}
]
}
]
}
Note that the elements of
hiddenChildren
will, if later revealed, have theirposition
data stripped off using unist-util-remove-position (making them generated nodes). This is becauseposition
data can be invalidated at any time due to it being impossible to know how later plugins will manipulate the AST. Missingposition
data will not crash any remark plugins that properly follow the unist spec.
And running the following JavaScript:
import fs from 'node:fs';
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { visit, SKIP } from 'unist-util-visit';
import { hide, visitAndReveal, reveal } from 'mdast-util-hidden';
const doc = fs.readFileSync('example.md');
const tree = unified().use(remarkParse).parse(doc);
visit(tree, 'heading', (node, index, parent) => {
if (index !== undefined && parent !== undefined) {
hide({ nodes: [node], index, parent });
return [SKIP, index + 1];
}
});
// LATER:
visit(tree, 'hidden', (node, index, parent) => {
if (index !== undefined && parent !== undefined) {
reveal({ nodes: [node], index, parent });
// β¦ Other stuff
// Do not traverse node, continue with the node now at index (NOT index + 1)
return [SKIP, index];
}
});
// OR:
visitAndReveal({ tree });
// OR:
visitAndReveal({
tree,
visitor: (node, index, parent) => {
// reveal is called for you
// β¦ Other stuff
// returns [SKIP, index] unless this function returns a defined value
}
});
console.dir(tree, { depth: null });
Yields the original AST with the hidden headings restored (but stripped of their
position
data):
{
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [{ "type": "text", "value": "Hello" }]
},
{
"type": "paragraph",
"children": [
{ "type": "text", "value": "Some " },
{
"type": "emphasis",
"children": [{ "type": "text", "value": "emphasis" }]
},
{ "type": "text", "value": ", " },
{
"type": "strong",
"children": [{ "type": "text", "value": "importance" }]
},
{ "type": "text", "value": ", and " },
{ "type": "inlineCode", "value": "code" },
{ "type": "text", "value": "." }
]
},
{
"type": "heading",
"depth": 1,
"children": [{ "type": "text", "value": "Goodbye" }]
}
]
}
When using mdast-util-hidden in your own remark plugin, it's generally a good
idea to mark your Hidden
nodes with a unique symbol and ensure that you only
call reveal
and visitAndReveal
on the Hidden
nodes marked with
said symbol. Otherwise, if someone is using your plugin and remark-ignore
concurrently, it could be the case that your plugin accidentally reveals nodes
that were hidden by remark-ignore, causing erroneous transformations against the
user's wishes.
An example of using a unique symbol to mark ownership of Hidden
nodes can be
found in the remark-renumber-references source code.
Detailed interface information can be found under docs/
.
Hidden
interface Hidden extends Node {
type: 'hidden';
hiddenChildren: MdastContent[];
}
Hidden (Node) represents an abstract interface in mdast containing mdast content that is hidden (and thus protected) from other transformers.
Hidden nodes are always generated, cannot be serialized to markdown, and cannot be derived from markdown directly.
- remark-ignore β use comments to exclude one or more nodes from transformation.
- remark-renumber-references β renumber numeric reference-style link ids
contiguously starting from
[1]
. - rehype-ignore β ignore content display via HTML comments.
New issues and pull requests are always welcome and greatly appreciated! π€© Just as well, you can star π this project to let me know you found it useful! βπΏ Thank you!
See CONTRIBUTING.md and SUPPORT.md for more information.
See the table of contributors.