remark-directive

remark-directive is a plugin for the unified/remark ecosystem that implements the CommonMark generic directives proposal — a single, consistent syntax (:name[]{}, ::name[]{}, :::name[]{}) for arbitrary markdown extensions. Rather than inventing a new ad-hoc syntax for every feature (custom containers, embeds, callouts), it gives authors one predictable pattern and gives plugin developers three new mdast node types (textDirective, leafDirective, containerDirective) to visit and transform.

The package itself does no rendering — it only parses directives into the syntax tree and can serialize them back to markdown. Turning a directive into HTML (or anything else) is left to a small user-authored remark plugin that visits the new node types, which keeps remark-directive minimal, dependency-light, and reusable across very different use cases: documentation callouts, video embeds, styled blocks, and more.

What You Get

• Three new mdast node types — textDirective, leafDirective, containerDirective — added to the parse tree for any markdown containing directive syntax
• Micromark, fromMarkdown, and toMarkdown extensions wired automatically into the unified processor via a single .use(remarkDirective) call
• Configurable markdown serialization (collapseEmptyAttributes, preferShortcut, preferUnquoted, quoteSmart, quote) for round-tripping directives back to clean markdown
• Full TypeScript typings with 100% type coverage, so directive options and node types are statically checked
• A minimal, unopinionated core — no bundled HTML renderer, so it composes with any downstream rendering plugin

Common Use Cases

• Documentation sites using :::note{.warning} style container directives for callouts and admonitions
• Static site generators embedding rich media (e.g. ::youtube[]{v=...}) via leaf directives instead of raw HTML
• CMS or blogging platforms offering non-technical authors a constrained, safe extension syntax instead of full HTML/JSX
• Plugin authors building higher-level markdown extensions (custom components, styled blocks) on top of the directive node types

Under The Hood

Architecture The entire runtime is a single default-export function (lib/index.js, under 40 lines) that runs once when a unified processor attaches the plugin: it reads this.data(), lazily initializes the processor’s micromarkExtensions, fromMarkdownExtensions, and toMarkdownExtensions arrays, and pushes one extension of each kind sourced from micromark-extension-directive (tokenizing) and mdast-util-directive (tree construction/serialization). There is no additional module graph, no internal state beyond what unified already manages, and no rendering logic at all — directive-to-HTML conversion is explicitly deferred to a separate plugin the consumer writes, which keeps the core’s blast radius trivial if the directive spec or unified’s plugin API changes.

Tech Stack Built as a pure ESM Node.js package ("type": "module", Node 16+ engines) with zero bundler or framework dependencies. Its four runtime dependencies are all part of the unified/remark/micromark ecosystem: @types/mdast for tree typings, mdast-util-directive for AST construction and markdown stringification, micromark-extension-directive for tokenizing the directive syntax, and unified itself. TypeScript types are hand-authored in index.d.ts (not compiled from .ts sources) and checked via tsc --build plus type-coverage in the build script.

Code Quality Tests live in test/index.js using Node’s built-in node:test and assert/strict, combined with a fixture-driven harness that walks test/fixtures/{container,leaf,text} directories, parses each input.md, and diffs both the resulting mdast tree (tree.json) and the re-serialized markdown output against checked-in expectations — a solid regression net for syntax-tree correctness even though it’s a small surface area. The project enforces 100% branch coverage via c8 --100 and lints with xo plus remark-preset-wooorm (dogfooding its own ecosystem’s linting conventions) and Prettier, all wired into a single npm test script alongside the type-coverage build step.

What Makes It Unique Unlike ad-hoc “one syntax per feature” extensions, remark-directive implements a single community-proposed generic directive grammar shared across the unified ecosystem, which lets independent plugin authors standardize on one attribute/naming convention instead of each inventing incompatible container syntaxes. Its deliberate refusal to bundle a renderer is itself the notable design choice: by staying a pure syntax-to-tree layer, it stays composable with arbitrarily different output targets (HTML via hast, or entirely custom renderers) without ever needing to know about them.