
Product
Introducing Module Reachability: Focus on the Vulnerabilities That Matter
Module Reachability filters out unreachable CVEs so you can focus on vulnerabilities that actually matter to your application.
micromark-extension-directive
Advanced tools
micromark extension to support generic directives (`:cite[smith04]`)
The micromark-extension-directive package is an extension for micromark, a Markdown parser, that allows for the use of custom directives within Markdown content. This can be useful for adding custom syntax or functionality to Markdown documents.
Custom Block Directives
This feature allows you to define custom block directives in your Markdown content. The example shows how to use a custom block directive and convert it to HTML using micromark.
const micromark = require('micromark');
const directive = require('micromark-extension-directive');
const content = ':::{custom-block}
This is a custom block directive.
:::';
const html = micromark(content, {
extensions: [directive()]
});
console.log(html);
Custom Leaf Directives
This feature allows you to define custom leaf directives in your Markdown content. The example shows how to use a custom leaf directive and convert it to HTML using micromark.
const micromark = require('micromark');
const directive = require('micromark-extension-directive');
const content = '::custom-leaf[This is a custom leaf directive.]';
const html = micromark(content, {
extensions: [directive()]
});
console.log(html);
Custom Text Directives
This feature allows you to define custom text directives in your Markdown content. The example shows how to use a custom text directive and convert it to HTML using micromark.
const micromark = require('micromark');
const directive = require('micromark-extension-directive');
const content = 'This is a text with a ::custom-text[custom text directive].';
const html = micromark(content, {
extensions: [directive()]
});
console.log(html);
remark-directive is a plugin for remark, another Markdown processor, that provides similar functionality for custom directives. It allows you to define custom syntax and behavior in Markdown documents. Compared to micromark-extension-directive, remark-directive is used within the remark ecosystem and offers similar capabilities for handling custom directives.
markdown-it-container is a plugin for markdown-it, a different Markdown parser, that allows for custom containers in Markdown. It provides a way to define custom block-level containers with specific syntax. While it doesn't offer the same granularity as micromark-extension-directive, it is useful for creating custom block elements in Markdown.
markdown-it-directive is another plugin for markdown-it that provides support for custom directives. It allows you to define custom syntax and behavior for both block and inline directives. This package is similar to micromark-extension-directive but is designed to work with the markdown-it parser.
micromark extensions to support directives (:cite[smith04]
and
such).
This package contains two extensions that add support for directive syntax in
markdown to micromark
.
This project is useful when you want to solve the need for an infinite number of potential extensions to markdown in a single markdown-esque way.
You can use these extensions when you are working with micromark
already.
When you need a syntax tree,
you can combine this package with
mdast-util-directive
.
All these packages are used remark-directive
,
which focusses on making it easier to transform content by abstracting these
internals away.
This package is ESM only. In Node.js (version 16+), install with npm:
npm:
npm install micromark-extension-directive
In Deno with esm.sh
:
import {directive, directiveHtml} from 'https://esm.sh/micromark-extension-directive@4'
In browsers with esm.sh
:
<script type="module">
import {directive, directiveHtml} from 'https://esm.sh/micromark-extension-directive@4?bundle'
</script>
Say our document example.md
contains:
A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.
…and our module example.js
looks as follows:
/**
* @import {Handle} from 'micromark-extension-directive'
* @import {CompileContext} from 'micromark-util-types'
*/
import fs from 'node:fs/promises'
import {micromark} from 'micromark'
import {directive, directiveHtml} from 'micromark-extension-directive'
const output = micromark(await fs.readFile('example.md'), {
extensions: [directive()],
htmlExtensions: [directiveHtml({abbr})]
})
console.log(output)
/**
* @this {CompileContext}
* @type {Handle}
* @returns {false | undefined}
*/
function abbr(d) {
if (d.type !== 'textDirective') return false
this.tag('<abbr')
if (d.attributes && 'title' in d.attributes) {
this.tag(' title="' + this.encode(d.attributes.title) + '"')
}
this.tag('>')
this.raw(d.label || '')
this.tag('</abbr>')
}
…now running node example.js
yields:
<p>A lovely language know as <abbr title="HyperText Markup Language">HTML</abbr>.</p>
This package exports the identifiers directive
and
directiveHtml
.
There is no default export.
It exports the TypeScript types
Directive
,
Handle
,
and HtmlOptions
.
The export map supports the development
condition.
Run node --conditions development module.js
to get instrumented dev code.
Without this condition,
production code is loaded.
directive()
Create an extension for micromark
to enable directive syntax.
Extension for micromark
that can be passed in extensions
,
to enable directive syntax
(Extension
).
directiveHtml(options?)
Create an extension for micromark
to support directives when serializing to
HTML.
👉 Note: this uses KaTeX to render math.
options
(HtmlOptions
, default: {}
)
— configurationExtension for micromark
that can be passed in htmlExtensions
,
to support directives when serializing to HTML
(HtmlExtension
).
Directive
Structure representing a directive (TypeScript type).
type
('containerDirective'
, 'leafDirective'
, or 'textDirective'
)
— kindname
(string
)
— name of directivelabel
(string
or undefined
)
— compiled HTML content that was in [brackets]
attributes
(Record<string, string>
or undefined
)
— object w/ HTML attributescontent
(string
or undefined
)
— compiled HTML content inside container directiveHandle
Handle a directive (TypeScript type).
this
(CompileContext
)
— current contextdirective
(Directive
)
— directiveSignal whether the directive was handled
(boolean
, default: true
).
Yield false
to let the fallback (a special handle for '*'
) handle it.
HtmlOptions
Configuration (TypeScript type).
👉 Note: the special field
'*'
can be used to specify a fallback handle to handle all otherwise unhandled directives.
type HtmlOptions = Record<string, Handle>
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.
The syntax looks like this:
Directives in text can form with a single colon,
such as :cite[smith04].
Their syntax is `:name[label]{attributes}`.
Leafs (block without content) can form by using two colons:
::youtube[Video of a cat in a box]{vid=01ab2cd3efg}
Their syntax is `::name[label]{attributes}` on its own line.
Containers (blocks with content) can form by using three colons:
:::spoiler
He dies.
:::
The `name` part is required.
The first character must be a letter,
other characters can be alphanumerical, `-`, and `_`.
`-` or `_` cannot end a name.
The `[label]` part is optional (`:x` and `:x[]` are equivalent)†.
When used,
it can include text constructs such as emphasis and so on: `x[a *b* c]`.
The `{attributes}` part is optional (`:x` and `:x{}` are equivalent)†.
When used,
it is handled like HTML attributes, such as that `{a}`, `{a=""}`, and `{a=''}`
but also `{a=b}`, `{a="b"}`, and `{a='b'}` are equivalent.
Shortcuts are available for `id=` (`{#readme}` for `{id=readme}`) and
`class` (`{.big}` for `{class=big}`).
When multiple ids are found,
the last is used; when multiple classes are found,
they are combined:
`{.red class=green .blue}` is equivalent to
`{.red .green .blue}` and `{class="red green blue"}`.
† there is one case where a name must be followed by an empty label or empty
attributes:
a *text* directive that only has a name,
cannot be followed by a colon.
So,
`:red:` doesn’t work.
Use either `:red[]` or `:red{}` instead.
The reason for this is to allow GitHub emoji (gemoji) and directives to coexist.
Containers can be nested by using more colons outside:
::::spoiler
He dies.
:::spoiler
She is born.
:::
::::
The closing fence must include the same or more colons as the opening.
If no closing is found,
the container runs to the end of its parent container
(block quote, list item, document, or other container).
::::spoiler
These three are not enough to close
:::
So this line is also part of the container.
Note that while other implementations are sometimes loose in what they allow, this implementation mimics CommonMark as closely as possible:
: a
:a []
:a {}
:a[] {}
[] ()
:::a:::
::a[b\nc]
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,
micromark-extension-directive@4
,
compatible with Node.js 16.
This package works with micromark
version 4
and later.
This package is safe assuming that you write safe handlers. Any vulnerability in your code could open you to a cross-site scripting (XSS) attack.
remark-directive
— remark plugin to support directivesmdast-util-directive
— mdast utility to support directivesSee contributing.md
in micromark/.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
micromark extension to support generic directives (`:cite[smith04]`)
The npm package micromark-extension-directive receives a total of 706,760 weekly downloads. As such, micromark-extension-directive popularity was classified as popular.
We found that micromark-extension-directive demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 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
Module Reachability filters out unreachable CVEs so you can focus on vulnerabilities that actually matter to your application.
Product
Socket is introducing a new way to organize repositories and apply repository-specific security policies.
Company News
Socket’s acquisition of Coana brings best-in-class reachability analysis to application security teams globally, cementing Socket’s position as the leader in software supply chain security.