docs: add info on plugins, themes, and starters (#20025)

* docs: add info on plugins, themes, and starters * chore: fix sidebar, add more details * chore: fix typo * Apply suggestions from code review Co-Authored-By: LB <[email protected]>
gatsbyjs · Dec 13, 2019 · a7ccb72 · a7ccb72
1 parent bfcc1ca
commit a7ccb72
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 16 deletions.
diff --git a/docs/docs/plugins-themes-and-starters.md b/docs/docs/plugins-themes-and-starters.md
@@ -0,0 +1,38 @@
+---
+title: Plugins, Themes, & Starters
+overview: true
+---
+
+In the Gatsby ecosystem, there's more than one way to build a site. To help you understand the differences between plugins, themes, and starters, this guide will talk through some of the details.
+
+## What is a plugin?
+
+Gatsby plugins are Node.js packages that implement Gatsby APIs and are commonly installed through a registry like npm. There are many types of [plugins](/plugins/), including data sourcing, SEO, responsive images, offline support, support for Sass, TypeScript, sitemaps and RSS, Google Analytics, and more. You can also [make your own plugins](/docs/creating-plugins/) and either distribute them for fellow Gatsby developers to use or [install them locally](/docs/loading-plugins-from-your-local-plugins-folder/).
+
+- [Plugin docs](/docs/plugins/)
+- [Using a plugin](/docs/using-a-plugin-in-your-site/)
+- [Plugin library](/plugins/)
+- [Creating plugins](/docs/creating-plugins/)
+
+## What is a theme?
+
+A Gatsby theme is a type of plugin that includes a `gatsby-config.js` file and adds pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. Since they are plugins, themes can be packaged and distributed through a registry like npm or yarn, and versions can be updated through a site's `package.json` file.
+
+With a Gatsby theme, all of your default configuration (shared functionality, data sourcing, design) is abstracted out of your site and into an installable package. A theme might differ from a typical plugin in that it packages up usage of a plugin into a consumable API, making it easy to include functionality without having to type out all of the code by hand (such as GraphQL queries). To understand more of the motivation for Gatsby themes, check out the docs on [What are Gatsby Themes?](/docs/themes/what-are-gatsby-themes/)
+
+- [Themes docs](/docs/themes/)
+- [Using a theme](/docs/themes/using-a-gatsby-theme/)
+- [Themes in plugin library](/plugins/?=gatsby-theme)
+- [Creating a theme](/docs/themes/building-themes/)
+
+## What is a starter?
+
+A starter is a boilerplate Gatsby site that users can copy and [customize](/docs/modifying-a-starter/). Once modified, a starter maintains no connection to its source.
+
+Gatsby offers [official starters](/docs/starters/#official-starters) for a default site, blog site, bare-bones hello world site, and both using and creating themes. There are also many starters from members of the community that can provide a good starting point for your Gatsby site.
+
+- [Starter docs](/docs/starters/)
+- [Modifying a starter](/docs/modifying-a-starter/)
+- [Starter library](/starters/)
+- [Creating a starter](/docs/creating-a-starter/)
+- [Converting a starter to a theme](/docs/themes/converting-a-starter/)
diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md
@@ -4,6 +4,10 @@ title: Plugins
 
 Gatsby plugins are Node.js packages that implement Gatsby APIs. For larger, more complex sites, plugins let you modularize your site customizations into site-specific plugins.
 
-Here are the guides in this section of the docs:
+There are many types of Gatsby plugins, including data sourcing, SEO, responsive images, offline support, Sass support, sitemaps, RSS feeds, TypeScript, Google Analytics, and more. You can also [make your own plugins](/docs/creating-plugins/)!
+
+Gatsby themes are a type of plugin that include a `gatsby-config.js` file and add **pre-configured** functionality, data sourcing, and/or UI code to Gatsby sites. To learn more about theme use cases and APIs, check out the [themes section of the docs](/docs/themes/).
+
+Here are the guides in the Plugins section of the docs:
 
 <GuideList slug={props.slug} />
diff --git a/docs/docs/starters.md b/docs/docs/starters.md
@@ -62,11 +62,13 @@ gatsby new blog ./Code/my-local-starter
 
 Official starters are maintained by Gatsby.
 
-| Starter                                                                              | Demo                                                         | Use case                       | Features                     |
-| ------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------ | ---------------------------- |
-| [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default)         | [Demo](https://gatsby-starter-default-demo.netlify.com/)     | Appropriate for most use cases | General Gatsby site          |
-| [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog)               | [Demo](https://gatsby-starter-blog-demo.netlify.com/)        | Create a basic blog            | Blog post pages and listings |
-| [gatsby-starter-hello-world](https://github.com/gatsbyjs/gatsby-starter-hello-world) | [Demo](https://gatsby-starter-hello-world-demo.netlify.com/) | Learn Gatsby                   | Gatsby bare essentials       |
+| Starter                                                                                      | Demo/Docs                                                    | Use case                       | Features                     |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------ | ---------------------------- |
+| [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default)                 | [Demo](https://gatsby-starter-default-demo.netlify.com/)     | Appropriate for most use cases | General Gatsby site          |
+| [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog)                       | [Demo](https://gatsby-starter-blog-demo.netlify.com/)        | Create a basic blog            | Blog post pages and listings |
+| [gatsby-starter-hello-world](https://github.com/gatsbyjs/gatsby-starter-hello-world)         | [Demo](https://gatsby-starter-hello-world-demo.netlify.com/) | Learn Gatsby                   | Gatsby bare essentials       |
+| [gatsby-starter-blog-theme](https://github.com/gatsbyjs/gatsby-starter-blog-theme)           | [Docs](/docs/themes/getting-started/)                        | Blog posts and pages           | Gatsby themes                |
+| [gatsby-starter-theme-workspace](https://github.com/gatsbyjs/gatsby-starter-theme-workspace) | [Docs](/docs/themes/building-themes/)                        | Building Gatsby Themes         | Minimal theme workspace      |
 
 ## Modifying starters
 

diff --git a/docs/docs/themes.md b/docs/docs/themes.md
@@ -19,3 +19,4 @@ This means that the configuration and functionality isn’t directly written int
 
 - [Gatsby theme tutorials](/tutorial/theme-tutorials/)
 - [Gatsby blog posts on themes](/blog/tags/themes)
+- [Plugins, Themes, and Starters](/docs/plugins-themes-and-starters/)
diff --git a/docs/docs/themes/converting-a-starter.md b/docs/docs/themes/converting-a-starter.md
@@ -2,7 +2,15 @@
 title: Converting a Starter to a Theme
 ---
 
-Gatsby themes are designed to be easy to create from an existing starter. Here we will walk you through the main steps of converting your starter to a theme.
+Gatsby themes are designed to be easy to create from an existing starter. This guide will walk you through the main steps of converting your starter to a theme.
+
+## What is a starter? What is a theme?
+
+A starter is a boilerplate Gatsby site that users can copy and [customize](/docs/modifying-a-starter/). Once modified, a starter maintains no connection to its source.
+
+A theme is a type of plugin that includes a `gatsby-config.js` file and adds pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. In contrast to starters, themes can be packaged and distributed through a registry like npm, and their versions can be tracked/managed through a `package.json` file.
+
+One reason to convert a starter to a theme is to make it easier to push updates out to consumers of your code. With a starter, users would have to try and update their code from the original starter repo and run the risk of overwriting some of their own changes. With a theme, it's much easier for developers to update code through their package manager and rely on a consistent theme API that respects their customizations.
 
 ## Prepare Your `package.json`
 

diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -240,15 +240,6 @@
                   link: /docs/remark-plugin-tutorial/
                 - title: Maintaining a Plugin*
                   link: /docs/maintaining-a-plugin/
-        - title: Starters
-          link: /docs/starters/
-          items:
-            - title: Starter Library
-              link: /starters/
-            - title: Modifying a Starter
-              link: /docs/modifying-a-starter/
-            - title: Creating a Starter
-              link: /docs/creating-a-starter/
         - title: Themes
           link: /docs/themes/
           items:
@@ -270,6 +261,15 @@
               link: /docs/themes/theme-composition/
             - title: Conventions
               link: /docs/themes/conventions/
+        - title: Starters
+          link: /docs/starters/
+          items:
+            - title: Starter Library
+              link: /starters/
+            - title: Modifying a Starter
+              link: /docs/modifying-a-starter/
+            - title: Creating a Starter
+              link: /docs/creating-a-starter/
         - title: Styling Your Site
           link: /docs/styling/
           breadcrumbTitle: Styling
@@ -541,6 +541,8 @@
           link: /docs/gatsby-core-philosophy/
         - title: Gatsby Project Structure
           link: /docs/gatsby-project-structure/
+        - title: Plugins, Themes, & Starters
+          link: /docs/plugins-themes-and-starters/
         - title: Overview of the Gatsby Build Process
           link: /docs/overview-of-the-gatsby-build-process/
         - title: Building with Components
Original file line number	Diff line number	Diff line change
Expand Up		@@ -19,3 +19,4 @@ This means that the configuration and functionality isn’t directly written int

		- [Gatsby theme tutorials](/tutorial/theme-tutorials/)
		- [Gatsby blog posts on themes](/blog/tags/themes)
		- [Plugins, Themes, and Starters](/docs/plugins-themes-and-starters/)