Smoothly Inclusive Component Library Documentation

How to Develop your Web App Connect with other web developers How to develop your web app Create a website How to create a website How to create a website How to create a website Create a website How to create a website How to create a website How to create a website How to create a website

Hello, my name is Kathleen McMahon and I'm here today to tell you how Gatsby and NDX make your component library documentation smoothly inclusive. Before we begin, let's get some details out of the way. My slide deck will be posted on Noticed including links to resources that I briefly touch upon. The full URL will be available later today on Twitter. But for now, if you want to download, if you want to take a look, you can look at https://noti.st r-e-s-o-u-r-c-e-1-1 You can also find me at resource11 on Twitter, Instagram and GitHub.

Before we dig into GaspianMDX, let's back up a bit so I can introduce myself a little bit better. I'm a principal engineer at CarGurus and I race bikes, very badly. Mostly, you'll see me in costume racing two laps to your six at the back of the pack on a single-speed bike, mostly, unless something happens, like a pandemic kicking in our doors. Then, your racing season is postponed. So, while I'm an engineer and a super slow bike racer, I am a super fan of design systems, especially the component library parts. Before CarGurus, I was a tech lead for the O'Reilly Media 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 before, let's just say there are a lot of moving parts. And if your core team is small and you are rebooting your component library, you really have to choose your focus and rely on your contributors. In our case, our focus was to extract the business logic out of our components and get the accessibility in. We fixed our colors, our components, our patterns, and rebooted our docs. Once that was done, we realized that part of our system was becoming a hindrance to 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 in two locations while the docs repo held the site scaffolding and the docs layout components. 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 into a React app. Ooh, that's a lot. Just getting started 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 component and your content to show up in the docs. Your button heading could be paired with an intro paragraph but only one paragraph. Same with the variance, only one paragraph and then a code block. Best practices had to be written as an unordered list, always, same with the related components section, always and an ordered list. So while our docs scripts were great for generating color swatches and details about which props were available in components, the process was not great for creating our component documentation which frustrated everyone. One mistake and if not whole chunks of documentation would be missing from the component pages. We had the freedom of using markdown yet we were not taking advantage of it.

This was a serious cognitive lift even for someone who was very familiar with the code base. Now imagine, if you have a new contributor to your project, not exactly welcoming experience.

We decided to review our process what wasn't working. One of our biggest issues, we chose to show one component variant at a time rather than all at once. This forced our users to access a select menu over and over again to compare component 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 Jell-O with shellfish.

So we decided it was time to make our docs contribution process more user-friendly in terms of structure and in terms of how we authored. Especially the component example pages. We wanted the users to have the confidence that whatever content they wrote on the docs page would make it into that 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. One, Gatsby gave us a way to migrate all our main documentation pages right into the site without much fuss. Two, Gatsby provides a web pack and Babel config similar to Create React app, so we could start with a scaffolded project and extend as needed. And three, Gatsby supports MDX, so we could write component documentation using Markdown, import React components right into 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's promoting inclusivity in general, and really should, it follows that inclusive docs make sense.

As a bonus, Gatsby, we streamed our stuff from two repos to one and reduced the amount of CLI commands dramatically. The default setup for Gatsby is great. However, we needed to make some adjustments so Gatsby worked for our needs. In the gatsby-config file, we added Gatsby-plugin-post-css to support post-css. Gatsby-plugin-compile-es6 packages to support our design system package. 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. Gatsby-plugin-page-creator to create pages from the source pages folder. And Gatsby-plugin-filesystem so we could pull in our data file and point Gatsby to the folder where all our component MDX files lived. In the Gatsby node file, we added a GraphQL query to find the component MDX content. And it create page action to routes and pages for the component docs. In the Gatsby browser file, we added things we wanted to apply throughout the site, like our global CSS styles and the wrap route element component. The wrap root element component acts as a wrapper around the site's root element and imports the MDX provider.

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 source directory, MDX renderer was needed to wrap the contents of our component page template. Otherwise, MDX files would render like this in the browser.

Now that our layout template used MDX renderer, our component MDX pages would render as we want in the browser. Now we could pop in React components next to code blocks in our MDX, and they would render, no problem. We could even wrap a buttoned component with a display box component and add a more cohesive look to the component code block pairing. If we wanted to add a props table to show which props can be used with a component and created a component that pulled in data to render as a data, a table of a props table component, pop that component into the docs MDX file and dots MDX file, I can speak today, passed in the name of the component to render, voila, the docs would show a props table.

For our component do's and don'ts, we used to have to write out an unordered list in the markdown file and the links and the list rendered like this. With MDX support, we instead created a custom component that renders on ordered lists. We could pass in a do's list and a don'ts list array into that component and boom, a nicely styled do's and don'ts list. 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 code block component and import a theme with good color contrast like Sarah Drasner's night owl theme. Then you can wrap your code block and theme it. Import that code block component into your wrap root element along with the predecode block utility and override the default pre tag styling at the app level by passing it in as a component to the root wrap element. So now when you write a code block in MDX, instead of the baseline styling, the custom code block will render with syntax highlighting. 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 in our custom code block component and pass the display box prop into that code block, if you add the display box prop to the code block in MDX, you'll get a code, you'll get a display box paired with a code block. Now, what about if you want your code block to be an editable code block? You can add a React live option to the component and show the component inside a display box pairing with an editable code block. So if you add the React live prop to your MDX code block, you'll get an editable code block and see your changes in real time. So if we write something like this, where we have three, three code blocks in MDX one with the React live prop, one with no prop just the name of the language and the third one with the display box prop passed in. This is what you will see. So over here is, I comped up a quick MDX file in my blog site to demo if you pass in, this one is the JSX with the React live prop passed in. This one is with just JSX passed in as the code. And this one is the passing in the display box prop to the JSX code block. What is great about the one with the React live prop is we are combining well the display box, fanciness and the block here, but this is now editable.

So I can do things with it. And if I know what props my component supports, I could make this button. If you see, look at there, it actually has error handling, but small button, wow. And I could also, I want, I know I support icons, so the icon I could use is the right arrow because I'm using React Font Awesome components under the hood. Look at that, I just added a icon to my button. But this, adding this type of editable block, editable React Live support to your code blocks is very powerful because your developers will be able to go into your component, into your documentation and play with the properties right there and understand how to use your component right away versus having to try, you know, look through all your props tables. This is another way for learners that need to type things to see how things break. So, editable block component, editable code blocks are amazing.