We’ve recently decided to remake our Developer Documentation site from scratch. That’s right, we’ve completely redone it using GatsbyJS. Building from scratch is a dream that many developers have, and we’re very excited about it… and you should be, too!

A blank slate of palpable excitement

Our Primary Motivations

Ability to best support our continual growth

Marqeta is continually expanding in company size and technological offerings. This is great for our current and future customers as we can offer new solutions while ensuring that our products are robust in nature. This also means that our documentation must also be able to grow and scale effortlessly. As such, it requires several crucial factors:

Painless, frequent, and quick updates to documentation

Ability to preview new doc versions and revert to old versions

Flexibility in the future to support other features, such as switching among product versions, and easy toggling between languages.

One Marqeta design

In addition to our products, Marqeta strives for our applications to also be a joy to use and interact with. We’ve been rolling out unified designs through a shared UI component library, but have also been working on new designs based on best design principles. Our newest designs are coming fresh from the oven and the Docs site will be our first site to implement them!

Fresh from the oven, just like our designs

Isomorphic JavaScript

Our awesome WAM (Web and Mobile) team at Marqeta has been migrating towards a more modern stack of React, GraphQL and AWS Lambda for faster development and better user experience with our design component library. (Check out a previous blog post about it here!)

Moving the Docs site away from our current Rails application to React and Gatsby.js is simply a continuation of the eventual migration for all of our applications.

Speed

Site speed is king. Research suggests that there are strong ties between content loading speed, first impressions, and conversions. Our content needs to reach our readers fast, so this is a crucial attribute of our Docs site, and there needs to be little to no compromise.

Why GatsbyJS?

So why did we choose Gatsby? Fantastic question!

Simply put, Gatsby hit all of our desired targets mentioned above, and then took it even further than we had anticipated.

Gatsby Tech

React:

React is the future for our web applications, and being able to use React in our Docs site was an obvious win. A static site generator with the ability to build static HTML with React while maintaining React state management on the client side? Say no more!

Static Site Generation:

Interestingly, as modern sites have been migrating to React, this has resulted in some sites actually losing out on performance. Site speed can go down due to monstrous JS bundle sizes and AJAX calls for deferred content. In addition, search engine optimization can get more complicated as web crawlers may not be able to scrape all the content. We didn’t want to sacrifice or have any trouble with these factors, so a static site generator was the way to go.

GraphQL:

Gatsby allows us to use GraphQL to query for information contained in the site. This includes site metadata, Asciidoc contents, any generated page information, and any other information we want to access in the site, such as our Site Tree that lets us know how the Asciidoc pages should be nested in the site. Gatsby gives us the ability to create our own information and query as needed with the ease of GraphQL!

Custom Plugins:

Gatsby allows us to fetch content (such as documents or images) from pretty much anywhere, such as a CMS, or locally. This is done through custom Gatsby plugins, which run before static HTML pages are created, to do many things from fetching content, creating content, and inserting them into Gatsby’s file system, that can then be queried with GraphQL in our React components. This gives us tremendous flexibility if we decide to host our images in the cloud or keep our documents in a separate GitHub repository for easy version control.

Asciidoc Support:

Our InfoDev team is moving towards writing documentation with Asciidoc. In a nutshell, this means all the content would be mapped to specific HTML elements, such as <h1>, <p>, etc… This allows for quicker writing and less wondering about how things will look. Asciidoc also allows for other documents to be included as snippets, for reusability of content. Using Gatsby’s plugins, and lifecycle methods, we’re then able to map specific Asciidoc content to Gatsby pages with custom URLs.

Built-in Web Optimizations:

Gatsby is fantastic at implementing web optimizations out of the box for us to use. This includes page prefetching, code-splitting, CSS modules support, and optimizing images for us. What does this mean exactly?

Any links that are on a page have their content prefetched, so when the user navigates to the page, there are no additional calls to the server. This means zero load time to the next page.

load time to the next page. Gatsby handles route based code splitting for us, which means smaller JS bundle sizes, and thus faster page loading speeds! Immediate win.

CSS module support out of the box means less configuration on our end. No need to worry about class name clashes within the application and in our imported React components.

Gatsby images are optimized in a few ways (Note: There are other specifics that Gatsby does with images, but these are what we’re excited about)

Blurred Images: An appropriately sized blurred image is served with the static HTML page fetched from the server. So no content bouncing or wondering if an image should exist.

Image Sizing: Gatsby creates multiple versions of the image in different sizes during production build, and the appropriately sized image is then fetched from the server. This image then replaces the blurred image. This means if the original image is 2000px wide, but only needs to be 100px wide, the client will only fetch the smaller 100px image that was generated by Gatsby.

Lazy Loading: Gatsby lazy loads images based on the viewport. As images enter the viewport, they are fetched, instead of having to wait for all the images to display at once.

Performance Testing

This is the most exciting part.

Chrome Lighthouse Audit

Here’s the performance of the production build of what we have so far. The only reason it’s not at 100%, is due to the way we import fonts currently, which will be optimized later on. Still impressive, with no compromises.

For comparison, here is our current Docs site.

Prefetching Content

Here’s the prefetching it’s doing for links on a page. Easy, and effortless on our end. The last call is the browser fetching the content on the hover of a link before the user clicks.

Note: There is zero additional network request when the user clicks on the link.

The Path from here

The Docs site is still a work in progress, and we’ll be constantly testing our site performance as we add new features and images.

We’re still building out our React components with the latest and greatest designs, and we’re constantly brainstorming about how we can best architect the code for current and future features.

One thing we know is that each day brings excitement as features are fleshed out.

If helping us build this interests you, join us!