[docs] Convert Gatsby starter blog to MDX

[spences10]

Summary

Add guide for converting the Gatsby starter blog to use MDX

I have put together a brief YouTube video a while back on doing it and made some documentation to go with it, it's a bit dated as it uses the mdx/tag and not mdx/react so will need updating.

I'd also like to cover the use of adding a root-wrapper for styling components.

Motivation

To aid user adoption of using MDX with Gatsby

Halp!

I'm not entirely sure where this can live in the current documentation, anyone able to give guidance?

[marcysutton]

I think some of this work is being done with the move to themes. Hey @amberleyromo, can you chime in on how this might overlap with your efforts already in progress?

[marcysutton]

Sounds like there is no overlap with theme efforts. @gillkyle what do you think about adding this as part of the MDX workflow (#14258)?

[gillkyle]

I think this would be a great addition for sure! (for context I'm currently working on issue #14890 that's sort of just a bigger effort to move the existing guides on the gatsby-mdx site to .org, maybe we reopen #14258 for this)

What do you think @marcysutton if this were added as an Advanced Tutorial? (since I imagine this'd probably be a little more step by step @spences10) The reference guides in the sidebar at Adding Components to Markdown with MDX sort of cover this from a more general approach so I think it could work on its own specific to the Gatsby starter blog.

[marcysutton]

My biggest thought is this: should we just convert the starter blog to MDX for everyone, so they get it by default?

I also agree that a tutorial under "Additional Tutorials" would help those who have already set up a blog pre-MDX.

[spences10]

So after initially logging this issue I tried to convert the starter blog in codesandbox.io to get an idea of the steps involved:

• add gatsby-mdx, @mdx-js/mdx and @mdx-js/react
• replace gatsby-transformer-remark with gatsby-mdx and add the rest of the remark plugins to gatsbyRemarkPlugins in gatsby-mdx

That's the basic steps covered, the next part, adding the root-wrapper is where I came up against some issues initially with gatsby-plugin-typography which I stripped out completely initially then typography.js which completely changes the look of the site, at this point I have to start adding some basic styles back in and have had to restart the codesandbox.io server several times and it's working still.

The next part, adding a root wrap module is where things start to break down, the codesandbox.io project will refuse to start and it becomes unworkable - I'm not really sure at this point if it's the code (more than likely) or codesandbox.io but the speed at which you can iterate is really hampered by this.

So the initial guide I linked, for converting an existing blog to get your own components working in mdx is entirely possible but adding something to wrap all the page elements I have struggled with on several occasions now but I feel will give the most impact as you have the freedom to style every page element of your markdown which wasn't really an option with markdown remark without creating custom html.js which I have always found a bit daunting.

Because of these setbacks I was having I decided to do my own, from 'scratch' blog with mdx at the beginning.

If anyone can give any guidance as to why the starter blog won't play nicely when you add in wrapRootElement to gatsby-browser.js and gatsby-ssr.js then I'd appreciate that and maybe could do the documentation for that specific part and I'd appreciate the guidance past that blocker.

In the meantime I'm going to continue with creating my own documentation for making a blog from scratch with mdx and including styling with styled-components so I have a clear understanding of what's needed.

[marcysutton]

My first recommendation would be to try doing it locally and skipping Codesandbox to eliminate that as a variable. There are also changes coming for plugins and docs this week that would be worth looking into (gatsby-plugin-mdx in this case), in case any dependencies were in flux. I'd be happy to take a closer look with you next week (things are a little wild this week with a big launch and the US holiday 🎇). Thanks for your patience on this!

[eclectic-coding]

It seems there is a lot of momentum MDX documentation at the present. At a minimum, for the end user, it might be helpful to triage the gatsby-plugin-mdx to represent correct installation procedures. Currently, the installation is documented as:

npm install --save gatsby-mdx @mdx-js/mdx @mdx-js/tag @mdx-js/react

This does not reflect gatsby-plugin-mdx and probably should read:

npm install --save gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

These changes may help with users trying to migrate OR install for the first time. Let me know if I can help. Chuck

[marcysutton]

Thanks for the heads up! There's already a PR open to fix those references: https://github.com/gatsbyjs/gatsby/pull/15559

[spences10]

So, an update on where I am with this, this by the way has spawned a whole "lets make a blog from scratch" post from me which is turning out to be a wonderful learning experience. However! Onto this:

My first recommendation would be to try doing it locally and skipping Codesandbox to eliminate that as a variable.

Ok, so after learning that gatsby-plugin-mdx was now a thing and changing my blog and some other pages that used gatsby-mdx I turned to trying again with the starter blog, this time locally, which works.

So, next steps for me are to try do the same on Codesanbox.io, then probably record a video of me doing it then a write up.

The reasoning for Codesandbox.io is the barrier to entry is reduced considerably due to not having to create a dev setup if they haven't got one already running.

[spences10]

Ok, so here's what I have found in relation to getting the Gatsby Starter Blog converted to using MDX .

What was causing the issues previously when I was trying to do this was adding styled-components to the gatsby-starter-blog has some sort of collision with typography:

✖ ｢wdm｣:
ERROR in ./node_modules/gatsby-plugin-typography/.cache/typography.js
Module build failed (from
./node_modules/gatsby/dist/utils/webpack-hmr-hooks-patch.js):
Error: ENOENT: no such file or directory, open
'/sandbox/node_modules/gatsby-plugin-typography/.cache/typography.js'
 @ ./node_modules/gatsby-plugin-typography/gatsby-browser.js 22:25-55
 @ ./.cache/api-runner-browser-plugins.js
 @ ./.cache/api-runner-browser.js
ℹ ｢wdm｣: Failed to compile.

I have the sandbox here if anyone is interested in taking a look.

So, without styled-components we have a working example but I have a feeling that syntax highlighting will also be sought after, this was also causing me issues.

The furthest I got was being able to add a root-wrapper.js so you could add your own page elements, I can add basic styles to h2, h3, etc. It's when I try adding prism-react-renderer I can validate the code works by using the example code from [the GitHub page], here:

import { MDXProvider } from '@mdx-js/react';
import Highlight, { defaultProps } from 'prism-react-renderer';
import React from 'react';

const components = {
  pre: props => (
    <Highlight
      {...defaultProps}
      code={`
        (function someDemo() {
          var test = "Hello World!";
          console.log(test);
        })();

        return () => <App />;
      `}
      language="jsx">
      {({
        className,
        style,
        tokens,
        getLineProps,
        getTokenProps,
      }) => (
        <pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </pre>
      )}
    </Highlight>
  ),
};

export const wrapRootElement = ({ element }) => (
  <MDXProvider components={components}>{element}</MDXProvider>
);

The second issue comes in when I try get the props of the child component by replacing the code example with props.children.props.children:

So, what I can do is cover the element styling and leave out this syntax highlighting until I understand what the issue is.

Thoughts @marcysutton, @gillkyle?

[gillkyle]

Wow, very detailed updates, thanks @spences10 🙂

There's been recent talk of converting the official blog starter to using the blog theme in the future. There's an existing gatsby-theme-blog-starter (that would be eclipsed/replaced by adding the theme to this starter) but then it would include MDX with it and make updates like this package upgrades which would be slick. That could also add syntax highlighting with it so maybe this is worth holding off on since that might solve some of the issues you've been running into 🤷‍♂

That being said, the guide for converting to MDX seems like it could still be beneficial for people that don't want to use the theme or want to see more of the fine tuned stuff you've already learned about that process.

[spences10]

Due to the difficulties I was having with the Gatsby starter blog I decided to do my own documentation from scratch (simple hello world) to fully fledged blog with syntax highlighting and react live code blocks.

It's a basic outline that I still have to break up into sections to record videos for each section to accompany the prose and also some basic styling and layout.

https://github.com/spences10/blog.scottspence.me/blob/authoring/posts/2019/2019-12-31-build-an-mdx-blog/index.mdx

I was thinking if we can't work out what's going on with the starter blog use some of that content, but I guess you have a lot already, right @gillkyle?

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[spences10]

Happy to close this, I see no reason for it to stay open with all the other pieces of working happening around this.

Let me know if you have any objections, otherwise I'll close it before the start of next week 🙏

[gillkyle]

Sounds good thanks @spences10, I think it makes sense to let the other moving parts situate themselves and we can reopen this in the future. Thanks for investigating so much into this. The context helps other issues and PRs like #16166

[ghost]

@spences10 thanks for all your work on this, found this closed issue while I was playing with mdx and react-live all weekend and it's a tougher than I expected to get working with an existing blog! The gatsby-theme-blog is very different than gatsby-starter-blog so that didn't end up being an option to switch over to. Your new tutorial is looking really great!

My biggest thought is this: should we just convert the starter blog to MDX for everyone, so they get it by default?

I also agree that a tutorial under "Additional Tutorials" would help those who have already set up a blog pre-MDX.

I think it is worth considering getting gatsby-starter-blog compatible with mdx by default (suggested by @marcysutton). I was able to do this with a starter I made that is a fork of gatsby-starter-blog: https://github.com/thomaswangio/gatsby-personal-starter-blog/commit/2bef261cb22800ac3c05f9a2e78b6cb27db1a347.

I will try making a PR to add these changes to the gatsby-starter-blog and reference back to this issue.

[spences10]

Thanks @thomaswangio 🙏

That post has taken up a lot of my spare time as of late, it's nearly done too 🎉

For anyone else interested the URL will change when I publish it but the playlist of the videos is here: https://www.youtube.com/playlist?list=PLGi_uHe_v04DRZ58L_0O5cilalymkC7On

Thanks!

Closing again as I think it's been opened again in error.

[ghost]

@spences10 Ahh no sorry I want to re-open to address these 2 issues:

My biggest thought is this: should we just convert the starter blog to MDX for everyone, so they get it by default?

I also agree that a tutorial under "Additional Tutorials" would help those who have already set up a blog pre-MDX.

I will work on some PR's!

[ghost]

Closing this issue now that 2 PR's are in the works :)

[spences10]

So, I'm confused as to why this was initially dismissed when I suggested this but then accepted when you made a PR for it @thomaswangio.

What did I miss that you did not with your contribution?

I thought that there was no need for this but Thomas manages to turn this around...

I'd appreciate some feedback on what I didn’t do that Thomas did.

Thanks

[ghost]

Hey @spences10 the team actually decided to keep it the way it is. The reason I made the PR was because there's no up to date tutorial on converting blogs to MDX (yours was actually one of the most recent and it was still using mdx tag)

https://github.com/gatsbyjs/gatsby/pull/19580#issuecomment-557534847

[laurieontech]

Hey @spences10, I'm going to close this again as the team is still interested in keeping MDX out of the starter blog.

That being said, we now have improved documentation on making the change to MDX and there are additional community starters that incorporate MDX out of the box. If you develop another we'd love to have you add it! https://www.gatsbyjs.org/contributing/submit-to-starter-library/