Use mdx instead of markdown-to-jsx.

[jbovenschen]

Before I would submit a PR to react-styleguidist I want to know what your opinion would be about using mdx instead of markdown-to-jsx.

It would basically works the same as markdown-to-jsx, only that it comes with some more handy features to customize the templates.

The problem
It is now not possible to import custom components within styleguidist without overwriting the internal Markdown component from rsg-components.

With mdx the following would become possible;

import Graph from './components/graph'

## Here's a graph

<Graph />

Proposed solution
Adding the webpack mdx loader to the core webpack config.

[sapegin]

It is now not possible to import custom components within styleguidist without overwriting the internal Markdown component from rsg-components.

Could you elaborate on that? You can require any component inside an example now. And imports won't work anyway, because Buble doesn't support them.

It would basically works the same as markdown-to-jsx

It would be a breaking change — users will have to rewrite all their examples, it would make viewing Markdown files as Markdown (for example on GitHub) impossible, because examples are just text. We need to have a very good reason for this change and so far I don't see any.

only that it comes with some more handy features to customize the templates.

From your examples I only see one feature: execute any code without rendering it, which wouldn't be hard to support with a new modifier.

[jbovenschen]

It is now not possible to import custom components within styleguidist without overwriting the internal Markdown component from rsg-components.
Could you elaborate on that? You can require any component inside an example now. And imports won't work anyway, because Buble doesn't support them.

As an example wtih markdown-to-jsx I need to do the following;

    <Markdown
        children={md}
        options={{
            overrides: {
                ColorPalette: {
                    component: ColorPalette,
                },
            },
        }} />

And then I can use the following within my markdown files;

# Colors

<ColorPalette />

It works but it will be directly available within every markdown template.
When using mdx I could do the following;

import ColorPalette from './components/ColorPalette';

# Colors

<ColorPalette />

So the import will only available within the markdown template where you do need it.

And imports won't work anyway, because Buble doesn't support them.
I don't see what Buble have to do with it? If I am correct the markdown files are rendered with the following steps;

1. Styleguide-loader identifies all components and doc files
2. Those are put on a global variable (window)
3. Styleguidist renders the whole tree.
4. Styleguidist calls markdown-to-jsx with the markdown content which is on the global variable.
5. Markdown-to-jsx converts the code blocks to editor (In which buble runs).

The same thing is viable with mdx, the only main difference I see at this moment is that the Markdown will be converted on compile time instead of run-time.

It would be a breaking change

It would If users did overwrite the Markdown component in styleguidist.
But in the advanced documentation it is described as the following (If you would really need it);

Note: these components are not guaranteed to be safe from breaking changes in react-styleguidist updates.

So I thought it could be viable to make the proposed changes.

[sapegin]

When using mdx I could do the following;

You can do the same now:

const ColorPalette = require('./components/ColorPalette').default;
<ColorPalette />

We only use markdown-to-jsx to render Markdown, examples are rendered separately and we have to transpile the code before running it in the browsers (we use Buble for that).

[jbovenschen]

@sapegin I didn't know that, for me this was the only / main reason to request this change. Thank you for the quick response.

This would look as following in the markdown if I understand you correctly.

```js no-editor
const ColorPalette = require('./components/ColorPalette').default;
<ColorPalette />

Mdx is also only used to render the Markdown it would not have anything to do with the code examples.