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:

``md
#tag @user $page #page/subpage
`

For example, with the default configuration,

`md
Micromark is #awesome right @conner ?
`

is parsed to

`html



Micromark is
#awesome right
@conner ?



`

> 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][]:

`sh
npm install micromark-extension-taggable
`

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

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

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

`html

`

Use

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

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

console.log(output);
`

Yields:

`html


#tag


`

Configuration Options

The following options can be specified:

$3

- 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:

`js
{
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:
`js
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 _:
`js
❌ This is a #multi word tag.
✔️ This is a #multi-word-tag.
`
> Output:
> ❌ This is a #multi word tag.
> ✔️ This is a #multi-word-tag.
- 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:
`js
{
rules: [
...,
{
marker: "@",
type: "mention",
toUrl: (val) => /users/${val.replace("@", "-at-").replace(".", "_")},
}
],
allowEmail: true
}
`

Syntax

Checks form with the following BNF:

`bnf
::=
::= # | @
::=
`

Where both and 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. 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