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.

• Install
• Usage
  • Additional Considerations
• API
  • Ast Nodes
• Related
• Contributing and Support
  • Contributors

Install

Due to the nature of the unified ecosystem, this package is ESM only and cannot be require'd.

npm install mdast-util-hidden

Usage

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 their position data stripped off using unist-util-remove-position (making them generated nodes). This is because position data can be invalidated at any time due to it being impossible to know how later plugins will manipulate the AST. Missing position 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" }]
    }
  ]
}

Additional Considerations

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.

API

Detailed interface information can be found under docs/.

Ast Nodes

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.

Related

• 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.

Contributing and Support

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.

Contributors

See the table of contributors.