markdown within javascript

[scubamaggo]

Is there a way to make strings within javascript be evaluated using the markdown syntax?

Taking from the official documentation, could I get this

export const Thing = () => '# World'

<Thing />

to evaluate to this html?

<h1> World</h1>

Why is this interesting?

In a lot of my cases, it would be handy to define some data using javascript and access it from various places in my mdx files.

For example, I could define some data like this

export const data = [
    {    
        key:            'Orange',
        color:          '#7e59ff',
        note:          '# Hello World'
        order:          '1',
    },
    {    
        key:            'Apple',
        color:          '#3352FF',
        note:          '## hello small world'
        order:          '2',
    },
]

and pass this to components, possible filtered, or simply use them in the mdx file. For example

{data[0].note}

Big things to be done

or to use them directly with something like Table component from ant design

export const columns = [
  {
    title: 'Note',
    dataIndex: 'note',
    key: 'note',
  },
]

<Table dataSource={data} columns={columns} />;

[ChristianMurphy]

The most idiomatic approach in MDX would be to have two MDX files.
A component file thing.mdx (which can also include props) and a page/document MDX file which imports thing.mdx and uses it as a component.
This approach is already supported today.

thing.mdx

# Hello {props.place}

document.mdx

import Thing from './thing.mdx'

<Thing place="world" />

---

The syntax you propose, is not something MDX core supports, nor do I think core should support it.
Not all JavaScript strings are MDX nor should they be interpreted as such.

Having a plain text strings is a valid use case, and a common one as well, for example:

export const frontmatter = { key: 'value' }

Trying to support string either as MDX or plain text within a document with a heuristic, would likely cause confusion and unexpected errors, rather than improving the developer experience.

---

Instead something that clearly differentiates between plain text and mdx text could be used. (though would be less idiomatic than using two files)
For example, it could be differentiated by using a function call:

export const Thing = () => mdx.evaluate('# World')

<Thing />

or by using a template tag function:

export const Thing = () => mdx`# World`

<Thing />

Both of which could be supported today by importing mdx into the runtime. (this would be slower as it would include the runtime client side).

[scubamaggo]

Thank you @ChristianMurphy for this very detailed and helpful answer. I now see that I can probably accomplish all or most of what I need with the idiomatic approach you suggest.

One clarifying question regarding the use of something like ant design's Table component inside mdx.
If the usage is

<Table dataSource={dataSource} columns={columns} />;

with dataSource and columns being JavaScript Arrays, the only way I have of generating mdx-evaluated content inside this table is to use the client side runtime, correct?

[ChristianMurphy]

with dataSource and columns being JavaScript Arrays, the only way I have of generating mdx-evaluated content inside this table is to use the client side runtime, correct?

There are a few options.

The most ergonomic approach would likely be leveraging the JSX part of MDX, and including the h1 and h2 for the formatting (which is minimal in the given example) inline:

document.mdx

import { Table } from "antd";
import Hello1 from "./hello1.mdx";
import Hello2 from "./hello2.mdx";

export const data = [
  {
    key: "Orange",
    color: "#7e59ff",
    note: <h1>Hello World</h1>,
    order: "1",
  },
  {
    key: "Apple",
    color: "#3352FF",
    note: <h2>hello small world</h2>,
    order: "2",
  },
];

<Table data={data} />;

---

If using markdown, even for the little snippets is a must and you want to avoid the runtime, using files would be possible:

hello1.mdx

# Hello World

hello2.mdx

## hello small world

document.mdx

import { Table } from "antd";
import Hello1 from "./hello1.mdx";
import Hello2 from "./hello2.mdx";

export const data = [
  {
    key: "Orange",
    color: "#7e59ff",
    note: <Hello1 />,
    order: "1",
  },
  {
    key: "Apple",
    color: "#3352FF",
    note: <Hello2 />,
    order: "2",
  },
];

<Table data={data} />;

---

The final option would indeed be to embed the parser and compiler:

document.mdx

import { Table } from "antd";
import { evaluateSync } from "@mdx-js/mdx";

export const data = [
  {
    key: "Orange",
    color: "#7e59ff",
    note: evaluateSync("# Hello World"),
    order: "1",
  },
  {
    key: "Apple",
    color: "#3352FF",
    note: evaluateSync("## hello small world"),
    order: "2",
  },
];

<Table data={data} />;