$3

If you find recma-mdx-html-override useful in your projects, consider supporting my work.
Your sponsorship means a lot 💖

Be the first sponsor and get featured here and on my sponsor wall.
Thank you for supporting open source! 🙌

recma-mdx-html-override

[![npm version][badge-npm-version]][url-npm-package]
[![npm downloads][badge-npm-download]][url-npm-package]
[![publish to npm][badge-publish-to-npm]][url-publish-github-actions]
[![code-coverage][badge-codecov]][url-codecov]
[![type-coverage][badge-type-coverage]][url-github-package]
[![typescript][badge-typescript]][url-typescript]
[![license][badge-license]][url-license]

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

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

When should I use this?

Use recma-mdx-html-override when you need to override specific raw HTML elements in MDX using MDXComponents.

It's easy to override elements created with Markdown syntax—like !alt for images or ## Heading for headings in MDX. However, elements written with raw HTML, such as or

Heading

, 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:

``bash
npm install recma-mdx-html-override
`

or

`bash
yarn add recma-mdx-html-override
`

Usage

Say we have the following file, example.mdx,

`mdx


Hi


`

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

`javascript
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:

`diff
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.

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

$3

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.

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

This makes

Syntax tree

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

Types

This package is fully typed with [TypeScript][url-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.

$3

- 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)

$3

- 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 (,

with optional captions, unwrapping images/videos/audio from paragraph, parsing directives in title for styling and adding attributes, and dynamically converting images into