mdast-util-directive

mdast-util-directive is a utility in the unified/remark ecosystem that adds support for the generic directives proposal to mdast, the markdown abstract syntax tree. It provides two extensions: one that plugs into mdast-util-from-markdown to parse directive syntax into typed syntax-tree nodes, and one that plugs into mdast-util-to-markdown to serialize those nodes back to markdown.

Directives are a controlled, extensible syntax for markdown—text (:name), leaf (::name), and container (:::name) forms—that let content authors embed rich components like citations, video embeds, or callouts without writing raw HTML or JavaScript. This package handles the tree-level parsing and stringification, working alongside micromark-extension-directive which handles the tokenization.

What You Get

• directiveFromMarkdown() to parse text, leaf, and container directives into mdast nodes
• directiveToMarkdown() to serialize directive nodes back to markdown, with configurable options
• Typed node definitions (ContainerDirective, LeafDirective, TextDirective) with full TypeScript types
• Seamless composition with mdast-util-from-markdown, mdast-util-to-markdown, and remark-directive

Common Use Cases

• Adding custom components (embeds, callouts, citations) to a docs site or static site generator
• Building remark/rehype pipelines that transform directives into HTML or React components
• Authoring extensible markdown for blogging tools where authors shouldn’t write raw HTML
• Programmatically generating markdown that includes directive nodes

Under The Hood

Architecture The package exposes two entry points from lib/index.js: directiveFromMarkdown() returns a from-markdown extension whose enter/exit handlers assemble ContainerDirective, LeafDirective, and TextDirective nodes as micromark tokenizes directive syntax, while directiveToMarkdown() returns a to-markdown extension whose node handlers stringify those nodes back to markdown. Attribute parsing leans on parse-entities/stringify-entities and unist-util-visit-parents for tree traversal. It deliberately handles only the tree layer, delegating tokenization to micromark-extension-directive.

Tech Stack It is a pure ESM JavaScript package ("type": "module") targeting modern Node, with runtime dependencies on @types/mdast, ccount, devlop, mdast-util-from-markdown, mdast-util-to-markdown, parse-entities, stringify-entities, and unist-util-visit-parents. Types are emitted from JSDoc via the TypeScript compiler; dev tooling includes xo, prettier, remark-cli, c8, and type-coverage.

Code Quality Quality is exemplary for a micro-library: a single comprehensive test.js run under both development and production Node conditions, enforced 100% coverage via c8 (--100), 100% type coverage via type-coverage, and strict linting with xo. This is characteristic of the syntax-tree collective’s uniformly high standards.

API Design The API surface is tiny and predictable—two factory functions returning extension objects—mirroring every other mdast-util package so developers already in the unified ecosystem need no new mental model. The README is thorough, documenting each node type and option. The main learning curve is conceptual (understanding directives and how micromark/mdast extensions compose) rather than the API itself.