Smoothly Inclusive Component Library Documentation

This ad is not shown to multipass and full ticket holders
React Summit US
React Summit US 2025
November 18 - 21, 2025
New York, US & Online
The biggest React conference in the US
Learn More
In partnership with Focus Reactive
Upcoming event
React Summit US 2025
React Summit US 2025
November 18 - 21, 2025. New York, US & Online
Learn more
Bookmark
Rate this content

Is your complex documentation setup a maintenance nightmare and chasing away potential contributors? In this talk, you will learn how to make your React component library documentation more user and contributor-friendly with Gats and MDX. Pair this with accessibility best practices, and your documentation will be inclusively smooth.

This talk has been presented at React Summit 2020, check out the latest edition of this React Conference.

FAQ

Kathleen McMahon is a principal engineer at CarGurus and an enthusiast of design systems, particularly component libraries. She has a background in leading tech for O'Reilly Media's Design System and is also known for participating in bike races.

Gatsby benefits documentation by allowing migration of main documentation pages seamlessly, providing similar configurations to Create React app through Webpack and Babel, and supporting MDX for enhanced Markdown documentation incorporating React components. It also improves accessibility and reduces the number of CLI commands needed.

MDX is a markdown format that allows you to write JSX directly in your markdown files and compile it into semantic HTML. This is crucial for documentation as it enhances accessibility, supports the use of React components within the docs, and provides better support for assistive technologies.

The Gatsby-plugin ecosystem enhanced documentation by supporting various functionalities such as PostCSS, compiling ES6 packages, recognizing MDX files, auto-linking headers for better screen reader support, creating pages from source folders, and managing filesystems for data files and component MDX files.

The previous documentation setup was fragmented between design system and docs repos, had complex syncing and script running requirements, and required markdown to be written in a specific format. This setup was cumbersome and unwelcoming for new contributors, often resulting in missing documentation sections.

MDX allowed for direct embedding of React components into documentation, facilitated the creation of dynamic examples such as editable code blocks, and streamlined the formatting and presentation of component properties and best practices, thereby making documentation more interactive and user-friendly.

Kathleen used Gatsby-plugin-post-css, Gatsby-plugin-compile-es6, Gatsby-plugin-mdx, Gatsby-remark-autolink-headers, Gatsby-plugin-page-creator, and Gatsby-plugin-filesystem. These plugins helped in managing styles, supporting MDX files, creating pages, and managing data more efficiently within the Gatsby framework.

The docs contribution process was improved by revising the structure and authoring approach, which included integrating all documentation into a single repository, simplifying the setup process, and using MDX to enable more dynamic and inclusive documentation practices.

Kathleen McMahon
Kathleen McMahon
18 min
17 Jun, 2021

Comments

Sign in or register to post your comment.
Video Summary and Transcription
In this talk, the speaker discusses how Gatsby and MDX help create inclusive documentation for component libraries. Gatsby simplifies the process by merging documentation into a single repository and reducing CLI commands. MDX enhances the documentation by allowing React components to be embedded directly into Markdown files. The speaker highlights the challenges faced with the previous documentation setup, such as the complexity of multiple repositories and specific Markdown formatting. With Gatsby and MDX, the documentation process became more user-friendly and accessible. The speaker also mentions the benefits of using Gatsby plugins like Gatsby-plugin-post-css, Gatsby-plugin-compile-es6, and Gatsby-plugin-mdx for improving the documentation structure and accessibility.

1. Introduction to Component Library Documentation

Short description:

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. 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. Before CarGurus, I was a tech lead for the O'Reilly Media Design System. 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. Just getting started working with these repos was overwhelming for new contributors to say the least. 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. 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.

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.

2. Improving the Documentation Process with Gatsby

Short description:

This was a serious cognitive lift even for someone who was very familiar with the code base. 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. 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. 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. As a bonus, Gatsby, we streamed our stuff from two repos to one and reduced the amount of CLI commands dramatically. However, we needed to make some adjustments so Gatsby worked for our needs.

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.

3. Enhancing Component Documentation with MDX

Short description:

The MDX renderer was needed to wrap the contents of our component page template, ensuring proper rendering in the browser. React components can now be easily added to MDX files, allowing for seamless rendering. Custom components can be created for ordered lists, providing a nicely styled do's and don'ts list. MDX also enhances code block support, allowing for custom styling and different types of code blocks. By adding the React live prop, code blocks can be made editable and changes can be seen in real time.

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.

4. Enhancing Documentation with Editable Code Blocks

Short description:

By adding editable React Live support to code blocks, developers can easily play with component properties in the documentation. This provides a more interactive and intuitive way to understand how to use the component. It also allows learners to experiment and see how different inputs affect the component's behavior.

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.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

Full Stack Documentation
JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Top Content
The Talk discusses the shift to full-stack frameworks and the challenges of full-stack documentation. It highlights the power of interactive tutorials and the importance of user testing in software development. The Talk also introduces learn.svelte.dev, a platform for learning full-stack tools, and discusses the roadmap for SvelteKit and its documentation.
Gateway to React: The React.dev Story
React Summit US 2023React Summit US 2023
32 min
Gateway to React: The React.dev Story
Watch video: Gateway to React: The React.dev Story
The Talk discusses the journey of improving React and React Native documentation, including the addition of interactive code sandboxes and visual content. The focus was on creating a more accessible and engaging learning experience for developers. The Talk also emphasizes the importance of building a human API through well-designed documentation. It provides tips for building effective documentation sites and highlights the benefits of contributing to open source projects. The potential impact of AI on React development is mentioned, with the recognition that human engineers are still essential.
Opensource Documentation—Tales from React and React Native
React Finland 2021React Finland 2021
27 min
Opensource Documentation—Tales from React and React Native
Documentation is often your community's first point of contact with your project and their daily companion at work. So why is documentation the last thing that gets done, and how can we do it better? This talk shares how important documentation is for React and React Native and how you can invest in or contribute to making your favourite project's docs to build a thriving community
MDX in React-Native!?
React Advanced 2021React Advanced 2021
21 min
MDX in React-Native!?
Top Content
This Talk is about the development of MDX, a combination of Markdown and JSX, by a freelance full stack JavaScript developer. MDX is a powerful technology that allows for the creation of interactive content within blog posts and supports React components. The speaker developed RnMDX, a proper and polished MDX library for React Native, which can be dropped into any React Native app. RnMDX provides solutions for common issues with Markdown content in React Native and allows for the rendering of MDX content into native views. Bringing MDX into native apps is now easier, and it can be used for various purposes, such as serving the app layout from a CMS or creating interactive online magazines or blogs.
Documenting components with stories
React Finland 2021React Finland 2021
18 min
Documenting components with stories
Most documentation systems focus on text content of one form or another: WYSIWYG editors, markdown, code comments, and so forth. Storybook, the industry-standard component workshop, takes a very different approach, focusing instead on component examples, or stories.
In this demo, I will introduce an open format called Component Story Format (CSF).
I will show how CSF can be used used to create interactive docs in Storybook, including auto-generated DocsPage and freeform MDX documentation. Storybook Docs is a convenient way to build a living production design system.
I will then show how CSF stories can be used create novel forms of documentation, such as multiplayer collaborative docs, interactive design prototypes, and even behavioral documentation via tests.
Finally, I will present the current status and outline a roadmap of improvements that are on their way in the coming months.
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
TypeScript Congress 2022TypeScript Congress 2022
25 min
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
TypeScript for library authors offers benefits for both internal and external use, improving code quality and providing accurate understanding of libraries. Documentation and examples should be in code to provide up-to-date information. Testing types alongside unit tests ensures accurate typing. Managing changes and exposing types requires careful versioning. Deep integration of types improves usability. Using a map in TypeScript allows for simpler implementation and customization. Leveraging types in libraries can generate code based on user access. TypeScript integration with Nuxt provides support and type declarations.