wooorm / mdxjs-rs Goto Github PK

View Code? Open in Web Editor NEW

416.0 7.0 14.0 261 KB

Compile MDX to JavaScript in Rust

Home Page: https://docs.rs/mdxjs/

License: MIT License

Rust 100.00%

commonmark gfm javascript markdown mdx rust

mdxjs-rs's Introduction

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

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

mdxjs-rs's People

Contributors

Stargazers

Watchers

Forkers

kwonoj michaeloliverx n1xx1 jridgewell ajstrand christianmurphy kdy1 gismo-stack nicozweifel arcanis tonywu6 prinorange hmthanh stormslowly

mdxjs-rs's Issues

Transforming the code

I'm trying to have Shiki Twoslash support in my mdx files, but I'm not sure it's currently possible.

My idea was to parse the original file as an AST, extract the code fences, send them to JavaScript for processing, and return them back before serializing it into mdx. However, the API here seems to only expose the compile function, which does both parsing and transformation. Would it be reasonable to split them in two operations?

Permission to update swc_core

Hey @wooorm, would you be open to granting @jridgewell, @kwonoj, and @sokra permission to approve and merge pull requests to update swc_core? We have to keep swc_core versions in sync across Next.js, Turbopack, and mdxjs-rs, so this would help our publishing velocity quite a bit.

May I request permission to merge updates of `swc_core` and publish new versions?

For the context, I need to update swc_core quite frequently but updating swc_core of mdxjs-rs takes lots of time.

swc-project/swc#8116

Exposing the interface to return the transformed swc AST?

I'd like to transform MDX to swc AST to make the package I'm working on (tagged-md) to support transforming the content to JSX. Are you open for exposing the interface?

[Feature request] bubble up underlying error as typed

Currently, the interface to compile mdx is like this

compile(value: &str, options: &Options) -> Result<String, String>

If the compilation fails, you'll only get a string error message, and you won't be able to access the actual error (Swc, etc.). With Turbopack, errors that occurred elsewhere can be controlled by a handler in the swc or some other way to show a separate message, which requires the actual error to be readable.

I'm curious if it's considerable to bubble up the actual error from compile, something similar to

compile(...) -> Result<String, CompileError>

CompileError {
  Ecma(E) // swc
  Hast(E) // hast
  Unknown(String) // other, not formed type
}

or could be some way like https://docs.rs/error-stack/latest/error_stack/#multiple-errors using libraries.

Cannot parse the jsx element

I try to excute the following code:

compile("import { Theme } from '@theme'\n <Theme />", &Default::default())

The compile function is exported from src/lib.rs.But it failed, the error log is as follows:

running 1 test
thread 'tests::test_compile' panicked at 'compile: "2:11: Unexpected statement in code: only import/exports are supported"', src/lib.rs:134:88
stack backtrace:
   0: rust_begin_unwind
             at /rustc/2c8cc343237b8f7d5a3c3703e3a87f2eb2c54a74/library/std/src/panicking.rs:575:5
   1: core::panicking::panic_fmt
             at /rustc/2c8cc343237b8f7d5a3c3703e3a87f2eb2c54a74/library/core/src/panicking.rs:64:14
   2: core::result::unwrap_failed
             at /rustc/2c8cc343237b8f7d5a3c3703e3a87f2eb2c54a74/library/core/src/result.rs:1790:5
   3: core::result::Result<T,E>::expect
             at /rustc/2c8cc343237b8f7d5a3c3703e3a87f2eb2c54a74/library/core/src/result.rs:1069:23
   4: mdxjs::tests::test_compile
             at ./src/lib.rs:134:13
   5: mdxjs::tests::test_compile::{{closure}}
             at ./src/lib.rs:132:23
   6: core::ops::function::FnOnce::call_once

Is my usage not correct?