micromark-extension-taggable

[micromark][] extensions to support custom #tags and @mentions.

Contents

• What is this?
• When to use this
• Install
• Use
• Configuration Options
• Authoring
• Syntax
• Changes
• License

What is this?

This package contains extensions that add support for custom mentions and tags into [micromark][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][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][esmsh]:

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

In browsers with [esm.sh][esmsh]:

<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][micromark-html-extension]).

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: [email protected]. 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][license] © [Rahul Das][author]

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