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
• Appendix
  • Published Package Details
  • License
• Contributing and Support
  • Contributors

Install

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

To install:

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]

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.

Appendix

Further documentation can be found under docs/.

Published Package Details

This is an ESM-only package built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

That means ESM source will load this package via import { ... } from ... or await import(...) and CJS source will load this package via dynamic import(). This has several benefits, the foremost being: less code shipped/smaller package size, avoiding dual package hazard entirely, distributables are not packed/bundled/uglified, and a drastically less complex build process.

The glaring downside, which may or may not be relevant, is that CJS consumers cannot require() this package and can only use import() in an asynchronous context. This means, in effect, CJS consumers may not be able to use this package at all.

Each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes one or more export conditions. These entries may or may not include: an exports[ENTRY].types condition pointing to a type declaration file for TypeScript and IDEs, a exports[ENTRY].module condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and other conditions not enumerated here. Check the package.json file to see which export conditions are supported.

Note that, regardless of the { "type": "..." } specified in package.json, any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that package.json may include the sideEffects key, which is almost always false for optimal tree shaking where appropriate.

License

See LICENSE.

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! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.

Contributors

See the table of contributors.