micromark-extension-directive

What is micromark-extension-directive?

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.

What are micromark-extension-directive's main functionalities?

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);

Other packages similar to micromark-extension-directive

remark-directive

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

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

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.

README

micromark-extension-directive

micromark extension to support the generic directives proposal (:cite[smith04], ::youtube[Video of a cat in a box]{v=01ab2cd3efg}, and such).

Generic directives solve the need for an infinite number of potential extensions to markdown in a single markdown-esque way. However, it’s just a proposal and may never be specced.

When to use this

If you’re using micromark or mdast-util-from-markdown, use this package. Alternatively, if you’re using remark, use remark-directive.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install micromark-extension-directive

Use

Say we have the following file, example.md:

A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}.

And our script, example.js, looks as follows:

import fs from 'node:fs'
import {micromark} from 'micromark'
import {directive, directiveHtml} from 'micromark-extension-directive'

const output = micromark(fs.readFileSync('example.md'), {
  extensions: [directive()],
  htmlExtensions: [directiveHtml({abbr})]
})

console.log(output)

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 yields (abbreviated):

<p>A lovely language know as <abbr title="HyperText Markup Language">HTML</abbr>.</p>

API

This package exports the following identifiers: directive, directiveHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

directive(syntaxOptions?)

directiveHtml(htmlOptions?)

Functions that can be called with options to get an extension for micromark to parse directives (can be passed in extensions) and one to compile them to HTML (can be passed in htmlExtensions).

syntaxOptions

None yet, but might be added in the future.

htmlOptions

An object mapping names of directives to handlers (Record<string, Handle>). The special name '*' is the fallback to handle all unhandled directives.

function handle(directive)

How to handle a directive (Directive).

Returns

boolean or void — false can be used to signal that the directive could not be handled, in which case the fallback is used (when given).

Directive

An object representing a directive.

Fields

• type ('textDirective'|'leafDirective'|'containerDirective')
• name (string) — name of directive
• label (string?) — compiled HTML content that was in [brackets]
• attributes (Record<string, string>?) — object w/ HTML attributes
• content (string?) — compiled HTML content inside container directive

Syntax

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=""}`,
, `{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:

• Whitespace is not allowed between colons and name (: a), name and label (:a []), name and attributes (:a {}), or label and attributes (:a[] {}) — because it’s not allowed in links either ([] ())
• No trailing colons allowed on the opening fence of a container (:::a:::) — because it’s not allowed in fenced code either
• The label and attributes in a leaf or container cannot include line endings (::a[b\nc]) — because it’s not allowed in fenced code either

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-directive — remark plugin using this to support directive
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• syntax-tree/mdast-util-directive — mdast utility to support generic directives
• syntax-tree/mdast-util-from-markdown — mdast parser using micromark to create mdast from markdown
• syntax-tree/mdast-util-to-markdown — mdast serializer to create markdown from mdast

Contribute

See 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.

License

MIT © Titus Wormer