https://github.com/goodproblems/remark-mdx-math-enhanced

Plugin to allow for math with expressions in MDX
https://github.com/goodproblems/remark-mdx-math-enhanced

Last synced: 3 months ago
JSON representation

Plugin to allow for math with expressions in MDX

• Host: GitHub
• URL: https://github.com/goodproblems/remark-mdx-math-enhanced
• Owner: goodproblems
• License: mit
• Created: 2022-04-24T01:28:41.000Z (over 2 years ago)
• Default Branch: master
• Last Pushed: 2023-01-08T16:10:24.000Z (almost 2 years ago)
• Last Synced: 2024-07-22T20:06:47.467Z (4 months ago)
• Language: TypeScript
• Size: 509 KB
• Stars: 13
• Watchers: 1
• Forks: 0
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Remark MDX math enhanced

> An MDX plugin adding support for math environments with embedded JS expressions

## What is this?

This package allows math environments in MDX documents to contain embedded JavaScript expressions analogous to [MDX expressions](https://mdxjs.com/docs/what-is-mdx/#expressions). These expressions have full access to props, exports, etc.

## How it works

Math nodes produced by [remark-math](https://github.com/remarkjs/remark-math/tree/main/packages/remark-math) are transformed into JSX element nodes at compile time and rendered at run time via a React component which your app is expected to provide (default is `Math` but is configurable)

---

**🚨 Important:** This plugin is quite new and currently still in beta, it's possible the API and/or approach may change so **use at your own risk**.

---

## Notes

- This plugin expects you to define your own `Math` component which will handle rendering. For an example implementation of a `` component using [Katex](http://katex.org) see [examples/Math.js](https://github.com/goodproblems/remark-mdx-math-enhanced/tree/master/examples/Math.js)

- Rendering math at runtime instead of at compile time means that client-side JS is required, and that more browser processing power is required for rendering. Accordingly, this plugin should only be used in cases where dynamic math (i.e. math with JS expressions inside) is actually required

## Install

Install with npm `npm install remark-mdx-math-enhanced`

## Use 

Say we have the following .mdx file where we want to render some math with a generated value of pi times a prop value

```mdx

export const pi = Math.PI

$\js{props.N}\pi = \js{props.N * pi}$

$$

\js{props.N}\pi = \js{props.N * pi}

$$

```

And an MDX setup something like this

```js

import { readFileSync } from 'fs'

import remarkMath from 'remark-math'

import remarkMdxEnhanced from 'remark-mdx-math-enhanced'

import { compileSync } from '@mdx-js/mdx'

const { value } = compileSync(readFileSync('example.mdx'), {

  remarkPlugins: [remarkMath, [remarkMdxEnhanced, { component: 'Math' }]]

})

console.log(value)

```

Will result in something like

```jsx

export const pi = Math.PI

export default function MDXContent(props) {

  return <>

    {String.raw`${props.N}\pi = ${props.N * pi}`}

    {String.raw`${props.N}\pi = ${props.N * pi}`}

  >

}

```

Note how `\js{...}` have been replaced by `${...}` which are valid [string interpolation placeholders](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#string_interpolation).

## API

The default export is `remarkMdxMathEnhanced`.

### `unified().use(remarkMdx).use(remarkMath).use(remarkMdxMathEnhanced[, options])`

Plugin to transform math nodes to JSX element nodes which render math at run time

##### `options`

Configuration (optional).

###### `options.component`

Name of react component which will be used to render math, default is 'Math'

###### `options.startDelimiter`

Start delimiter of JS expressions, default is `\js{`

###### `options.endDelimiter`

Start delimiter of JS expressions, default is `}`