Hi, my name is Kathleen McMahon and I’m here today to tell you how Gatsby and MDX makes component library documentation… smoothly inclusive
Before we begin, let’s get some details out of the way
My slide deck will be posted on Notist, including links to resources I briefly touch upon.
The full URL will be available later today on Twitter.
You can follow me at. Resource11 on Twitter, Instagram, and GitHub.
Mostly you’ll see me in costume, racing two laps to your six, at the back of the pack, on a singlespeed.
Mostly. Unless something happens.
So while I’m an engineer, and a super slow bike racer…
Before working for CarGurus, I was the Tech Lead for O’Reilly Media’s design system.
While I was there, I learned a lot about streamlining component libraries, and optimizing documentation.
If you’ve never worked on a design system, let’s just say… There are a lot of moving parts.
And if your core team is small — and you’re rebooting your component library — you really have to choose your focus. And… rely on your contributors.
In our case, our focus was business logic out, accessibility in. We fixed our colors, our components, our patterns, and rebooted our docs.
Once that was done, we realized that a part of our system was becoming a hindrance for our team, and a barrier to entry for our contributors: our documentation.
Our process was spread across two projects: the design-system repo, and the design-system-docs repo.
In the design-system repo, the documentation content was stored…
To get up and running, you had to follow a detailed series of steps to sync, run scripts, grab files, parse information, generate data, and render the docs to a React app. Phew!
Just getting starting working with these repos was overwhelming for new contributors to say the least…
But wait there’s more!
The scripts were set up in such a way that you had to write your Markdown in a very specific order for your content to show up in the docs.
Your Button heading could be paired with an intro paragraph, but only one paragraph.
Same with your variants. Only one paragraph, and then a code block.
So while our docs scripts were great for of generating color swatches and details about which props were available in components…
One mistake, and parts if not whole chunks of documentation would be missing on the component pages. We had the freedom of using markdown, yet weren’t taking advantage of it.
This was a serious cognitive lift, even for someone who is very familiar with the codebase
One of our biggest issues: we chose to show one component variant at a time, rather than all at once.
This forced users to access a select menu over and over to compare variants, which increased the time they needed to look up information. It didn’t make sense.
In retrospect, that decision was about as questionable as a recipe that combines Jello with shellfish
We decided that it was time to make our docs contribution process more user friendly, in terms of the structure, and how we authored.
Especially the component example pages. We wanted the users to have confidence that whatever content they wrote in a docs page
If we made our docs more user friendly, we’d have more contributors rather than fewer.
We considered our options for making our docs better, and decided upon Gatsby for a few reasons.
Gatsby gave us a way to migrate all our main documentation pages right into the site without much fuss.
Gatsby provides a Webpack and Babel config similar to create-react-app, so we could start with a scaffolded project, and extend as needed. And…
Gatsby supports MDX, so we could write component documentation using Markdown, import React components right in the file, and it just works. Even better, MDX compiles down into…
Semantic HTML. Which in turn, gives the site…
Improved accessibility. Better support for users that rely on assistive technology to access the docs.
If a design system is promoting inclusivity in general — and it really should — it follows that inclusive docs makes sense.
As a bonus, with Gatsby we streamlined our setup from two repos to one, and…
The default setup for Gatsby is great, however, we needed to make some adjustments so Gatsby worked for our needs.
gatsby-plugin-mdx, so the site would recognize MDX files.
gatsby-remark-autolink-headers, to generate auto links for page headings for better screen reader and keyboard support…
And gatsby-plugin-filesystem so we could pull in our data file, and…
…we added things we wanted to apply throughout the site, like our global CSS styles and the wrap-root-element component.
…And imports MDXProvider. This way, the entire site would recognize MDX content.
We had to do one extra thing for our component docs page template, though.
Since our component MDX files were located outside of the src/pages folder, MDXRenderer needed to wrap the contents of our component page template.
Otherwise, the MDXs file would render…
Now that our layout template used MDXRenderer, our component MDX pages…
…And they would render, no problem.
…Popped that component into the docs MDX file, passed in the name of the component to render…
With MDX support, we instead created a custom component that renders unordered lists.
Code blocks. Markdown has great code block support. MDX makes those even more powerful, so we were psyched to add this feature.
You can override the styling of a code block in an MDX file with a custom code block, or even display different types of code blocks.
You can use prism-react-renderer in a custom CodeBlock component and import a theme with good color contrast…
…And override the default pre styling at the app level by passing it in as a component to the wrapRootElement.
Fun fact: you can pass in a prop to that code block and do really cool things if you use custom code blocks!
For example, if you abstract this MDX into a DRYer pattern into our custom CodeBlock component…
You’ll get a display box paired with a code block.
What about if you want your code block to be an editable code block?
…You’ll get an editable block, and see your changes in real time.
… So if we write something like this… this is what you see in the app.
[open live demo]
Here’s a side-by-side example of the three options, the live editable code block is the top block here.
If your documentation setup is brittle, your contributors will flee…
https://noti.st/resource11
Slide deck posted after the talk
@resource11 Twitter | Instagram | GitHub
Hi, my name is Kathleen McMahon and I’m here today to tell you how Gatsby and MDX makes component library documentation… smoothly inclusive
Before we begin, let’s get some details out of the way