Gatsby: [docs] [workflows] Using Gatsby Themes

[thomaswang]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

User story

As a new Gatsby user, I want to use Themes in my Gatsby project.

Evaluation

| Search | Discover | Complete | Linked | Tone | Style | Overall |
| --- | --- | --- | --- | --- | --- | --- |
| 😄 | 😄 | 😄 | 😄 | 😄 | 😄 | 😄 |

Steps taken to implement

1. Searchability
   
   
   
   1. Searched gatsby themes on Google; clicked on the first result - What Are Gatsby Themes?
   
   
   2. Building a Theme tutorial has incorrect date (SEO)
      
      
      
      
      
      1. ✅ [rec] Fix seo date for this tutorial
      
      
      
   
   

1. Discoverability
   
   
   
   1. Searched themes on .org; clicked on the first result - Themes
   
   
   2. Clickpath on .org (3 clicks):
      
      
      
      
      
      1. clicked on Docs in Navbar
      
      
      
      2. clicked on Reference Guides in Sidebar
      
      
      
      3. clicked on Themes in Reference Guides page, under In this section:
      
      
      
      4. 🚫(blocked due to UX concerns) [rec]: Add Themes to "Ecosystem" on .org home page, 1 click for direct link to documentation
      
      
      
   
   
2. Completeness
   
   
   
   1. Read through What Are Gatsby Themes?.
      
      
      
      
      
      • ✅ [rec] Add explanation of when to use themes vs. starters
      
      
      
      • ✅ [rec] Add all themes sections to "What's next?"
      
      
      
      • ✅ [rec] Put a one-liner of what Gatsby Themes are at the top of the doc on What are Gatsby Themes?
      
      
      
   
   
   2. Read through Using a Gatsby Theme
      
      
      
      
      
      • ✅ [rec] rename doc as "Getting Started"
      
      
      
      • ✅ [rec] Make this page about how to install a theme directly. Answer where themes must be published to pull into your project
      
      
      
   
   
   3. Read through Building Themes.
      
      
      
      
      
      • ✅ [rec] Add explanation of how to publish themes
      
      
      
   
   
3. Linkedness
   
   
   
   1. 6 blog posts linked on "What are Gatsby Themes" and 3 resources linked in the Themes main page
   
   
   2. Theme showcase not in docs
      
      
      
      
      
      • ✅ [rec] link to the Theme Jam submissions and the Plugins page tagged with gatsby theme
      
      
      
      • ✅ [rec] add Theme Tutorials to main Themes page and move Building Themes livestreams to Building Themes page
      
      
      
   
   
   3. Themes not linked in Plugins documentation
      
      
      
      
      
      • ✅ [rec] add Themes link to What is a Plugin?
      
      
      
   
   
4. Tone
5. Informative and friendly, but could consider making tone a bit easier to understand in reference guides. Try and tie into plugins more and remove the abstract nature of the word "theme"
6. Style
7. 👍(a bit verbose, could consider trimming down fat for descriptions / in getting started)

Recommendations

• [x] #18602 When to use themes vs. starters? (add to "What Are Gatsby Themes")
• [x] #18602 Add rest of themes documentation to "What Are Gatsby Themes"
• [x] #18301 Add Themes to "Ecosystem" on .org home page (improve Discoverability)
• [x] #18301 Add Themes to "Ecosystem" page (improve Discoverability)
• [x] #19222 Fix SEO on Building a theme tutorial
• [x] #19223 Put a one-liner of what Gatsby Themes are at the top of the doc on What are Gatsby Themes?
• [x] #19231 Link to the Theme Jam submissions and the Plugins page tagged with gatsby theme
• [x] #19243 Rename Using a Gatsby Theme doc as "Getting started". Then re-make this page about how to install a theme directly. Answer where themes must be published to pull into your project. Link old doc to new doc as reference.
• [x] #19244 Add Themes link to What is a Plugin?
• [x] #19245 Add Theme Tutorials to main Themes page and move Building Themes livestreams to Building Themes page
• [x] #19246 Add information on how to publish themes in Building Themes doc

Infographic from Gatsby Days

from Maggie Appleton

[marcysutton]

To add some of the things we talked about today:

• Some content is covered on the blog and could be cross-linked in the docs, such as Why Themes and the Roadmap. See the themes tag for where that stuff exists: https://www.gatsbyjs.org/blog/tags/themes
• For the Marketplace thing, we need to have bigger discussions internally but we could link to the Theme Jam submissions and the Plugins page tagged with gatsby theme
• The information on Using a Gatsby Theme provides a lot of cognitive overhead by telling people how to install a starter to use a theme. What if there isn't a starter for the theme someone wants to use: how do they install it?
  
  
  
  • I think we should rename that doc as "Using the Gatsby-Starter-Blog-Theme" and make this page about how to install a theme directly. It should answer where themes must be published to pull into your project: can developers use npm link, private and/or public npm packages, GitHub repos? I'm thinking specifically of monorepo users here in addition to consumers of public packages (which may or may not have clear docs themselves).
  
  
• Some information on publishing themes when Building a Theme would be appreciated as well: I don't see anything on the "Building Themes" doc, which is a better use of a starter since it's something people can customize for creating rather than consuming.

Here's another thing that stands out to me as an easy win potentially:

• Put a one-liner of what Gatsby Themes are at the top of the doc on What are Gatsby Themes? as it's not consistent with the purpose of Reference Guides to have to read about the history of them to know what they are.
  
  
  
  • Here's a suggestion of what to add: "Gatsby Themes are a type of plugin that includes a gatsby-config.js file and bundles functionality and/or UI code into a reusable, composable package." It's also described elsewhere as a "Gatsby Theme is a Gatsby site": https://www.gatsbyjs.org/docs/themes/building-themes/#accessibility
  
  

[marcysutton]

@thomaswangio, I wanted to check: are you able to take on the recommendations I put in this workflow issue? They would be good to resolve sooner than later (during the work-week, of course).

[thomaswang]

Hi @marcysutton, yes sorry for the delay! I'll make time to finish addressing the points on this issue this coming week.

[gillkyle]

I think this is going to be so helpful 🙂

If it's any help as a reference in boiling down ideas into something sensible and understandable I wrote a blog post about this way back when: https://kylegill.com/blog/2019-04-22-a-simple-guide-to-gatsby-themes/index

[thomaswang]

Pending open PR's, this workflow has finished evaluation. Further work on maintaining the "Using Themes" workflow, will be a UX improvement on the home page. What was discussed was potentially a block on the home page that talks about what themes are overall & then links to more detailed info about themes (cc @marcysutton @shannonbux).

In addition, the Theme Marketplace will need to be integrated into this workflow when it is added to the roadmap.

[shannonbux]

Fun to see this moving along!!