Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wooorm/mdxjs-rs

Compile MDX to JavaScript in Rust
https://github.com/wooorm/mdxjs-rs

commonmark gfm javascript markdown mdx rust

Last synced: 2 days ago
JSON representation

Compile MDX to JavaScript in Rust

Awesome Lists containing this project

README 

        
# mdxjs-rs



[![Build][build-badge]][build]

[![Coverage][coverage-badge]][coverage]

[![GitHub][repo-badge]][repo]

[![docs.rs][docs-badge]][docs]

[![crates.io][crate-badge]][crate]



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`][markdown-rs] instead.



This project does not yet support plugins.

To benefit from the unified (remark and rehype) ecosystem, use

[`@mdx-js/mdx`][mdx-js].



## What is this?



This Rust crate works exactly like the npm package [`@mdx-js/mdx`][mdx-js].

It uses the Rust crates [`markdown-rs`][markdown-rs] and [SWC][] to deal with the

markdown and JavaScript inside MDX.



## Questions



*   to learn MDX, see [`mdxjs.com`][mdx-site]

*   for the API, see the [crate docs][docs]

*   for questions, see [Discussions][chat]

*   to help, see [contribute][] or [sponsor][] below



## Contents



*   [Install](#install)

*   [Use](#use)

*   [API](#api)

*   [Project](#project)

    *   [Test](#test)

    *   [Version](#version)

    *   [Security](#security)

    *   [Contribute](#contribute)

    *   [Sponsor](#sponsor)

    *   [Thanks](#thanks)

*   [License](#license)



## Install



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



```sh

cargo add mdxjs

```



## Use



```rs

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.



"###,

            &Default::default()

        )?

    );



    Ok(())

}

```



Yields (prettified):



```javascript

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`](https://docs.rs/mdxjs/latest/mdxjs/fn.compile.html),

[`JsxRuntime`](https://docs.rs/mdxjs/latest/mdxjs/enum.JsxRuntime.html),

[`Options`](https://docs.rs/mdxjs/latest/mdxjs/struct.Options.html),

and a few other structs and enums.



See the [crate docs][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:

    ```sh

    RUST_BACKTRACE=1 cargo run --example lib

    ```

*   format:

    ```sh

    cargo fmt && cargo fix

    ```

*   lint:

    ```sh

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

    ```

*   test:

    ```sh

    RUST_BACKTRACE=1 cargo test

    ```

*   docs:

    ```sh

    cargo doc --document-private-items

    ```



### Version



`mdxjs-rs` follows [SemVer](https://semver.org).



### 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`][contributing] for ways to help.

See [`support.md`][support] for ways to get help.

See [`code-of-conduct.md`][coc] for how to communicate in and around this

project.



### Sponsor



Support this effort and give back by sponsoring:



*   [GitHub Sponsors](https://github.com/sponsors/wooorm)

    (personal; monthly or one-time)

*   [OpenCollective](https://opencollective.com/unified) or

    [GitHub Sponsors](https://github.com/sponsors/unifiedjs)

    (unified; monthly or one-time)



### Thanks



Special thanks go out to:



*   [Vercel][] for funding the initial development



## License



[MIT][license] © [Titus Wormer][author]



[build-badge]: https://github.com/wooorm/mdxjs-rs/workflows/main/badge.svg



[build]: https://github.com/wooorm/mdxjs-rs/actions



[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/mdxjs-rs.svg



[coverage]: https://codecov.io/github/wooorm/mdxjs-rs



[repo-badge]: https://img.shields.io/badge/GitHub-wooorm%2Fmdxjs--rs-brightgreen



[repo]: https://github.com/wooorm/mdxjs-rs



[docs-badge]: https://img.shields.io/docsrs/mdxjs



[docs]: https://docs.rs/mdxjs/



[crate-badge]: https://img.shields.io/crates/v/mdxjs



[crate]: https://crates.io/crates/mdxjs/



[chat]: https://github.com/wooorm/mdxjs-rs/discussions



[license]: license



[author]: https://wooorm.com



[mdx-js]: https://mdxjs.com/packages/mdx/



[mdx-site]: https://mdxjs.com



[markdown-rs]: https://github.com/wooorm/markdown-rs



[swc]: https://swc.rs



[rust]: https://www.rust-lang.org



[vercel]: https://vercel.com



[contribute]: #contribute



[sponsor]: #sponsor



[contributing]: .github/contribute.md



[support]: .github/support.md



[coc]: .github/code-of-conduct.md