Defining a component library with MDX for content creators
Overview
This Dot Labs was hired by the ReactJS team at Meta (formerly Facebook) to upgrade the React documentation site and modernize it with interactive guides and clearer API documentation.
Prior to our work with Meta, the ReactJS documentation site did not provide a first-class experience to help developers learn ReactJS and its documentation was hard to explore.
Through This Dot Labs and the React team's collaboration, we were able to deliver a first-in-class documentation site with interactive examples and clearer API documentation while keeping the experience focused on content writers and not technical implementers.
Services Provided
This Dot Labs implemented a design system into a library of MDX components that allows content writers to generate the site's content via easy to use markdown. Once the MDX library was defined, content writers could contribute new documentation while component design was refined and optimized for all users.
Although the final design has changed after This Dot's involvement, the React team was able to quickly modify the Tailwind CSS classes to match the project's new theme thanks to a well-defined component library.
Tech-stack
NextJS
MDX
Tailwind CSSThe tech stack of Next.js, MDX, and Tailwind CSS originated from Jared Palmer who built the initial prototype for the new site. This is a tech stack that we use regularly at This Dot Labs for projects, and when we learned this was the core of the new docs site, we were excited to have the opportunity to work with the React team to create the MDX library. The following are a few reasons why we typically recommend this stack, and we believe were some of Jared and the React team's motivations as well:
- Developing components using Tailwind CSS allowed for tokenization of colors and other styles to enable rapid global changes to site aesthetics and provide features like dark mode while reducing the overall CSS shipped to production.
- Leveraging Next.js static generation and MDX compatibility allows the site to load faster and have better SEO.
- Utilizing MDX to write custom markdown components enables content creators to develop rich content pages without having to implement complex features in code.
This Dot Labs is a development consultancy focused on providing staff augmentation, architectural guidance, and consulting to companies.
We help implement and teach modern web best practices with technologies such as React, Angular, Vue, Web Components, GraphQL, Node, and more.
Meta Platforms is the parent company that owns and operates multiple social media and communication platforms including Facebook, Instagram, and WhatsApp. Meta Platforms is also the company that oversees the development of the ReactJS library.
Enabling Content Creators Using Simple Markdown Component APIs
This Dot Labs worked with the project designer and the project leads to understand the scope and behavior of the components needed for the documentation site. Once our team established the design and behavior, we parsed through the content to understand what unique components we would need to create. From there, we worked on the content rich pages first to create a full library of components that could be used by content writers so that the main content could be developed alongside the design system and content.
To enable this, we had to find creative solutions to allow creators to develop content without having to write code. Instead, we wanted them to be able to just use markdown with minimal components since we didn't want writers to be concerned with layout when they should be focusing on content.
Working with Third Parties to Improve Technologies for the Client Project
We worked closely with CodeSandbox to extend their new Sandpack plugin which is used to display code and interactive examples. We identified some areas for improvement that limited the plugin's extensibility, and worked with CodeSandbox to help align the tool with a diverse array of use cases, making it easier for developers to create rich, interactive experiences between the code and content.
Stealth Open Source Development
Because of the main code repository's open-source nature, we needed to develop the project in a separate private repository that had to be migrated at a later date. We did this to keep the project's updates private until the React team was ready to publish them along with the React Docs beta release, which successfully launched on October 22, 2021.
Let's see how This Dot can help you
If you are interested in learning about how your development team can benefit from a partnership with This Dot Labs, email hi@thisdot.co with questions, or to schedule a complementary one-hour code audit.
You might also like
Portfolio
This Dot Labs supports companies and individuals as they grow their web based technologies.