Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
remark-directive
Advanced tools
Readme
remark plugin to support the generic directives
proposal (:cite[smith04]
,
::youtube[Video of a cat in a box]{v=01ab2cd3efg}
, and such).
This package is a unified (remark) plugin to add support for directives: one syntax for arbitrary extensions in markdown.
Directives are one of the four ways to extend markdown: an arbitrary extension syntax (see Extending markdown in micromark’s docs for the alternatives and more info). This mechanism works well when you control the content: who authors it, what tools handle it, and where it’s displayed. When authors can read a guide on how to embed a tweet but are not expected to know the ins and outs of HTML or JavaScript. Directives don’t work well if you don’t know who authors content, what tools handle it, and where it ends up. Example use cases are a docs website for a project or product, or blogging tools and static site generators.
If you just want to turn markdown into HTML (with maybe a few extensions such
as this one), we recommend micromark
with
micromark-extension-directive
instead.
If you don’t use plugins and want to access the syntax tree, you can use
mdast-util-from-markdown
with
mdast-util-directive
.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install remark-directive
In Deno with esm.sh
:
import remarkDirective from 'https://esm.sh/remark-directive@3'
In browsers with esm.sh
:
<script type="module">
import remarkDirective from 'https://esm.sh/remark-directive@3?bundle'
</script>
Say our document example.md
contains:
:::main{#readme}
Lorem:br
ipsum.
::hr{.red}
A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.
:::
…and our module example.js
contains:
// Register `hName`, `hProperties` types, used when turning markdown to HTML:
/// <reference types="mdast-util-to-hast" />
// Register directive nodes in mdast:
/// <reference types="mdast-util-directive" />
import {h} from 'hastscript'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkDirective from 'remark-directive'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'
import {visit} from 'unist-util-visit'
const file = await unified()
.use(remarkParse)
.use(remarkDirective)
.use(myRemarkPlugin)
.use(remarkRehype)
.use(rehypeFormat)
.use(rehypeStringify)
.process(await read('example.md'))
console.log(String(file))
// This plugin is an example to let users write HTML with directives.
// It’s informative but rather useless.
// See below for others examples.
function myRemarkPlugin() {
/**
* @param {import('mdast').Root} tree
* Tree.
* @returns {undefined}
* Nothing.
*/
return function (tree) {
visit(tree, function (node) {
if (
node.type === 'containerDirective' ||
node.type === 'leafDirective' ||
node.type === 'textDirective'
) {
const data = node.data || (node.data = {})
const hast = h(node.name, node.attributes || {})
data.hName = hast.tagName
data.hProperties = hast.properties
}
})
}
}
…then running node example.js
yields:
<main id="readme">
<p>Lorem<br>ipsum.</p>
<hr class="red">
<p>A <i>lovely</i> language know as <abbr title="HyperText Markup Language">HTML</abbr>.</p>
</main>
This package exports no identifiers.
The default export is remarkDirective
.
unified().use(remarkDirective)
Add support for generic directives.
There are no parameters.
Nothing (undefined
).
Doesn’t handle the directives: create your own plugin to do that.
This example shows how directives can be used for YouTube embeds.
It’s based on the example in Use above.
If myRemarkPlugin
was replaced with this function:
// Register `hName`, `hProperties` types, used when turning markdown to HTML:
/// <reference types="mdast-util-to-hast" />
// Register directive nodes in mdast:
/// <reference types="mdast-util-directive" />
import {visit} from 'unist-util-visit'
// This plugin is an example to turn `::youtube` into iframes.
function myRemarkPlugin() {
/**
* @param {import('mdast').Root} tree
* Tree.
* @param {import('vfile').VFile} file
* File.
* @returns {undefined}
* Nothing.
*/
return (tree, file) => {
visit(tree, function (node) {
if (
node.type === 'containerDirective' ||
node.type === 'leafDirective' ||
node.type === 'textDirective'
) {
if (node.name !== 'youtube') return
const data = node.data || (node.data = {})
const attributes = node.attributes || {}
const id = attributes.id
if (node.type === 'textDirective') {
file.fail(
'Unexpected `:youtube` text directive, use two colons for a leaf directive',
node
)
}
if (!id) {
file.fail('Unexpected missing `id` on `youtube` directive', node)
}
data.hName = 'iframe'
data.hProperties = {
src: 'https://www.youtube.com/embed/' + id,
width: 200,
height: 200,
frameBorder: 0,
allow: 'picture-in-picture',
allowFullScreen: true
}
}
})
}
}
…and example.md
contains:
# Cat videos
::youtube[Video of a cat in a box]{#01ab2cd3efg}
…then running node example.js
yields:
<h1>Cat videos</h1>
<iframe src="https://www.youtube.com/embed/01ab2cd3efg" width="200" height="200" frameborder="0" allow="picture-in-picture" allowfullscreen>Video of a cat in a box</iframe>
👉 Note: This is sometimes called admonitions, callouts, etc.
This example shows how directives can be used to style blocks.
It’s based on the example in Use above.
If myRemarkPlugin
was replaced with this function:
// Register `hName`, `hProperties` types, used when turning markdown to HTML:
/// <reference types="mdast-util-to-hast" />
// Register directive nodes in mdast:
/// <reference types="mdast-util-directive" />
import {h} from 'hastscript'
import {visit} from 'unist-util-visit'
// This plugin is an example to turn `::youtube` into iframes.
// This plugin is an example to turn `::note` into divs, passing arbitrary
// attributes.
function myRemarkPlugin() {
/**
* @param {import('mdast').Root} tree
* Tree.
* @returns {undefined}
* Nothing.
*/
return (tree) => {
visit(tree, (node) => {
if (
node.type === 'containerDirective' ||
node.type === 'leafDirective' ||
node.type === 'textDirective'
) {
if (node.name !== 'note') return
const data = node.data || (node.data = {})
const tagName = node.type === 'textDirective' ? 'span' : 'div'
data.hName = tagName
data.hProperties = h(tagName, node.attributes || {}).properties
}
})
}
}
…and example.md
contains:
# How to use xxx
You can use xxx.
:::note{.warning}
if you chose xxx, you should also use yyy somewhere…
:::
…then running node example
yields:
<h1>How to use xxx</h1>
<p>You can use xxx.</p>
<div class="warning">
<p>if you chose xxx, you should also use yyy somewhere…</p>
</div>
When authoring markdown with directives, keep in mind that they don’t work in most places. On your own site it can be great!
You can define how directives are turned into HTML. If directives are not handled, they do not emit anything.
How to display directives is left as an exercise for the reader.
See Syntax in
micromark-extension-directive
.
See Syntax tree in
mdast-util-directive
.
This package is fully typed with TypeScript. It exports no additional options.
If you’re working with the syntax tree, you can register the new node types
with @types/mdast
by adding a reference:
// Register directive nodes in mdast:
/// <reference types="mdast-util-directive" />
import {visit} from 'unist-util-visit'
function myRemarkPlugin() {
/**
* @param {import('mdast').Root} tree
* Tree.
* @returns {undefined}
* Nothing.
*/
return (tree) => {
visit(tree, function (node) {
console.log(node) // `node` can now be one of the nodes for directives.
})
}
}
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, remark-directive@^3
,
compatible with Node.js 16.
Use of remark-directive
does not involve rehype (hast) or user
content so there are no openings for cross-site scripting (XSS)
attacks.
remark-gfm
— support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists)remark-frontmatter
— support frontmatter (YAML, TOML, and more)remark-math
— support mathremark-mdx
— support MDX (ESM, JSX, expressions)See contributing.md
in remarkjs/.github
for ways
to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
FAQs
remark plugin to support directives
The npm package remark-directive receives a total of 207,866 weekly downloads. As such, remark-directive popularity was classified as popular.
We found that remark-directive demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.