Micromark-extension-taggable NPM

micromark-extension-taggable

micromark extensions to support custom #tags and @mentions.

What is this?

This package contains extensions that add support for custom mentions and tags into micromark. It can be configured to parse tags of the following sort:

#tag @user $page #page/subpage

For example, with the default configuration,

Micromark is #awesome right @conner ?

is parsed to

<p>
  Micromark is
  <a href="/tags/awesome" class="micromark-taggable tag">#awesome</a> right
  <a href="/users/conner" class="micromark-taggable user"> @conner</a> ?
</p>

Output: Micromark is #awesome right @conner ?

When to use this

This project is useful when you want to support custom tags in markdown.

You can use these extensions when you are working with micromark.

When you need a syntax tree, you can combine this package with mdast-util-taggable.

All these packages are used remark-taggable. It is recommended to this package when working with remark.

Install

In Node.js (version 16+), install with npm:

npm install micromark-extension-taggable

In Deno with esm.sh:

import {
  gfmTaskListItem,
  gfmTaskListItemHtml,
} from "https://esm.sh/micromark-extension-taggable";

In browsers with esm.sh:

<script type="module">
  import {
    gfmTaskListItem,
    gfmTaskListItemHtml,
  } from "https://esm.sh/micromark-extension-taggable?bundle";
</script>

Use

import { micromark } from "micromark";
import { syntax, html } from "micromark-extension-taggable";

const output = micromark("#tag", {
  extensions: [syntax()],
  htmlExtensions: [html()],
});

console.log(output);

Yields:

<p><a href="/tags/tag" class="micromark-taggable tag">#tag</a></p>

Configuration Options

The following options can be specified:

`syntax(options)`

options.classes: string[] = Array of class names to be given to HTML representation of every type of taggable
options.rules: rule[] = Describes the rules for the taggables/markers.
- rule.marker: string = The marker that marks the start of a tag.
- rule.type string = The type of taggable.
- rule.toUrl: (string) => string = Function that maps the taggable name/value to a URL.
- rule.classes: string[] = Array of class names to be given to HTML representation of this type of taggable
options.allowEmail: boolean = If set to true, the parser will also consider @ and . to be valid characters for the title/value.

The defaults are:

{
    classes: ["micromark-taggable"],
    rules: [
        {
            classes: ["tag"],
            marker: "#",
            toUrl: (argument) => `/tags/${argument}`,
            type: "tag",
        },
        {
            classes: ["mention"],
            marker: "@",
            toUrl: (argument) => `/users/${argument}`,
            type: "mention",
        },
    ]
}

Returns

syntax(): Array of extension for micromark that can be passed in extensions.
- Because it is an array, it is recommended to use spread syntax when passing to extensions:
```
extensions: [...syntax()];
```
html(): HtmlExtension for micromark that can be passed in htmlExtensions

Returns

Extension for micromark that can be passed in htmlExtensions to support GFM task list items when serializing to HTML (HtmlExtension).

Authoring

The following restrictions apply to this markdown extension:

Spaces cannot be used in the taggable value. We recommend using dashes - or underscores _:
```
❌ This is a #multi word tag.
✔️ This is a #multi-word-tag.
```
Output: > ❌ This is a <a href="/tags/multi">#multi</a> word tag. > ✔️ This is a <a href="/tags/#multi-word-tag">#multi-word-tag</a>.
By default, the parser only considers the following characters:
- Characters in the Unicode General Category L.
- The following characters:
  - / | :
- If the option Option.rules.rule.allowEmail is set to true:
  - . @
  In this case, do note that periods will not terminate the taggable.
Anything outside of these characters will not be included in the taggable. For name, we recommend setting up a key for your users that use either:
- First Name: Only viable for small sets. Example: John.
- An Alias: Viable for a large set of users. Can be alphanumeric, following above constraints. Example: USR23B3
- Using the user's email ID: Viable for any set of users. Example: contact@therdas.dev. The option Option.rules.rule.allowEmail needs to be set to true. As an example:
```
{
  rules: [
      ...,
      {
          marker: "@",
          type: "mention",
          toUrl: (val) => `/users/${val.replace("@", "-at-").replace(".", "_")}`,
      }
  ],
  allowEmail: true
}
```

Syntax

Checks form with the following BNF:

<taggable> ::= <marker><value>
<marker> ::= # | @
<value> ::= <text>

Where both <marker> and <text> can be specified via options.

License

MIT © Rahul Das

Changes

v1.0.0:
- Moved the library over to TypeScript.
- ⚠️ Breaking Change: The library now supplies an Extension instead of an Array<Extension>. There is now no need for using the spread operator when passing the syntax extension

Please refer to the changelog for more information regarding changes