remark-flexible-markers

This package is a unified (remark) plugin to add custom <mark> element with customizable properties in markdown.

unified is a project that transforms content with abstract syntax trees (ASTs) using the new parser micromark. remark adds support for markdown to unified. mdast is the Markdown Abstract Syntax Tree (AST) which is a specification for representing markdown in a syntax tree.

This plugin is a remark plugin that transforms the mdast.

When should I use this?

This plugin is useful if you want to add a custom <mark> element in markdown for providing marked or highlighted text, with custom tag name, custom class name, custom color classification, and also additional properties. You can easily create <mark> element with the remark-flexible-markers.

Installation

This package is suitable for ESM only. In Node.js (version 16+), install with npm:

npm install remark-flexible-markers

or

yarn add remark-flexible-markers

Usage

== sign around the content

==marked content==

[!IMPORTANT] The == in the begining part of representation specifies there is NO color specification.

=[classification key]= at the beginning side, == at the ending side

=r=marked content with red classification==

[!IMPORTANT] The =r= at the beginning part of representation specifies the color specification is "red".

Say we have the following file, example.md, which consists some flexible markers.

==marked content==
=r=marked content==

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

import { read } from "to-vfile";
import remark from "remark";
import gfm from "remark-gfm";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import remarkFlexibleMarkers from "remark-flexible-markers";

main();

async function main() {
  const file = await remark()
    .use(gfm)
    .use(remarkFlexibleMarkers)
    .use(remarkRehype)
    .use(rehypeStringify)
    .process(await read("example.md"));

  console.log(String(file));
}

Now, running node example.js yields:

<p>
  <mark class="flexible-marker flexible-marker-default">marked content</mark>
  <mark class="flexible-marker flexible-marker-red">marked content</mark>
</p>

Without remark-flexible-markers, you’d get:

<p>==marked content==
=r=marked content==</p>

[!CAUTION] The double equity signs must be adjacent to the content.
The content must be wrapped with double equity signs, not singular at any side.
More than one classification is not allowed.

Here are some bad usage, and will not work.

==text with bad wrapped=

=text with bad wrapped==

== text with unwanted space==

==text with unwanted space ==

=ab=text with more than one classification==

It is more flexible and powerful

As of version ^1.2.0, the remark-flexible-markers can handle also the syntax containing other markdown phrases like strong, emphasis, link etc. For example:

==**marked bold content**==

==_marked italic content_==

==[marked link](https://google.com)==

<p>
  <mark class="flexible-marker flexible-marker-default">
    <strong>marked bold content</strong>
  </mark>
</p>
<p>
  <mark class="flexible-marker flexible-marker-default">
    <em>marked italic content</em>
  </mark>
</p>
<p>
  <mark class="flexible-marker flexible-marker-default">
    <a href="https://google.com">marked link</a>
  </mark>
</p>

Options

All options are optional and have default values.

type Dictionary = Partial<Record<Key, string>>;
type TagNameFunction = (color?: string) => string;
type ClassNameFunction = (color?: string) => string[];
type PropertyFunction = (color?: string) => Record<string, unknown> & { className?: never };

use(remarkFlexibleMarkers, {
  dictionary?: Dictionary; // explained in the options section
  markerTagName?: string | TagNameFunction; // default is "mark"
  markerClassName?: string | ClassNameFunction; // default is "flexible-marker"
  markerProperties?: PropertyFunction;
  equalityOperator?: string;
  actionForEmptyContent?: "keep" | "remove" | "marker"; // // default is "marker"
} as FlexibleMarkerOptions);

dictionary

It is a key, value option for providing color classification for the mark node.

The dictionary is opinionated, by default.

type Key = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" 
         | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";

type Dictionary = Partial<Record<Key, string>>;

const dictionary: Dictionary = {
  a: "amber",
  b: "blue",
  c: "cyan",
  d: "brown",
  e: "espresso",
  f: "fuchsia",
  g: "green",
  h: "hotpink",
  i: "indigo",
  j: "jade",
  k: "kiwi",
  l: "lime",
  m: "magenta",
  n: "navyblue",
  o: "orange",
  p: "purple",
  q: "pink",
  r: "red",
  s: "silver",
  t: "teal",
  u: "umber",
  v: "violet",
  w: "white",
  x: "gray",
  y: "yellow",
  z: "black",
};

You can override the dictionary entries.

use(remarkFlexibleMarkers, {
  dictionary: {
    w: "wall"
  };
});

Now, it is overriden for the only w key, and the color classification will be wall instead of default one white.

=w=marked content==

<p>
  <mark class="remark-marker remark-marker-wall">marked content</mark>
</p>

markerTagName

It is a string or a callback (color?: string) => string option for providing custom HTML tag name for mark nodes.

By default, it is mark which is well known HTML element for highlighting the texts.

use(remarkFlexibleMarkers, {
  markerTagName: "span";
});

Now, the element tag names will be span.

<span class="...">marked content</span>

The option can take also a callback function, which has an optional argument color, and returns string representing the custom tag name.

use(remarkFlexibleMarkers, {
  markerTagName: (color) => color ?? "yellow";
});

Now, the element tag names will be the color name.

==marked content==
=r=marked content==

<p>
  <yellow class="...">marked content</yellow>
  <red class="...">marked content</red>
</p>

markerClassName

It is a string or a callback (color?: string) => string[] option for providing custom class name for the mark node.

By default, it is flexible-marker, and all mark nodes' classnames will contain flexible-marker.

A mark node contains also a secondary class name representing the color specification which starts with the flexible-marker- and ends with the color specification, like flexible-marker-red or flexible-marker-blue. If there is no color classification, then the secondary class name will be flexible-marker-default.

If a mark syntax in the document has no content, and would wanted to be an empty marker, the class name will contain flexible-marker-empty, additionally.

use(remarkFlexibleMarkers, {
  markerClassName: "remark-marker";
});

Now, the mark nodes will have remark-marker as a className, and the secondary class names will start with remark-marker-.

==marked content==
=r=marked content==

<p>
  <mark class="remark-marker remark-marker-default">marked content</mark>
  <mark class="remark-marker remark-marker-red">marked content</mark>
</p>

The option can take also a callback function, which has an optional argument color, and returns array of strings representing class names.

use(remarkFlexibleMarkers, {
  markerClassName: (color) => {
    return [`marker-${color ?? "yellow"}`]
  };
});

Now, the element class names will contain only one class name like marker-yellow, marker-red etc.

==marked content==
=r=marked content==

<p>
  <mark class="marker-yellow">marked content</mark>
  <mark class="marker-red">marked content</mark>
</p>

[!WARNING] If you use the markerClassName option as a callback function, it is your responsibility to define class names, primary or secondary in an array.

markerProperties

It is a callback (color?: string) => Record<string, unknown> & { className?: never } option to set additional properties for the mark node.

The callback function that takes the color as optional argument and returns object which is going to be used for adding additional properties into the mark node.

The className key is forbidden and effectless in the returned object.

use(remarkFlexibleMarkers, {
  markerProperties(color) {
    return {
      ["data-color"]: color,
    };
  },
});

Now, the mark nodes which have a color classification will contain data-color property.

==marked content==
=r=marked content==

<p>
  <mark class="flexible-marker flexible-marker-default">marked content</mark>
  <mark class="flexible-marker flexible-marker-red" data-color="red">marked content</mark>
</p>

equalityOperator

It is a string option in order not to confuse with mathematical equality operator like if a == b, then ....

If there is a space around double equality in a mathematical text, there is no problem, since the plugin will not match with these.

If a == b and c == d then the theorem is right. --> will not cause any problem.

But, if there is NO space around double equality in a mathematical text, the plugin assumes they are marker but actually not.

If a==b and c==d then the theorem is right. --> will cause the plugin match a marker <mark>b and c</mark>, unwantedly.

In order the plugin to handle this kind of mathematical expressions correctly, there is equalityOperator option.

use(remarkFlexibleMarkers, {
  equalityOperator: "=:=",
});

If a=:=b and c=:=d then the theorem is right

Now, the plugin is going to convert the =:= into == as should be.

<p>If a==b and c==d then the theorem is right</p>

By default, the option is undefined, which means no check happens.

actionForEmptyContent

It is a union "keep" | "remove" | "mark" option to handle marker syntax with empty content in a markdown document.

By default, it is mark, meaningly the plugin will create an empty <mark> node for marker syntax with empty content.

I don't know what could be a reason you use empty markers, but anyway I wanted to handle it. Here is an example marker syntax with empty content.

====, ==  ==, =r===, =r= ==

You have three options to handle marker syntax with empty content.

keep will keep the syntax as it is.

use(remarkFlexibleMarkers, {
  actionForEmptyContent: "keep",
});

will produce:

<p>====, ==  ==, =r===, =r= ==</p>

remove will remove the mark syntax with empty content.

use(remarkFlexibleMarkers, {
  actionForEmptyContent: "remove",
});

will produce:

<p>, , , </p>

mark will crate an empty <mark> node.

use(remarkFlexibleMarkers, {
  actionForEmptyContent: "mark", // actually, it is default
});

will produce <mark> nodes with additional class name "flexible-marker-empty".

<p>
  <mark class="flexible-marker flexible-marker-default flexible-marker-empty"></mark>,
  <mark class="flexible-marker flexible-marker-default flexible-marker-empty"></mark>,
  <mark class="flexible-marker flexible-marker-red flexible-marker-empty"></mark>,
  <mark class="flexible-marker flexible-marker-red flexible-marker-empty"></mark>
</p>

Examples:

Here is ==marked content==

Here is =r=marked content with r classification==

Here are **==bold marked content==** and ==**bold marked content**==

### ==marked content in headings==

Without any option

use(remarkFlexibleMarkers);

is going to produce as default:

<p>
  Here is 
  <mark class="flexible-marker flexible-marker-default">marked content</mark>
</p>
<p>
  Here is 
  <mark class="flexible-marker flexible-marker-red">marked content with r classification</mark>
</p>
<p>
  Here are 
  <strong>
    <mark class="flexible-marker flexible-marker-default">bold marked content</mark>
  </strong>
   and 
  <mark class="flexible-marker flexible-marker-default">
    <strong>bold marked content</strong>
  </mark>
</p>
<h3>
  <mark class="flexible-marker flexible-marker-default">marked content in headings</mark>
</h3>

With options

use(remarkFlexibleMarkers, {
  dictionary: {
    r: "rain",
  },
  markerClassName: "custom-marker",
  markerTagName: "span",
  markerProperties(color) {
    return {
      ["data-color"]: color,
    };
  },
});

is going to produce:

<p>
  Here is 
  <span class="custom-marker custom-marker-default">marked content</span>
</p>
<p>
  Here is 
  <span class="custom-marker custom-marker-rain" data-color="rain">marked content with r classification</span>
</p>
<p>
  Here are 
  <strong>
    <span class="custom-marker custom-marker-default">bold marked content</span>
  </strong>
   and 
  <span class="custom-marker custom-marker-default">
    <strong>bold marked content</strong>
  </span>
</p>
<h3>
  <span class="custom-marker custom-marker-default">marked content in headings</span>
</h3>

[!TIP] You can use the marker syntax in the tables, headings, lists, blockquotes etc. You can have a look at the test files in the github repo for detailed examples.

Syntax tree

This plugin only modifies the mdast (markdown abstract syntax tree) as explained.

Types

This package is fully typed with TypeScript. The plugin options' type is exported as FlexibleMarkerOptions.

Compatibility

This plugin works with unified version 6+ and remark version 7+. It is compatible with mdx version 2+.

Security

Use of remark-flexible-markers does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

My Plugins

I like to contribute the Unified / Remark / MDX ecosystem, so I recommend you to have a look my plugins.

My Remark Plugins

• remark-flexible-code-titles – Remark plugin to add titles or/and containers for the code blocks with customizable properties
• remark-flexible-containers – Remark plugin to add custom containers with customizable properties in markdown
• remark-ins – Remark plugin to add ins element in markdown
• remark-flexible-paragraphs – Remark plugin to add custom paragraphs with customizable properties in markdown
• remark-flexible-markers – Remark plugin to add custom mark element with customizable properties in markdown
• remark-flexible-toc – Remark plugin to expose the table of contents via Vfile.data or via an option reference
• remark-mdx-remove-esm – Remark plugin to remove import and/or export statements (mdxjsEsm)

My Rehype Plugins

• rehype-pre-language – Rehype plugin to add language information as a property to pre element

My Recma Plugins

• recma-mdx-escape-missing-components – Recma plugin to set the default value () => null for the Components in MDX in case of missing or not provided so as not to throw an error
• recma-mdx-change-props – Recma plugin to change the props parameter into the _props in the function _createMdxContent(props) {/* */} in the compiled source in order to be able to use {props.foo} like expressions. It is useful for the next-mdx-remote or next-mdx-remote-client users in nextjs applications.

License

MIT License © ipikuka

Keywords

🟩 unified 🟩 remark 🟩 remark plugin 🟩 mdast 🟩 markdown 🟩 remark marker