# recma-mdx-html-override
**A robust Next.js newsletter `Next.js Weekly` is sponsoring me** π
[](https://nextjsweekly.com/)
**An outstanding Git-based CMS `Outstatic` is also sponsoring me** π
[](https://outstatic.com/?utm_source=github&utm_medium=readme&utm_campaign=next-mdx-remote-client)
A warm thanks π to [@ErfanEbrahimnia](https://github.com/ErfanEbrahimnia), [@avitorio](https://github.com/avitorio), [@recepkyk](https://github.com/recepkyk), and [@LSeaburg](https://github.com/LSeaburg) for the [support](https://github.com/sponsors/ipikuka) π
---
[![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 `` 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 `Literal`s (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](https://mdxjs.com/docs/using-mdx/#components).
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
};
```
### 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.
```javascript
use(recmaMdxHtmlOverride, {tags: "video"} as HtmlOverrideOptions);
```
This makes `` 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][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.
### Support My Work ([become a sponsor](https://github.com/sponsors/ipikuka) π)
If you find **`recma-mdx-html-override`** 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](https://github.com/sponsors/ipikuka).
Thank you for supporting open source! π
### My Remark Plugins
- [`remark-flexible-code-titles`](https://www.npmjs.com/package/remark-flexible-code-titles)
β Remark plugin to add titles or/and containers for the code blocks with customizable properties
- [`remark-flexible-containers`](https://www.npmjs.com/package/remark-flexible-containers)
β Remark plugin to add custom containers with customizable properties in markdown
- [`remark-ins`](https://www.npmjs.com/package/remark-ins)
β Remark plugin to add `ins` element in markdown
- [`remark-flexible-paragraphs`](https://www.npmjs.com/package/remark-flexible-paragraphs)
β Remark plugin to add custom paragraphs with customizable properties in markdown
- [`remark-flexible-markers`](https://www.npmjs.com/package/remark-flexible-markers)
β Remark plugin to add custom `mark` element with customizable properties in markdown
- [`remark-flexible-toc`](https://www.npmjs.com/package/remark-flexible-toc)
β Remark plugin to expose the table of contents via `vfile.data` or via an option reference
- [`remark-mdx-remove-esm`](https://www.npmjs.com/package/remark-mdx-remove-esm)
β Remark plugin to remove import and/or export statements (mdxjsEsm)
- [`remark-mdx-remove-expressions`](https://www.npmjs.com/package/remark-mdx-remove-expressions)
β Remark plugin to remove MDX expressions within curlybraces {} in MDX content
### My Rehype Plugins
- [`rehype-pre-language`](https://www.npmjs.com/package/rehype-pre-language)
β Rehype plugin to add language information as a property to `pre` element
- [`rehype-highlight-code-lines`](https://www.npmjs.com/package/rehype-highlight-code-lines)
β Rehype plugin to add line numbers to code blocks and allow highlighting of desired code lines
- [`rehype-code-meta`](https://www.npmjs.com/package/rehype-code-meta)
β Rehype plugin to copy `code.data.meta` to `code.properties.metastring`
- [`rehype-image-toolkit`](https://www.npmjs.com/package/rehype-image-toolkit)
β Rehype plugin to enhance Markdown image syntax `![]()` and Markdown/MDX media elements (``, `
` or `