importMDX Helper

[avigoldman]

Proposal

Right now there are 3 clear ways to use MDX.

1. Import the component directly (The "natural" way)
2. Add in an MDX file in the pages/ directory
3. Query the MDX files via GraphQL and use the createPage action to create the pages

We could add a 4th way – an importMDX helper that would let people get MDX components from GraphQL queries in their page components.

import React from 'react'
import { graphql } from 'gatsby'
import { importMDX } from 'gatsby-mdx'

const MyPage = ({ data: { mdx: { component } } }) => {
  const MyMarkdown = importMDX(component)

  return (
    <div>
      <MyMarkdown />
    </div>
  )
}

export default MyPage


export const pageQuery = graphql`
  query MyPageQuery {
    mdx {
      component
    }
  }
`

Thoughts on adding in a importMDX helper for loading MDX components from GraphQL queries?

[ChristopherBiscardi]

mmm yeah, there's probably going to be something like this. My big question is how the other sources work. If you're querying the graphql for mdx, then presumably you could also send it through the webpack loader right? I'm not super familiar with the other source plugins though and we'd probably need the mime-db PR to operate on other sources. Do other sources get persisted to disk? Can we just require them? Then the graphql query is mostly for metadata (and filesystem location) and every works just like the "natural" way too.

but, mdx also works in the browser, so maybe instead of querying for the component, you query for the raw(ish) source (minus frontmatter) and the importMDX component just calls mdx.sync?

[avigoldman]

I don't think this can function like other plugins since they source new nodes/fields into GraphQL, where we need to end up with a React component.

I like the idea of querying the source and then calling mdx.sync but I'm not sure that would play nicely with imports inside the MDX source.

[ChristopherBiscardi]

I'm actually having trouble coming up with a use case for being able to query the code and use it as a component. The ones I can come up with are overly convoluted and I can think of better ways to accomplish them (straight code imports, a structured JSON data, etc).

On the other hand, I do see a lot of use cases for being able to query the metadata (excerpts, time to read, etc).

Do you have a good use case in mind that we can target this functionality toward?

I also keep coming back to some kind of "createComponent" type API (similar to createPage, but I'd like to hear a solid use case first so I can focus my thoughts a bit better.

[avigoldman]

The only example I can find where this would be used so far is the React website. They query multiple markdown files and use them to build each row of the home page. https://github.com/reactjs/reactjs.org/blob/master/src/pages/index.js#L404

But with MDX, it would be dramatically easier since they could import the files as components and skip the query.

I'm thinking that this might be a non-issue. Unless we can think of a good reason for this, I'm for closing this issue and removing the code GraphQL field.

[ChristopherBiscardi]

I'd hold off on removing the field. Maybe just have it there undocumented for some enterprising soul to find a solid use case (or my own experiments to find one lol).

The best argument I can see for this is that it's what users want to do and if they keep running into "this is how I expect it to work and it doesn't work this way" then we could put more effort into supporting it.