Gatsby templates for documentation

[danielfdsilva]

This research looks at gatsby templates geared towards documentation sites, that could be used as a starting point.

List of starters

Gatsby Theme Document

🔗 https://www.gatsbyjs.com/plugins/gatsby-theme-document/
👁️ https://gatsby-theme-document.netlify.app/

Pretty simple starter with mdx support. Uses theme-ui for styling (Similar-ish to Chakra UI)
Outdated dependencies and unmaintained. Uses Gatsby v2.

Verdict: Unmaintained and outdated. Not recommended.

Adobe I/O Gatsby Theme

🔗 https://gatsbytemplates.io/theme/adobe-gatsby-theme/
👁️ https://adobedocs.github.io/dev-site-documentation-template/guides/

Clean an minimal with a lot of components built in.
It's by Adobe and doesn't support any custom styling.

Verdict: Good for Adobe projects, not recommended for general use.

Carbon Gatsby Theme

🔗 https://gatsbytemplates.io/theme/carbon-gatsby-theme/
👁️ https://gatsby-theme-carbon.vercel.app/

Originally by IBM, now maintained by the community, and it is based on the Carbon Design System which uses SCSS. Overrides are possible but don't seem straightforward and it has a definite flavor to it. Built for Gatsby v4 and has a lot of components built in.

Verdict: Good for projects that need a lot of components and are okay with the Carbon Design System.

Docz Gatsby Theme

🔗 https://gatsbytemplates.io/theme/docz-gatsby-theme/
👁️ https://www.docz.site/docs/getting-started

Pretty simple starter with mdx support. Uses theme-ui for styling (Similar-ish to Chakra UI)
Outdated dependencies and unmaintained. Uses Gatsby v2.

Verdict: Unmaintained and outdated. Not recommended.

Legals Gatsby Theme

🔗 https://gatsbytemplates.io/theme/legals-gatsby-theme/
👁️
Event though it is a documentation theme, seems to lack some features we're looking for like sub pages. It's a simple theme really geared towards legal documents.
Outdated dependencies and unmaintained. Uses Gatsby v2.

Verdict: Unmaintained and outdated. Not recommended.

gatsby-gitbook-starter

🔗 https://www.gatsbyjs.com/starters/hasura/gatsby-gitbook-starter
👁️ https://hasura.io/learn/graphql/react/introduction/

Doesn't seem to be actively maintained, but uses Gatsby v4. Seems inspired by Gatsby Theme Document.
Uses styled-components for styling, but doesn't seem to have an customizable theme. It uses several classes instead, with "hardcoded" values.
It is not a theme that is installed, but a starter that is cloned, therefore all files can be changed as needed.

Verdict: Could be a good starting point. It would require some customization to make it more flexible.

gatsby-antd-docs

🔗 https://www.gatsbyjs.com/starters/jannikbuschke/gatsby-antd-docs
👁️ https://www.jannikbuschke.de/gatsby-antd-docs/

Looks unmaintained and under development. Uses Gatsby v4.

Verdict: Unmaintained and outdated. Not recommended.

Custom

A custom option could be created using our own opinions and taking inspiration from the themes above. If we want to add some CMS functionality, and we have some research time, we could revisit TinaCMS, since it matured and has Gatsby support once again.

[ricardoduplos]

Great research! Thanks for sharing.

[danielfdsilva]

The research on gatsby starters for documentation sites yielded very few results. What exists is either pretty outdated or very targeted and lacking easy customization.

This lead us to start considering other options. The main requirements were:

• Easy to setup
• Maintained and updated
• Easy for content editors (Ease of content creation and page listing configuration)
• Support for custom MDX components for additional interactive pieces
• Customizable design

Enter Docusaurus. It's a project by Meta that aims to be a modern static site generator for documentation sites. It's built on top of React and MDX, and it's very easy to get started with.
Although it doesn't have the same level of data sourcing customization as Gatsby, it already comes with all the features we need for a documentation site, which is what we were looking for.

A first exploration revealed that it will be very easy to replicate the current features of "Satellite State of Play", while improving the overall experience for content editors and developers.

Accomplished with some quick customization and copy&paste.