[docs] [workflows] Using Gatsby Themes

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

2. 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:
      • 🚫(blocked due to UX concerns) [rec]: Add Themes to "Ecosystem" on .org home page, 1 click for direct link to documentation
3. 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
4. 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?
5. Tone

• 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

• 👍(a bit verbose, could consider trimming down fat for descriptions / in getting started)

Recommendations

• [docs] improving Themes completeness #18602 When to use themes vs. starters? (add to "What Are Gatsby Themes")
• [docs] improving Themes completeness #18602 Add rest of themes documentation to "What Are Gatsby Themes"
• feat(www): Add Themes to "Ecosystem" on home page (option 1) #18301 Add Themes to "Ecosystem" on .org home page (improve Discoverability)
• feat(www): Add Themes to "Ecosystem" on home page (option 1) #18301 Add Themes to "Ecosystem" page (improve Discoverability)
• [docs] Add date to building a theme tutorial #19222 Fix SEO on Building a theme tutorial
• [docs] Add one liner to top of What are Gatsby Themes? #19223 Put a one-liner of what Gatsby Themes are at the top of the doc on What are Gatsby Themes?
• [docs] Add Browse themes section #19231 Link to the Theme Jam submissions and the Plugins page tagged with gatsby theme
• [docs] Refactoring Using Gatsby Themes, how to install a theme directly #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.
• [docs] Add bullet about themes to What are Plugins #19244 Add Themes link to What is a Plugin?
• [docs] Organizing themes tutorials and walkthroughs #19245 Add Theme Tutorials to main Themes page and move Building Themes livestreams to Building Themes page
• [docs] Add link to publishing theme and update instructions with gatsby-theme keyword #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).

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