From 1a94571ca5a94cb7587641ff7c69412562449a97 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Mon, 9 Dec 2019 15:50:46 -0800 Subject: [PATCH 1/4] docs: add info on plugins, themes, and starters --- docs/docs/plugins-themes-and-starters.md | 38 ++++++++++++++++++++++++ docs/docs/plugins.md | 6 +++- docs/docs/starters.md | 12 ++++---- docs/docs/themes.md | 1 + docs/docs/themes/converting-a-starter.md | 10 ++++++- www/src/data/sidebars/doc-links.yaml | 20 +++++++------ 6 files changed, 71 insertions(+), 16 deletions(-) create mode 100644 docs/docs/plugins-themes-and-starters.md diff --git a/docs/docs/plugins-themes-and-starters.md b/docs/docs/plugins-themes-and-starters.md new file mode 100644 index 0000000000000..b611cc6f817b6 --- /dev/null +++ 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. 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 distribute them for fellow Gatsby developers to use! + +- [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. 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. + +- [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 index 5a9e4160795b5..76a97003f9690 100644 --- 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: diff --git a/docs/docs/starters.md b/docs/docs/starters.md index d5e4423001960..a9402f1ce80ba 100644 --- 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 index e55e90d18f140..455d40f82a9b1 100644 --- 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 index 413e881a5929d..221b1e0f0ff9a 100644 --- 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 customzations. ## Prepare Your `package.json` diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 1445c23cfcf46..77c1c56807639 100644 --- 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: Themes, Plugins, & Starters + link: /docs/themes-plugins-and-starters/ - title: Overview of the Gatsby Build Process link: /docs/overview-of-the-gatsby-build-process/ - title: Building with Components From e5be65f1d6b571690d574fe503d22c906815744e Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Mon, 9 Dec 2019 16:22:07 -0800 Subject: [PATCH 2/4] chore: fix sidebar, add more details --- docs/docs/plugins-themes-and-starters.md | 6 +++--- www/src/data/sidebars/doc-links.yaml | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/plugins-themes-and-starters.md b/docs/docs/plugins-themes-and-starters.md index b611cc6f817b6..096279c14577b 100644 --- a/docs/docs/plugins-themes-and-starters.md +++ b/docs/docs/plugins-themes-and-starters.md @@ -7,7 +7,7 @@ In the Gatsby ecosystem, there's more than one way to build a site. To help you ## What is a plugin? -Gatsby plugins are Node.js packages that implement Gatsby APIs. 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 distribute them for fellow Gatsby developers to use! +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/) @@ -16,9 +16,9 @@ Gatsby plugins are Node.js packages that implement Gatsby APIs. There are many t ## 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. 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. +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. Like 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. +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 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 learn more about how 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/) diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 77c1c56807639..0e56371b19d82 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -541,8 +541,8 @@ link: /docs/gatsby-core-philosophy/ - title: Gatsby Project Structure link: /docs/gatsby-project-structure/ - - title: Themes, Plugins, & Starters - link: /docs/themes-plugins-and-starters/ + - 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 From 81c5dbef6929e27f831d8714382afa4712825831 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Mon, 9 Dec 2019 16:29:53 -0800 Subject: [PATCH 3/4] chore: fix typo --- docs/docs/plugins-themes-and-starters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/plugins-themes-and-starters.md b/docs/docs/plugins-themes-and-starters.md index 096279c14577b..a9893417ea7a2 100644 --- a/docs/docs/plugins-themes-and-starters.md +++ b/docs/docs/plugins-themes-and-starters.md @@ -18,7 +18,7 @@ Gatsby plugins are Node.js packages that implement Gatsby APIs and are commonly 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. Like 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 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 learn more about how Gatsby themes, check out the docs on [What are Gatsby Themes?](/docs/themes/what-are-gatsby-themes/) +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 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/) From 1f35a518373da6355347b532b6c184bb79c06202 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Thu, 12 Dec 2019 12:05:10 -0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-Authored-By: LB --- docs/docs/plugins-themes-and-starters.md | 4 ++-- docs/docs/themes/converting-a-starter.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/plugins-themes-and-starters.md b/docs/docs/plugins-themes-and-starters.md index a9893417ea7a2..35e9161c03a6b 100644 --- a/docs/docs/plugins-themes-and-starters.md +++ b/docs/docs/plugins-themes-and-starters.md @@ -16,9 +16,9 @@ Gatsby plugins are Node.js packages that implement Gatsby APIs and are commonly ## 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. Like 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. +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 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/) +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/) diff --git a/docs/docs/themes/converting-a-starter.md b/docs/docs/themes/converting-a-starter.md index 221b1e0f0ff9a..3e6afc0a9ed54 100644 --- a/docs/docs/themes/converting-a-starter.md +++ b/docs/docs/themes/converting-a-starter.md @@ -10,7 +10,7 @@ A starter is a boilerplate Gatsby site that users can copy and [customize](/docs 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 customzations. +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`