@ipikuka/handlers

A robust Next.js newsletter Next.js Weekly is sponsoring me 💖

A warm thanks 🙌 to @ErfanEbrahimnia, @recepkyk, and @LSeaburg for the support 💖

@ipikuka/handlers is a collection of rehype handlers for markdown / MDX that I used in my many projects.

unified is a project that transforms content with abstract syntax trees (ASTs) using the new parser micromark. rehype is a tool that transforms HTML with plugins. hast stands for HTML Abstract Syntax Tree (HAST) that rehype uses.

@ipikuka/handlers provides custom rehype handlers that is opinionated and well tested for @mdx-js/mdx and related projects like next-mdx-remote and next-mdx-remote-client.

The rehype handlers that exposed by @ipikuka/handlers:

• defList via remark-definition-list
• defListTerm via remark-definition-list
• defListDescription via remark-definition-list
• abbrDefinition which is undefined on behalf of @richardtowers/remark-abbr,
• html a custom handler for removing undefined tags/components

See also Handlers from mdast-util-to-hast.

Installation

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

npm install @ipikuka/handlers

or

yarn add @ipikuka/handlers

Usage

See remark-rehype options.

import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import handlers from "@ipikuka/handlers";

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype, {allowDangerousHtml: true, handlers: handlers() })
  .use(rehypeStringify, {allowDangerousHtml: true})
  .process(source)

Thanks to @ipikuka/handlers, the markdown/mdx content will support abbreviations, definition lists and removing unknown html nodes.

Without @ipikuka/handlers the depicted features will not work.

Options

type Options = {
  format?: "detect" | "md" | "mdx" | null | undefined;
};

format

It is "md" | "mdx" | "detect" | null | undefined option to adjust remark plugins and whether or not to employ recma plugins.

It is optional, and default is mdx.

Examples:

Example with @mdx-js/mdx

import { compile } from "@mdx-js/mdx";
import handlers from "@ipikuka/handlers";

const compiledSource = await compile(source, {
  remarkRehypeOptions: {
    handlers: handlers({ format: "md" })
  }
})

console.log(toc); // now it has table of contents

// ...

Example with next-mdx-remote-client

import { serialize } from "next-mdx-remote-client/serialize";
import handlers from "@ipikuka/handlers";

// ...
const mdxSource = await serialize<TFrontmatter, TScope>({
  source,
  options: {
    mdxOptions: {
      // ...,
      remarkRehypeOptions: {
        handlers: handlers({ format: "md" })
      }
    },
    parseFrontmatter: true,
  },
});

// ...

Example with next-mdx-remote

import { serialize } from "next-mdx-remote/serialize";
import handlers from "@ipikuka/handlers";

const mdxSource = await serialize<TScope, TFrontmatter>(
  source,
  {
    mdxOptions: {
      // ...,
      remarkRehypeOptions: {
        handlers: handlers({ format: "md" })
      }
    },
    parseFrontmatter: true,
  },
);

// ...

Syntax tree

Handlers are utilized in converting mdast (Markdown abstract syntax tree) into hast (HTML abstract syntax tree).

Types

This package is fully typed with TypeScript.

The package exports the type Options.

Compatibility

The handlers that are provided by this package work with unified version 6+, MDX version 3+, next-mdx-remote, next-mdx-remote-client and @next/mdx.

Security

Use of rehype handlers involves creating hast, but doesn't lead to 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.

Support My Work (become a sponsor 🚀)

If you find @ipikuka/handlers or any of my projects is useful and helpful, please consider supporting my work. Your sponsorship means a lot to me and keeps these projects alive and updated! 💖

My sponsors are going to be featured at the very top of the page and proudly displayed on my Sponsor Wall.

Thank you for supporting open source! 🙌

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)
• remark-mdx-remove-expressions – Remark plugin to remove MDX expressions within curlybraces {} in MDX content

My Rehype Plugins

• rehype-pre-language – Rehype plugin to add language information as a property to pre element
• rehype-highlight-code-lines – Rehype plugin to add line numbers to code blocks and allow highlighting of desired code lines
• rehype-code-meta – Rehype plugin to copy code.data.meta to code.properties.metastring
• rehype-image-toolkit – Rehype plugin to enhance Markdown image syntax ![]() and Markdown/MDX media elements (<img>, <audio>, <video>) by auto-linking bracketed or parenthesized image URLs, wrapping them in <figure> with optional captions, unwrapping images/videos/audio from paragraph, parsing directives in title for styling and adding attributes, and dynamically converting images into <video> or <audio> elements based on file extension.

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.
• recma-mdx-change-imports – Recma plugin to convert import declarations for assets and media with relative links into variable declarations with string URLs, enabling direct asset URL resolution in compiled MDX.
• recma-mdx-import-media – Recma plugin to turn media relative paths into import declarations for both markdown and html syntax in MDX.
• recma-mdx-import-react – Recma plugin to ensure getting React instance from the arguments and to make the runtime props {React, jsx, jsxs, jsxDev, Fragment} is available in the dynamically imported components in the compiled source of MDX.
• recma-mdx-html-override – Recma plugin to allow selected raw HTML elements to be overridden via MDX components.
• recma-mdx-interpolate – Recma plugin to enable interpolation of identifiers wrapped in curly braces within the alt, src, href, and title attributes of markdown link and image syntax in MDX.

My Unist Utils and Unified Plugins

I also build low-level utilities and plugins for the Unified ecosystem that can be used across Remark, Rehype, Recma, and other unist-based abstract syntax trees (ASTs).

• unist-util-find-between – Unist utility to find the nodes between two nodes.
• unified-log-tree – Unified plugin to log abstract syntax trees (ASTs) for debugging without mutating.

License

MIT License © ipikuka