Context-free output

[pshrmn]

This is a question, so I can move this to Spectrum if that is preferable, but I assumed that the question redirect refers to usage questions.

Question

I'm wondering if using React's context is really necessary with the output of mdx. To put this another way, can mdx-hast-to-jsx produce "pure" outputs that makes @mdx-js/tag unnecessary?

Why?

Right now, the mdx-hash-to-jsx compiler has no idea what custom components are used by an application. MDX gets around this by using the tag name output by the markdown parser and relies on React's context to determine the "real" component at runtime.

While there is nothing inherently wrong with using React's context, I'm also not certain that it is necessary. If the compiler knows how to map the markdown tag names to what the application expects, then that would remove the main purpose of needing to use the context.

Note: The other benefit of React's context is that an application can dynamically alter the mapped components. This would be incompatible with "pure" output. The compiler would need to have branches for context and non-context modules.

Example

This input

# Test

Hurray!

with this (theoretical) configuration

Note: The most complicated step for this would be producing import statements, because:

1. If there is a custom h1 component, an mdx file that uses it would need to import the component (likewise, any mdx files that don't use it should not import it).
2. The import source would need to work with Node's resolution algorithm.

mdx(input, {
  components: {
    h1: {
      component: "CustomH1",
      import: {
        specifier: "CustomH1",
        path: "src/components/CustomH1"
      }
    }
  }
});

would produce this output

import React from "react"

import CustomH1 from "./components/CustomH1"

export default function MDXContent(props) {
  return (
    <div name="wrapper">
      <CustomH1>Test</CustomH1>
      <p>Hurray!</p>
    </div>
  )
}

---

It is entirely possible that I have overlooked reasons that this would not work. I'm not exactly pushing for this to be included (especially at the eleventh hour with v1), but I am curious to know what others think.

[johno]

The short answer ultimately boils down to composition. With your proposed approach there isn't a way for multiple MDX documents in an application tree to have different components get rendered. For example, imagine a large site that has /blog and /docs sections.

At the application level you might have a collection of components that you'd want to be rendered for all elements. However, in the docs you'll want to change code to be a completely different component that has the ability to be a syntax highlighted code block or a live repl. You would only want to include the special code block when it's needed because it brings in a lot of libraries that add substantial weight to the page.

With context you can more granularly dictate which components will be rendered by composing providers:

// src/Layout.js
import React from 'react'
import {MDXProvider} from '@mdx-js/tag'

import mdxComponents from './components/mdx'

export default props => (
  <MDXProvider components={mdxComponents}>
    <main {...props} />
  </MDXProvider>
)

// src/DocsLayout.js
import React from 'react'
import {MDXProvider} from '@mdx-js/tag'

// Super fancy code block with lots of extra functionality
import CodeBlock from './components/CodeBlock'

export default props => (
  <MDXProvider components={{ code: CodeBlock }}>
    <main {...props} />
  </MDXProvider>
)

With the above two layouts, all docs pages can wrap themselves with DocsLayout inside the main application layout to mix in their custom code block. Without composing context this isn't really possible (at least in a straightforward way).

It's also important to note that context isn't exactly required by any means, you could opt out of using it and style everything with CSS and only use custom components with imports.

What's cool with MDX internals, though, is that the type of output you've proposed can be achieved with a custom compiler. Once v1 is shipped I'd be open to even officially supporting this as a plugin. In the long term there's no reason that MDX can't support many different types of output for different usages so for projects where composition isn't necessarily needed, there's no reason that you couldn't grab for a plugin to customize the output.

[pshrmn]

Ah, yes, I hadn't thought about that sort of composition. Thanks! I'll close for now and maybe play around with the idea some more once v1 is shipped.