recma-mdx-html-override

This package is a unified (recma) plugin that allows selected raw HTML elements to be overridden via MDX components.

unified is a project that transforms content with abstract syntax trees (ASTs) using the new parser micromark. recma adds support for producing a javascript code by transforming esast which stands for Ecma Script Abstract Syntax Tree (AST) that is used in production of compiled source for the MDX.

When should I use this?

Use this plugin when you need to override specific raw HTML elements in MDX using MDXComponents.

In MDX, it's easy to override elements created with Markdown syntax—like ![alt](image.png) for images or ## Heading for headings. However, elements written using raw HTML, such as <img src="image.png" alt="alt"> or <h2>Heading</h2>, cannot be overridden in the same way. recma-mdx-html-override bridges this gap, making it possible to override raw HTML elements just like their Markdown counterparts.

recma-mdx-html-override visits the ESAST elements and focuses on Literals (those starting with lowercase letters or/and contains hypen) in ESAST to make them overridable via MDXComponents. Basically, recma-mdx-html-override modifies Literal parameters in the jsx/jsxs call expressions by converting them to _components.[literal], ensuring they can be overridden. You can find information about valid JSX identifiers (identifiers, wrapper and html tags) that can be passed into MDXComponents and whether they are Literals or a References to an Identifier in @mdx-js/mdx documentation.

If a html raw element is in the content with markdown ("md") format and if the plugin pipeline contains rehype-raw, then the html raw element is already overridable by default via MDXComponents. recma-mdx-html-override is mostly useful for the content in MDX ("mdx") format.

Installation

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

npm install recma-mdx-html-override

or

yarn add recma-mdx-html-override

Usage

Say we have the following file, example.mdx,

# Hi

<img src="image.png" alt="picture" />

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

import { read } from "to-vfile";
import { compile } from "@mdx-js/mdx";
import recmaMdxHtmlOverride from "recma-mdx-html-override";

main();

async function main() {
  const source = await read("example.mdx");

  const compiledSource = await compile(source, {
    recmaPlugins: [[recmaMdxHtmlOverride, {tags: "img"}]],
  });

  return String(compiledSource);
}

Now, running node example.js produces the compiled source like below:

function _createMdxContent(props) {
  const _components = {
    h1: "h1",
+   img: "img",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.h1, {
      children: "Hi"
-   }), "\\n", _jsx("img", {
+   }), "\\n", _jsx(_components.img, {
      src: "image.png",
      alt: "picture"
    })]
  });
}

This allows the img component to be overridden via MDX components: { img: (props) => {/* custom rendering */} }.

Options

There is one option.

export type HtmlOverrideOptions = {
  tags?: string | string[]; // default is undefined
};

Tags

It is a string | string[] option to specify which HTML elements should be made overridable in MDX.

Altough it is optional, the plugin will be effectless if you don't provide the option. recma-mdx-html-override makes only the tags defined via tags option overridable.

use(recmaMdxHtmlOverride, {tags: "video"} as HtmlOverrideOptions);

This makes <video /> elements overridable via MDX components.

Syntax tree

This plugin modifies only the ESAST (EcmaScript Abstract Syntax Tree) as explained.

Types

This package is fully typed with TypeScript. The plugin options is exported as HtmlOverrideOptions.

Compatibility

This plugin works with unified version 6+. It is compatible with mdx version 3+.

Security

Use of recma-mdx-html-override does not involve 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
• 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.

License

MIT License © ipikuka