remark-flexible-paragraphs

This package is a unified (remark) plugin to add custom paragraphs 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 paragraph in markdown, with alignment support, custom class names, custom classifications, and also additional properties. This plugin also give an option to wrap the paragraph with a container. You can easily center or align paragraphs with the remark-flexible-paragraphs.

Installation

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

npm install remark-flexible-paragraphs

or

yarn add remark-flexible-paragraphs

Usage

~> paragraph content

=> paragraph content to be wrapped in a container

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

I am a normal paragraph
~> I am a flexible paragraph
=> I am a flexible paragraph wrapped in a div

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 remarkFlexibleParagraphs from "remark-flexible-paragraphs";

main();

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

  console.log(String(file));
}

Now, running node example.js yields:\

<p>I am a normal paragraph</p>
<p class="flexible-paragraph">I am a flexible paragraph</p>
<div class="flexible-paragraph-wrapper">
  <p class="flexible-paragraph">I am a flexible paragraph wrapped in a div</p>
</div>

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

<p>I am a normal paragraph ~> I am a flexible paragraph => I am a flexible paragraph wrapped in a div</p>

Further Usage

The way of the usage (it is easy):

1. choose the marker: ~> for paragraph; => for paragraph in a wrapper
2. put the marker ~> or => where the flexible paragraph begins
3. choose the character(s) from the dictionary [a-z0-9] (only lowercase and numbers) for classification
4. each dictionary key has a predefined but customizable classification value
5. put the character(s) into middle of the marker (in order to add classification)
6. it has no alignment by default
7. if you want to center it, use a pipe |
8. if you want to align it to left, use a colon : at the left side
9. if you want to align it to right, use a colon : at the right side
10. if you want to justify it, use a colon : at both sides
11. if there is no classification, but want to align it, use the colon with the pipe:

• for left alignment use :|
• for right alignment use |:
• for justify alignment use :|:
• for justify alignment use ::
• for center alignment use |

~> paragraph with no classification and no alignment

~|> paragraph center-aligned with no classification
~:|> paragraph left-aligned with no classification
~|:> paragraph right-aligned with no classification
~::> paragraph justify-aligned with no classification

=> paragraph in a wrapper with no classification and no alignment

=|> paragraph center-aligned in a wrapper with no classification
=:|> paragraph left-aligned in a wrapper with no classification
=|:> paragraph right-aligned in a wrapper with no classification
=::> paragraph justify-aligned in a wrapper with no classification

~s> classified as "success" with no alignment
~s|> center-aligned and classified as "success"
~|s> center-aligned and classified as "success"
~:s> left-aligned and classified as "success"
~s:> right-aligned and classified as "success"
~:s:> justify-aligned and classified as "success"

~w> classified as "warning" with no alignment
~d> classified as "danger" with no alignment
~i> classified as "info" with no alignment
~n> classified as "note" with no alignment
~t> classified as "tip" with no alignment

~aw> classified as "alert" and "warning" with no alignment
~:aw> left-aligned and classified as "alert" and "warning"
~aw:> right-aligned and classified as "alert" and "warning"
~:aw:> justify-aligned and classified as "alert" and "warning"
~|aw> center-aligned and classified as "alert" and "warning"
~a|w> center-aligned and classified as "alert" and "warning"
~aw|> center-aligned and classified as "alert" and "warning"

=f2c> classified as "framed", "type-2" and "caution" in a wrapper
=:f2c> left-aligned and classified as "framed", "type-2" and "caution" in a wrapper
=f2c:> right-aligned and classified as "framed", "type-2" and "caution" in a wrapper
=:f2c:> justify-aligned and classified as "framed", "type-2" and "caution" in a wrapper
=|f2c> center-aligned and classified as "framed", "type-2" and "caution" in a wrapper
=f|2c> center-aligned and classified as "framed", "type-2" and "caution" in a wrapper
=f2|c> center-aligned and classified as "framed", "type-2" and "caution" in a wrapper
=f2c|> center-aligned and classified as "framed", "type-2" and "caution" in a wrapper

Options

All options are optional and have default values.

type Alignment = "center" | "left" | "right" | "justify";
type RestrictedRecord = Record<string, unknown> & { className?: never };

type Dictionary = Partial<Record<Key, string>>;
type TagNameFunction = (alignment?: Alignment, classifications?: string[]) => string;
type ClassNameFunction = (alignment?: Alignment, classifications?: string[]) => string[];
type PropertyFunction = (alignment?: Alignment, classifications?: string[]) => RestrictedRecord;

use(remarkFlexibleParagraphs, {
  dictionary?: Dictionary; // explained in the options section
  paragraphClassName?: string | ClassNameFunction; // default is "flexible-paragraph"
  paragraphProperties?: PropertyFunction;
  paragraphClassificationPrefix?: string; // default is "flexiparaph"
  wrapperTagName?: string | TagNameFunction; // default is "div"
  wrapperClassName?: string | ClassNameFunction; // default is "flexible-paragraph-wrapper"
  wrapperProperties?: PropertyFunction;
} as FlexibleParagraphOptions)

dictionary

It is a key, value option for providing custom classification for the paragraph 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"
         | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";

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

const dictionary: Dictionary = {
  a: "alert",
  b: "blue",
  c: "caution",
  d: "danger",
  e: "error",
  f: "framed",
  g: "green",
  h: "horizontal",
  i: "info",
  j: "jumbo",
  k: "kindle",
  l: "lokum",
  m: "menu",
  n: "note",
  o: "ordinary",
  p: "pack",
  q: "quantity",
  r: "red",
  s: "success",
  t: "tip",
  u: "unified",
  v: "verticle",
  w: "warning",
  x: "xray",
  y: "yellow",
  z: "zigzag",
  "0": "type-0",
  "1": "type-1",
  "2": "type-2",
  "3": "type-3",
  "4": "type-4",
  "5": "type-5",
  "6": "type-6",
  "7": "type-7",
  "8": "type-8",
  "9": "type-9",
};

You can override the dictionary entries.

use(remarkFlexibleParagraphs, {
  dictionary: {
    w: "white"
  },
});

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

~w> paragraph content

<p class="flexible-paragraph flexiparaph-white">paragraph content</p>

paragraphClassName

It is a string or a callback (alignment?: Alignment, classifications?: string[]) => string[] option for providing custom class name for the paragraph node.

By default, it is flexible-paragraph, and all paragraphs' classnames will contain flexible-paragraph.

A flexible paragraph node contains also secondary class names representing the specification and/or alignment which starts with the prefix flexiparaph-, like flexiparaph-alert or flexiparaph-warning or flexiparaph-align-center. If there is no classification or alignment, then the secondary class name will not take place.

use(remarkFlexibleParagraphs, {
  paragraphClassName: "remark-paragraph",
});

Now, the paragraph nodes will contain remark-paragraph as a className.

~> content
=> content in a container

<p class="remark-paragraph">content</p>
<div class="...">
  <p class="remark-paragraph">content in a container</p>
</div>

The option can take also a callback function, which has two optional arguments alignment and classifications, and returns array of strings representing class names. For example, if the input contains ~:a> content, the parameter alignment would be "left" and the classifications would be ["alert"].

use(remarkFlexibleParagraphs, {
  paragraphClassName: (alignment, classifications) => {
    return [
      "custom-paragraph",
      ...(classifications ? classifications : []),
      ...(alignment ? [alignment] : []),
    ];
  },
});

Now, the paragraph will contain class names like custom-paragraph, custom-paragraph alert center etc.

~> content
~a> content
~|> content

<p class="custom-paragraph">content</p>
<p class="custom-paragraph alert">content</p>
<p class="custom-paragraph center" style="text-align:center">content</p>

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

paragraphClassificationPrefix

It is a string option for providing classification prefix for the paragraph node.

By default, it is flexiparaph, which is added as a prefix like flexiparaph-alert, flexiparaph-align-center etc.

use(remarkFlexibleParagraphs, {
  paragraphClassificationPrefix: "",
});

Now, the paragraph class name will not take any prefix for the classifications and alignment.

~> content
~a> content
~|> content

<p class="flexible-paragraph">content</p>
<p class="flexible-paragraph alert">content</p>
<p class="flexible-paragraph align-center" style="text-align:center">content</p>

paragraphProperties

It is a callback (alignment?: Alignment, classifications?: string[]) => Record<string, unknown> & { className?: never } option to set additional properties for the paragraph node.

The callback function that takes alignment and classifications as optional arguments and returns object which is going to be used for adding additional properties into the paragraph node. For example, if the input contains ~:a> content, the parameter alignment would be "left" and the classifications would be ["alert"].

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

use(remarkFlexibleParagraphs, {
  paragraphProperties(alignment, classifications) {
    return {
      title: classifications,
      ["data-align"]: alignment,
    };
  },
});

Now, the paragraph nodes which have a classification will contain title property, which have an alignment will contain data-align property.

~> content
~a:> content

<p class="...">content</p>
<p class="..." title="alert" data-align="right">content</p>

wrapperTagName

It is a string or a callback (alignment?: Alignment, classifications?: string[]) => string option for providing custom HTML tag name for the wrapper nodes.

By default, it is div which is well known HTML element for containers.

use(remarkFlexibleParagraphs, {
  wrapperTagName: "section",
});

Now, the wrapper tag names will be section.

<section class="...">
  <p class="flexible-paragraph">content</p>
</section>

The option can take also a callback function, which has optional arguments alignment and classifications, and returns string representing the custom tag name. For example, if the input contains =a> content, the parameter alignment would be undefined and the classifications would be ["alert"].

use(remarkFlexibleParagraphs, {
  wrapperTagName: (alignment, classifications) => {
    return classifications?.includes("alert") ? "section" : "div"
  },
});

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

=> content
=a> content

<div class="...">
  <p class="flexible-paragraph">content</p>
</div>
<section class="...">
  <p class="flexible-paragraph flexiparaph-alert">content</p>
</section>

wrapperClassName

It is a string or a callback (alignment?: Alignment, classifications?: string[]) => string[] option for providing custom class name for the wrapper node.

By default, it is flexible-paragraph-wrapper, and all wrappers' classnames will contain flexible-paragraph-wrapper.

use(remarkFlexibleParagraphs, {
  wrapperClassName: "remark-wrapper",
});

Now, the wrapper nodes will contain remark-wrapper as a className.

=a> content in a wrapper

<div class="remark-wrapper">
  <p class="...">content in a wrapper</p>
</div>

The option can take also a callback function, which has two optional arguments alignment and classifications, and returns array of strings representing class names. For example, if the input contains =w:> content, the parameter alignment would be "right" and the classifications would be ["warning"].

use(remarkFlexibleParagraphs, {
  wrapperClassName: (alignment, classifications) => {
    return alignment 
      ? [`custom-paragraph-${alignment}`]
      : [ "custom-paragraph"];
  },
});

Now, the wrapper class names will contain a class name like custom-paragraph, custom-paragraph-center etc.

=> content
=|> content

<div class="custom-paragraph">
  <p class="...">content</p>
</div>
<div class="custom-paragraph-center">
  <p class="..." style="text-align:center">content</p>
</div>

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

wrapperProperties

It is a callback (alignment?: Alignment, classifications?: string[]) => Record<string, unknown> & { className?: never } option to set additional properties for the wrapper node.

The callback function that takes alignment and classifications as optional arguments and returns object which is going to be used for adding additional properties into the wrapper node. For example, if the input contains =:aw:> content, the parameter alignment would be "justify" and the classifications would be ["alert", "warning"].

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

use(remarkFlexibleParagraphs, {
  wrapperProperties(alignment, classifications) {
    return {
      title: classifications,
      ["data-align"]: alignment,
    };
  },
});

Now, the wrapper nodes which have a classification will contain title property, which have an alignment will contain data-align property.

=> content
=a:> content

<div class="...">
  <p class="...">content</p>
</div>
<div class="..." title="alert" data-align="right">
  <p class="...">content</p>
</div>

Examples:

~> Standard flexible paragraph
=:a:> Alert paragraph justified in a wrapper
~:s> Success paragraph left-aligned
=|> Centered paragraph in a wrapper

Without any option

use(remarkFlexibleParagraphs);

is going to produce as default:

<p class="flexible-paragraph">Standard flexible paragraph</p>
<div class="flexible-paragraph-wrapper">
  <p
    class="flexible-paragraph flexiparaph-alert flexiparaph-align-justify"
    style="text-align:justify"
  >
    Alert paragraph justified in a wrapper
  </p>
</div>
<p
  class="flexible-paragraph flexiparaph-success flexiparaph-align-left"
  style="text-align:left"
>
  Success paragraph left-aligned
</p>
<div class="flexible-paragraph-wrapper">
  <p class="flexible-paragraph flexiparaph-align-center" style="text-align:center">
    Centered paragraph in a wrapper
  </p>
</div>

With options

use(remarkFlexibleParagraphs, {
  dictionary: {
    s: "solid",
  },
  paragraphClassName: "custom-paragraph",
  paragraphClassificationPrefix: "paraflex",
  wrapperTagName: "section",
  wrapperClassName: "custom-paragraph-wrapper",
  wrapperProperties(alignment, classifications) {
    return {
      ["data-alignment"]: alignment,
      ["data-classifications"]: classifications,
    };
  },
});

is going to produce:

<p class="custom-paragraph">Standard flexible paragraph</p>
<section class="custom-paragraph-wrapper" data-alignment="justify" data-classifications="alert">
  <p class="custom-paragraph paraflex-alert paraflex-align-justify" style="text-align:justify">
    Alert paragraph justified in a wrapper
  </p>
</section>
<p class="custom-paragraph paraflex-solid paraflex-align-left" style="text-align:left">
  Success paragraph left-aligned
</p>
<section class="custom-paragraph-wrapper" data-alignment="center">
  <p class="custom-paragraph paraflex-align-center" style="text-align:center">
    Centered paragraph in a wrapper
  </p>
</section>

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 FlexibleParagraphOptions.

Compatibility

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

Security

Use of remark-flexible-paragraphs 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-paragraphs – 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 paragraph