mdxjs-rs

Compile MDX to JavaScript in Rust.

When should I use this?

You can use this crate when you’re dealing with the Rust language and want to compile MDX to JavaScript. To parse the MDX format to a syntax tree, use markdown-rs instead.

This project does not yet support plugins. To benefit from the unified (remark and rehype) ecosystem, use @mdx-js/mdx.

What is this?

This Rust crate works exactly like the npm package @mdx-js/mdx. It uses the Rust crates markdown-rs and SWC to deal with the markdown and JavaScript inside MDX.

Questions

• to learn MDX, see mdxjs.com
• for the API, see the crate docs
• for questions, see Discussions
• to help, see contribute or sponsor below

Contents

• Install
• Use
• API
• Project
  • Test
  • Version
  • Security
  • Contribute
  • Sponsor
  • Thanks
• License

Install

With Rust (rust edition 2018+, ±version 1.56+), install with cargo:

cargo add mdxjs

Use

extern crate mdxjs;

fn main() -> Result<(), markdown::message::Message> {
    println!(
        "{}",
        mdxjs::compile(
            r###"
import {Chart} from './snowfall.js'
export const year = 2018

# Last year’s snowfall

In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.

<Chart year={year} color="#fcb32c" />
"###,
            &Default::default()
        )?
    );

    Ok(())
}

Yields (prettified):

import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
import {Chart} from './snowfall.js'
export const year = 2018

function _createMdxContent(props) {
  const _components = Object.assign({h1: 'h1', p: 'p'}, props.components)
  return _jsxs(_Fragment, {
    children: [
      _jsx(_components.h1, {children: 'Last year’s snowfall'}),
      '\n',
      _jsxs(_components.p, {
        children: [
          'In ',
          year,
          ', the snowfall was above average.\nIt was followed by a warm spring which caused\nflood conditions in many of the nearby rivers.'
        ]
      }),
      '\n',
      _jsx(Chart, {year: year, color: '#fcb32c'})
    ]
  })
}

function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || {}
  return MDXLayout
    ? _jsx(MDXLayout, Object.assign({}, props, {children: _jsx(_createMdxContent, props)}))
    : _createMdxContent(props)
}

export default MDXContent

API

mdxjs-rs exposes compile, JsxRuntime, Options, and a few other structs and enums.

See the crate docs for more info.

Project

Test

mdxjs-rs is tested with a lot of tests. These tests reach all branches in the code, which means that this project has 100% code coverage.

The following bash scripts are useful when working on this project:

• run examples:

  RUST_BACKTRACE=1 cargo run --example lib

• format:

  cargo fmt && cargo fix

• lint:

  cargo fmt --check && cargo clippy --all-targets

• test:

  RUST_BACKTRACE=1 cargo test

• docs:

  cargo doc --document-private-items

Version

mdxjs-rs follows SemVer.

Security

MDX is a programming language. It is JavaScript. It is not safe to let people you don’t trust write MDX.

Contribute

See contributing.md for ways to help. See support.md for ways to get help. See code-of-conduct.md for how to communicate in and around this project.

Sponsor

Support this effort and give back by sponsoring:

• GitHub Sponsors (personal; monthly or one-time)
• OpenCollective or GitHub Sponsors (unified; monthly or one-time)

Thanks

Special thanks go out to:

• Vercel for funding the initial development

License

MIT © Titus Wormer