remark-flexible-markers

This package is a unified (remark) plugin to add custom marker in a flexible way (compatible with new parser "micromark").

"unified" is a project that transforms content with abstract syntax trees (ASTs). "remark" adds support for markdown to unified. "mdast" is the markdown abstract syntax tree (AST) that remark uses.

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 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 element with the remark-flexible-markers.

Installation

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

npm install remark-flexible-markers

or

yarn add remark-flexible-markers

Usage

use == or =[classification key]=

==marked content==

=r=marked content with red classification==

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

==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></p>

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

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

Dictionary

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

Options

All options are optional and have default values.

use(remarkFlexibleMarkers, {
  dictionary?: Dictionary; // optional, default is represented above
  markerTagName?: string; // optional, default is "mark"
  markerClassName?: string; // optional, default is "flexible-marker"
  markerProperties: (color: string) => Record<string, unknown>, // optional, default is undefined
});

dictionary

It is an key, value option for providing color classification value for the mark node. If you provide dictionary: {w: "wall"}, it overrides to the only w key, and the value would be "wall" instead of default one "white".

markerTagName

It is a string option for providing custom HTML tag name for the mark node other than mark.

markerClassName

It is a string option for providing custom className for the mark node other than flexible-marker.

markerProperties

It is an option to set additional properties for the mark node. It is a callback function that takes the color as optional argument and returns the object which is going to be used for adding additional properties into the mark node. If you input for example as =r=, the param color would be "red".

Examples:

Here is ==marked content==

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

Here is **==bold and marked content==**

### Heading with ==marked content==

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 red classification</mark></p>
<p>Here is <strong><mark class="flexible-marker flexible-marker-default">bold and marked content</mark></strong></p>
<h3>Heading with <mark class="flexible-marker flexible-marker-default">marked content</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 red classification</span></p>
<p>Here is <strong><span class="custom-marker custom-marker-default">bold and marked content</span></strong></p>
<h3>Heading with <span class="custom-marker custom-marker-default">marked content</span></h3>

You can use the marker syntax in the tables, headings, lists, blockquotes etc. For detailed examples, you can have a look at the test files in the github repo.

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 Remark Plugins

The remark packages I have published are presented below:

• 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-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-ins – Remark plugin to add ins element in markdown

License

MIT © ipikuka

Keywords

unified remark remark-plugin mdast markdown remark marker