Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Recently I've been on the hunt for React UI libraries that handle theming in an easy and extensible way. After a bit of comparison, Grommet ended up utilizing one of the most ideal architectures for styling and theming components. Grommet uses Styled Components (instead of object-based syntax like JSS), it handles theming properly (design tokens + minimal component tokens/styles), and it has many of the base components you need (from buttons to inputs).
I wanted to use Grommet as a basis for a design system and contribute to the library. However, the documentation for Grommet is a bit lacking. And after looking into the source code, I wasn't happy with the way the code was actually documented. So I set out to create a more robust documentation website that was more inclusive for contributions, included more content, and faster overall.
Not sure if this should be in the main grommet repo or not. I can re-file this there if necessary.
Problems with docs (and solutions)
It's honestly not too different from the current setup. There's just more examples, more documentation (on theming, general use, architecture and semantics), and less code — all sitting on a better stack that enables better UX on the frontend and contribution side.
How to accomplish
After a bit of initial exploration and experimentation using Gatsby and Docz (a docs template based on Gatsby), I started to notice some other strange issues with the code base.
After a day of tinkering or so, I whipped up this proof of concept using Gatsby, MDX, React-Docgen to generate documentation based off a slightly modified Grommet library. I converted one Grommet component (
It doesn't feature all the component pages, or new content (like theming docs). Those are a bit more time consuming or ideally community driven / discussed. However I thought this prototype would illustrate the architecture changes I'm proposing.
gatsby build docs
When you run Gatsby's build process, it's "source" plugins check the Grommet
The final product is static PWA that offers features like page preloading, offline support, and image optimizations. I also added live coding support to more examples. This way users don't have to load a new CodeSandbox for each experiment they want to test (which can be intensive + unnecessary if you've already saved the docs offline).
Deploying the documentation in production would also require production deployment of the UI library's source code documentation (since the Gatsby docs uses Grommet as NPM dependency, and pulls production content from there). This is why the live demo is deployed on Netlify using a static build process that's manually uploaded, instead of deployed via git commit.
Let's compare these Gatsby docs to the current iteration of the Grommet v2 documentation. These metrics were created by Lighthouse running on a MacBook Pro, set to Mobile and Simulated 4G with a 4x CPU slow down. I'm pretty sure both sites are hosted on Netlify, making it a great baseline CDN.
What do you think?
Thank you for your time and consideration!
If Grommet moved docs to Gatsby with the same content and continued to fragment all the information between three websites, there would be zero net gain in moving to Gatsby IMO.
So generally I'm in favor of this proposal, but let's also think about how to reduce the tribal knowledge in Grommet and improve the information architecture of the docs.
@whoisryosuke, thank you for the detailed discussion points. I've recently merged a PR which adds an extra build step to create a static build, resolving a few overdue SEO issues. Our goal for the Grommet site is to keep it low touch and simple. In the spirit of Grommet, we try to build custom for our use cases and not rely on heavy libraries.
I do believe we need to better streamline avenues of documentation for Grommet as @iMerica mentioned. However, I'm not certain that the argument regarding anyone can edit MDX is valid when the author would generally need to already be consuming the library to be creating documentation for it.
Maybe @L0ZZI can chime in regarding the use of a sidebar. I presume it goes back to the "keeping things simple" mantra. Additionally, one of the patterns we're leaning into with Grommet applications is search-based navigation rather than lengthy nav lists.
I can certainly understand the benefit of a Gatsby Grommet docs site but I'd want to see the team re-think how all of the information is presented first then we would choose the framework that is best suited to the design and concept rather than engineer first.