Ahoy, MDX fans! If you’re reading this I’ll assume you’ve already experienced how absolutely mind blowing MDX is (and if not then please watch this video by the fantastic Prince Wilson and come back after).
I first fell in love with Gatsby back in 2019. One of the many reasons was the vast plugin ecosystem and Gatsby Themes most of all. Gatsby Themes stitch together a plethora of plugins to add pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. You can think of Gatsby themes as separate Gatsby sites that can be assembled together to form a whole, allowing you to split up a larger Gatsby project into modular pieces.
After numerous failed attempts at creating a theme of my own, I finally made something I was proud of. Unfortunately I missed the deadline for last year’s Theme Jam event, but then not long after 100 Days of Gatsby was announced. Ah, ha! I thought, Here’s a great opportunity to get my code out there! And so I set about conjuring up ideas for Gatsby projects to build, blog and tweet about over the full 100 days of the challenge. (If you’re really interested here’s 26,341 words detailing everything I did over the 100 days).
One happy outcome from surviving this challenge: I really got to grips with MDX. The happiest result of all, though, was creating and releasing my first plugin, gatsby-mdx-embed: a Gatsby MDX plugin to embed Twitter, YouTube, Instagram and many more into your .mdx without needing to import anything. (If you’re not already familiar with the Gatsby plugin ecosystem, this handy guide walks you through everything you need to know).
Personally I think that easily allowing the community to write and release plugins for use with Gatsby is an absolute hammer of an idea. It gives Gatsby enthusiasts like myself a way to easily get started with open source by providing a solid foundation for us to build from.
Once you’ve got the plugin basics down you can then really let your imagination run wild. This is kind of what I did in deciding to combine my interest in markdown / MDX with the Gatsby plugin ecosystem.
(Side note: If you’ve ever open sourced anything you’ll probably be aware of how difficult it is to get the project out there. If, like me, you have few Twitter followers it’s hard to reach your potential users. But by building with the Gatsby plugin ecosystem you’ll start off on the right foot because you already have a user base for your project…boogie time).
Throwing down with markdown
I’ve used a number of markdown plugins before and have noticed one or two things I’d want to change if they were mine. Now, instead of moaning about their shortcomings, I decided to do something about it.
Allow me to explain myself.
Just load it
A markdown plugin will typically require you add a URL to your post like this one for CodePen 👇
…and this will indeed recognize /codepen.io/... and then execute the code, which in turn loads a CodePen iframe.
However, what you might not have noticed is that, regardless of where in the page this embed actually lives — be it right at the top or below the fold where a user would have to scroll to see it — additional HTML, CSS and Javascript gets frontloaded into the page in order for the embed to display correctly. Even if the user never actually scrolls down to encounter it. I think of this as the “f**k it, just load it” approach.
All this additional “f**k it” code can lead to poorly performing page load speeds and Lighthouse scores. And, naturally, the more embeds you have on each page, the more this problem gets exaggerated.
A more polite approach
And that is why I thought it would be good to have a plugin that takes a more nuanced approach. In contrast to the standard just load it method, I created MDX Embed to ask “Would you mind awfully if I were to load myself please?” approach. In a manner of speaking, MDX Embed is very polite.
This is possible thanks to MDX Embeds’ use of the Intersection Observer. (In short, the Intersection Observer API “lets code register a callback function that is executed whenever an element they wish to monitor enters or exits another element (or the viewport).” This is necessary for lazy-loading images and other assets and functionality: basically, deferring calling them up until they’re wanted. Right at the heart of MDX Embed, wrapped around every component is what we call the General Observer.
When General Observer reports for duty — in other words, when a component enters the viewport — then and only then does it attempt to load the 3rd party embed script. This is key to ensuring additional code is only loaded as and when required. This method can help keep page load speeds fast and Lighthouse scores high.
First go
My first effort toward a politer MDX Embed plugin focused on a Gatsby-specific version. Gatsby-mdx-embed was just one of the 10 challenges I set for myself during my 100 Days of Gatsby journey. Over the course of the challenge I released a few updates to the project and got some really positive initial feedback. Which was fab, and I was really pleased at least one of these experiments was looking like it might have legs. Gatsby’s own Laurie Barth was actually one of the project’s earliest adopters! (Thanks Laurie, 💜 your support is very much appreciated).
Over time, however, my interest in the project waned a bit. In part this was because I was not completely happy with the repo structure or docs site. Honestly, though, I’d become a little deflated by the lack of interest in the project. This last bit happens, I imagine, for lots of open source developers. So if you are using someone else’s project please do make a note of Tweeting about it and showing your support by adding a Star to the repo. These are small things but, trust me, they can make a world of difference.
(With that said, Scott Spence has been instrumental in keeping me upbeat and keeping the project alive and has contributed a number of times and generally just been a positive influence on both myself and the project. Thanks Scott! 💜)
Then this happened
As an MDX enthusiast I was naturally pretty excited by the announcement of the first ever MDX Conf organized by Chris Biscardi, and when I tuned in I couldn’t believe what I was seeing, both Monica Powell and Kathleen McMahon were talking about and using gatsby-mdx-embed !!! (I then ruined it by making a joke meant for Scott but forgot it was a live stream, apologies again Kathleen 😬).
…Um, anyway, following on from MDX Conf Monica tweeted the following:
With gatsby-mdx-embed you can embed all kinds of things in MDX like Codepens, CodeSandboxes, tweets and even Egghead lessons! Don’t let the name fool you…it can be used outside of Gatsby – @waterproofheart
Monica is absolutely right, gatsby-mdx-embed can and always has been able to work outside of Gatsby. I just hadn’t done a very good job of calling it out in the README. From here both Scott Spence and Rich Haines offered up frequent but friendly encouragement for me to do something about that.
(Rich has been doing quite a bit of work in and around the Next.js / next-mdx projects and has played a prominent role in encouraging MDX Embeds’ usage outside of Gatsby. Thanks Rich 💜).
So the decision was made. MDX Embed needed to move, and as of Friday 28th of August 2020 I archived the ‘gatsby-mdx-embed` repo and set about creating a new universal MDX Embed monorepo. Which I hope will be much more developer friendly and pleasant to maintain and contribute to.
Final form
I’m now pleased to introduce the new home of MDX Embed: https://mdx-embed.com complete with a snazzy new logo designed by Griko Nibras!
This new docs site, which uses the latest version of Storybook, is home to documentation on how to use the components. There are also abundant help snippets to aid users in finding embed codes from various providers, plus a few examples of where and how MDX Embed can be used in other projects and frameworks.
Fear ye not
Gatsby plugin support remains! Now it is its own package called gatsby-plugin-mdx-embed which is really just a child component returned by Gatsbys’ wrapRootElement and has a dependency on the core package mdx-embed
Thanks to the aforementioned mighty ecosystem of Gatsby plugins, to get started with MDX Embed all you really need to do is install the dependencies:
And then add gatsby-plugin-mdx-embed to the gatsby.config.js plugins array:
Alternatively
If you experience any issues with the plugin you can manually add the MDXEmbedProvider to your own gatsby-browser.js and / or gatsby-ssr.js files and return it from wrapRootElement:
Or
If you’re only interested in using one or two of the components in MDX Embed you can import and use them by passing them on to your own MDXProvider:
Furthermore
You could also manually import each component in to a single .mdx file and avoid the provider install altogether:
Jsx
MDX Embed components will also work outside of MDX. If you’re interested in using them in Jsx you can also import and use as you normally would.
The last word
As you can see, this restructure is not just new names for packages. It represents a whole new direction for MDX Embed. Our ethos: MDX Embed should work anywhere MDX works…plus a bonus Jsx usage method for good measure.
We hope in the future MDX Embed will become the de facto method for embedding 3rd party media content in MDX – no import required!
We’re actively working on deploying examples to illustrate the various MDX Embed consumption methods but for now these examples can be found in the repo under examples.
We currently have examples for the following:
- Gatsby
- MDX Deck
- Next MDX Deck
- Next
We’re not quite stable
At the time of writing this post we’ve not quite reached a stable release, and for good reason… tests!
It’s here where we’re calling on the community for help. We’ve been really busy preparing the repo, creating a CODE_OF_CONDUCT and CONTRIBUTING document in preparation for this year’s Hacktoberfest.
If you’re interested in contributing to the project we have an ongoing Umbrella Issue which should be everything you need to get started. In there you can have a browse of any open issues labeled Hacktoberfest.
The plan is for contributors to create both Unit Tests and Integration Tests which once complete should bring us to a stable release of `1.0.0`
Each contributor will be gifted a super cool special edition MDX Embed sticker. They’re limited edition because I’m cheap and only ordered 50, so get involved now before they’re all gone!
Oh, and if you do happen to stop by the repo a cheeky GitHub star ⭐ would be very much appreciated!
The future
The bigger picture plans for MDX Embed are for the larger blogging platforms Medium or dev.to et al to adopt the project, affording authors the ability to embed all the things but in a way that won’t affect site performance. (If anyone reading this has any good ins with either of those sites we’d love to get the conversations going…I mentioned there are stickers…)
…And that’s it for now folks!
If you have any questions, queries or just general ponderings please do reach out to one of us and we’d be happy to help!
- Paul Scanlon | @pauliescanlon
- Scott Spence | @spences10
- Rich Haines | @studio_hungry