From ce9b87077083a9936ccdecb0a469ef0d4663f25e Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Tue, 27 Feb 2018 15:58:13 -0600 Subject: [PATCH 01/12] docs: add links for plugin authors - Link to plugin docs - Link to API spec re #4266 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d481aa392cfe..ba14db7b90d91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,7 @@ Looking to speak about Gatsby? We'd love to review your talk abstract/CFP! You c ### Creating your own plugins and loaders -If you create a loader or plugin, we would <3 for you to open source it, and put it on npm. +If you create a loader or plugin, we would <3 for you to open source it, and put it on npm. For more information on creating custom plugins, please see the documentation for [plugins](/docs/plugins/) and the [API specification](/docs/api-specification/). ### Contributing to the repo From c8e65effc993547183744fc6e75a85cc7306d6d1 Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Tue, 27 Feb 2018 16:10:44 -0600 Subject: [PATCH 02/12] =?UTF-8?q?docs:=20create=20a=20=E2=80=9Cplugin=20au?= =?UTF-8?q?thoring=E2=80=9D=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit re #4266 --- docs/docs/plugin-authoring.md | 5 +++++ www/src/pages/docs/doc-links.yaml | 2 ++ 2 files changed, 7 insertions(+) create mode 100644 docs/docs/plugin-authoring.md diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md new file mode 100644 index 0000000000000..b7c7849d5f824 --- /dev/null +++ b/docs/docs/plugin-authoring.md @@ -0,0 +1,5 @@ +--- +title: Plugin Authoring +--- + +TKTK diff --git a/www/src/pages/docs/doc-links.yaml b/www/src/pages/docs/doc-links.yaml index ff8e79ba0b8fe..d14f20dddca80 100644 --- a/www/src/pages/docs/doc-links.yaml +++ b/www/src/pages/docs/doc-links.yaml @@ -54,6 +54,8 @@ link: /docs/migrating-from-v0-to-v1/ - title: Path Prefix link: /docs/path-prefix/ + - title: Plugin Authoring + link: /docs/plugin-authoring/ - title: Proxying API Requests link: /docs/api-proxy/ - title: Using CSS-in-JS library Glamor From 30ad745e39b6dfe6e5d573a0631eff56e8cad458 Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Tue, 27 Feb 2018 17:16:07 -0600 Subject: [PATCH 03/12] docs: move authoring docs to authoring page - removes local plugin docs - adds link to plugin authoring (where local plugin docs were moved) re #4266 --- docs/docs/plugins.md | 36 ++---------------------------------- 1 file changed, 2 insertions(+), 34 deletions(-) diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index 200e40763f7cd..ac425bc9db280 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -40,41 +40,9 @@ Plugins can take options. Note that plugin options will be stringified by Gatsby See each plugin page below for more detailed documentation on using each plugin. -## Locally defined plugins +## Creating your own plugins -When you want to work on a new plugin, or maybe write one that is only relevant -to your specific use-case, a locally defined plugin is more convenient than -having to create an NPM package for it. - -You can place the code in the `plugins` folder in the root of your project like -this: - -``` -plugins -└── my-own-plugin - ├── gatsby-node.js - └── package.json -``` - -You still need to add the plugin to your `gatsby-config.js` like for plugins -installed from NPM. - -Each plugin requires a package.json file, but the minimum content is just an -empty object `{}`. The `name` and `version` fields are read from the package -file. The name is used to identify the plugin when it mutates the GraphQL data -structure. The version is used to clear the cache when it changes. - -For local plugins it is best to leave the version field empty. Gatsby will -generate an md5-hash from all gatsby-\* file contents and use that as the -version. This way the cache is automatically flushed when you change the code of -your plugin. - -If the name is empty it is inferred from the plugin folder name. - -Like all gatsby-\* files, the code is not being processed by Babel. If you want -to use JavaScript syntax which isn't supported by your version of Node.js, you -can place the files in a `src` subfolder and build them to the plugin folder -root. +If you’d like to create a custom Gatsby plugin, check out the [plugin authoring guide](/docs/plugin-authoring/). ## Official plugins From 3ae8f92d27a8c2bdd846b90918aebec0bffb31a6 Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Tue, 27 Feb 2018 17:21:50 -0600 Subject: [PATCH 04/12] docs: write plugin authoring docs - add naming convention explanations and examples - add core plugin concepts as bullet points - add list of files Gatsby tries to find in a plugin - explain local plugin development re #4266 --- docs/docs/plugin-authoring.md | 65 ++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index b7c7849d5f824..99ec70a9e94e2 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -2,4 +2,67 @@ title: Plugin Authoring --- -TKTK +Creating custom plugins in Gatsby is a breeze with our straightforward authoring process. + +## Core Concepts + +- Every Gatsby plugin is a standalone npm package +- At minimum, a `package.json` is required +- Plugins can be used locally (see [local plugins](#local-plugins) below) or published to npm as packages +- A plugin has access to the the Gatsby [Node](/docs/node-apis/), [SSR](/docs/ssr-apis/), and [browser](/docs/browser-apis/) APIs + +## Plugin naming conventions + +There are four standard plugin naming conventions for Gatsby: + +- **`gatsby-source-*`** — a source plugin loads data from a given source (e.g. WordPress, MongoDB, the file system). Use this plugin type if you are connecting a new source of data to Gatsby. + - Example: `gatsby-source-contentful` +- **`gatsby-transformer-*`** — a transformer plugin converts data from one format to another (e.g. CSV to JSON). Use this naming convention + - Example: `gatsby-transformer-yaml` +- **`gatsby-[plugin-name]-*`** — if a plugin is a plugin for another plugin 😅, it should be prefixed with the name of the plugin it extends (e.g. if it adds emoji to the output of `gatsby-transformer-remark`, call it `gatsby-remark-add-emoji`). Use this naming convention whenever your plugin will be included as a plugin in the `options` object of another plugin. + - Example: `gatsby-remark-images` +- **`gatsby-plugin-*`** — this is the most general plugin type. Use this naming convention if your plugin doesn’t meet the requirements of any other plugin types. + - Example: `gatsby-plugin-sass` + +## What files does Gatsby look for in a plugin? + +- `package.json` — [required] used to find the `name` and `version` fields (both optional) + - this can be an empty object (`{}`) for local plugins +- `gatsby-browser.js` — usage details are in the [browser API reference](/docs/browser-apis/) +- `gatsby-node.js` — usage details are in the [Node API reference](/docs/node-apis/) +- `gatsby-ssr.js` — usage details are in the [SSR API reference](/docs/ssr-apis/) + +## Local plugins + +When you want to work on a new plugin, or maybe write one that is only relevant +to your specific use-case, a locally defined plugin is more convenient than +having to create an NPM package for it. + +You can place the code in the `plugins` folder in the root of your project like +this: + +``` +plugins +└── my-own-plugin + └── package.json +``` + +**NOTE:** You still need to add the plugin to your `gatsby-config.js` like for plugins +installed from NPM. + +At a minimum, each plugin requires a package.json file, but the minimum content is just an +empty object `{}`. The `name` and `version` fields are read from the package +file. The name is used to identify the plugin when it mutates the GraphQL data +structure. The version is used to clear the cache when it changes. + +For local plugins it is best to leave the version field empty. Gatsby will +generate an md5-hash from all `gatsby-*` file contents and use that as the +version. This way the cache is automatically flushed when you change the code of +your plugin. + +If the name is empty it is inferred from the plugin folder name. + +Like all `gatsby-*` files, the code is not being processed by Babel. If you want +to use JavaScript syntax which isn't supported by your version of Node.js, you +can place the files in a `src` subfolder and build them to the plugin folder +root. From f2c62369502d4a48f64c01f41edc18873975ec4b Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Wed, 28 Feb 2018 10:35:52 -0600 Subject: [PATCH 05/12] docs: clean up plugin authoring docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add link to “create a source plugin” docs - Clarify optional vs. required files - Clarify how `package.json` works and what default values are - Clean up local plugin `gatsby-config.js` note - Remove duplicate explanation of `package.json` re #4266 --- docs/docs/plugin-authoring.md | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index 99ec70a9e94e2..f6c16b7a72479 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -17,6 +17,7 @@ There are four standard plugin naming conventions for Gatsby: - **`gatsby-source-*`** — a source plugin loads data from a given source (e.g. WordPress, MongoDB, the file system). Use this plugin type if you are connecting a new source of data to Gatsby. - Example: `gatsby-source-contentful` + - Docs: [create a source plugin](/docs/create-source-plugin/) - **`gatsby-transformer-*`** — a transformer plugin converts data from one format to another (e.g. CSV to JSON). Use this naming convention - Example: `gatsby-transformer-yaml` - **`gatsby-[plugin-name]-*`** — if a plugin is a plugin for another plugin 😅, it should be prefixed with the name of the plugin it extends (e.g. if it adds emoji to the output of `gatsby-transformer-remark`, call it `gatsby-remark-add-emoji`). Use this naming convention whenever your plugin will be included as a plugin in the `options` object of another plugin. @@ -26,8 +27,14 @@ There are four standard plugin naming conventions for Gatsby: ## What files does Gatsby look for in a plugin? -- `package.json` — [required] used to find the `name` and `version` fields (both optional) - - this can be an empty object (`{}`) for local plugins +All files are optional unless specifically marked as required. + +- `package.json` — [required] this can be an empty object (`{}`) for local plugins + - `name` is used to identify the plugin when it mutates Gatsby’s GraphQL data structure + - if `name` isn’t set, the folder name for the plugin is used + - `version` is used to manage the cache — if it changes, the cache is cleared + - if `version` isn’t set, an MD5 hash of the `gatsby-*` file contents is used to invalidate the cache + - omitting the `version` field is recommended for local plugins - `gatsby-browser.js` — usage details are in the [browser API reference](/docs/browser-apis/) - `gatsby-node.js` — usage details are in the [Node API reference](/docs/node-apis/) - `gatsby-ssr.js` — usage details are in the [SSR API reference](/docs/ssr-apis/) @@ -47,20 +54,7 @@ plugins └── package.json ``` -**NOTE:** You still need to add the plugin to your `gatsby-config.js` like for plugins -installed from NPM. - -At a minimum, each plugin requires a package.json file, but the minimum content is just an -empty object `{}`. The `name` and `version` fields are read from the package -file. The name is used to identify the plugin when it mutates the GraphQL data -structure. The version is used to clear the cache when it changes. - -For local plugins it is best to leave the version field empty. Gatsby will -generate an md5-hash from all `gatsby-*` file contents and use that as the -version. This way the cache is automatically flushed when you change the code of -your plugin. - -If the name is empty it is inferred from the plugin folder name. +**NOTE:** You still need to add the plugin to your `gatsby-config.js`. There is no auto-detection of local plugins. Like all `gatsby-*` files, the code is not being processed by Babel. If you want to use JavaScript syntax which isn't supported by your version of Node.js, you From eaa76ae5628d7ec0ab76e998574e2875c17ebd38 Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Wed, 28 Feb 2018 10:40:34 -0600 Subject: [PATCH 06/12] docs: clarify npm package core concept - Clarify that plugins can run as npm packages or local files re #4266 --- docs/docs/plugin-authoring.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index f6c16b7a72479..e7c55119fb859 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -6,9 +6,8 @@ Creating custom plugins in Gatsby is a breeze with our straightforward authoring ## Core Concepts -- Every Gatsby plugin is a standalone npm package +- Each Gatsby plugin can installed as an npm package or as a [local plugin](#local-plugins) - At minimum, a `package.json` is required -- Plugins can be used locally (see [local plugins](#local-plugins) below) or published to npm as packages - A plugin has access to the the Gatsby [Node](/docs/node-apis/), [SSR](/docs/ssr-apis/), and [browser](/docs/browser-apis/) APIs ## Plugin naming conventions From 6d22a0b457cb4000360b8b36aa0714c605540d1f Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Wed, 28 Feb 2018 17:05:09 +0000 Subject: [PATCH 07/12] Add missing word --- docs/docs/plugin-authoring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index e7c55119fb859..fed25810b8cda 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -6,7 +6,7 @@ Creating custom plugins in Gatsby is a breeze with our straightforward authoring ## Core Concepts -- Each Gatsby plugin can installed as an npm package or as a [local plugin](#local-plugins) +- Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins) - At minimum, a `package.json` is required - A plugin has access to the the Gatsby [Node](/docs/node-apis/), [SSR](/docs/ssr-apis/), and [browser](/docs/browser-apis/) APIs From 760342632a85c2b4f9113193075adfe313c6c61f Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Wed, 28 Feb 2018 16:41:59 -0600 Subject: [PATCH 08/12] docs: improve opening paragraph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - remove reference to plugins being “easy” - build off @robwierzbowski’s wording - add examples of what plugins can do re #4266 --- docs/docs/plugin-authoring.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index fed25810b8cda..123e7c362a6c0 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -2,7 +2,14 @@ title: Plugin Authoring --- -Creating custom plugins in Gatsby is a breeze with our straightforward authoring process. +One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to modify and extend just about everything Gatsby does. + +Of the many possibilities, plugins can: + +- add external data or content (e.g. your CMS, static files, a REST API) to your Gatsby GraphQL data +- transform data from other formats (e.g. YAML, CSV) to JSON objects +- add third-party services (e.g. Google Analytics, Instagram) to your site +- anything you can dream up! ## Core Concepts From fd6a68cda975e650354919dcfdd27f056373a4b4 Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Wed, 28 Feb 2018 17:47:08 -0600 Subject: [PATCH 09/12] docs: clarify and clean up - update wording per @kyleamathews feedback - clarify transformer description - link to example plugins - fix grammar mistakes re #4266 --- docs/docs/plugin-authoring.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index 123e7c362a6c0..692bd98abe8eb 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -14,22 +14,22 @@ Of the many possibilities, plugins can: ## Core Concepts - Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins) -- At minimum, a `package.json` is required -- A plugin has access to the the Gatsby [Node](/docs/node-apis/), [SSR](/docs/ssr-apis/), and [browser](/docs/browser-apis/) APIs +- A `package.json` is required +- Plugin implement the Gatsby APIs for [Node](/docs/node-apis/), [server-side rendering](/docs/ssr-apis/), and the [browser](/docs/browser-apis/) ## Plugin naming conventions There are four standard plugin naming conventions for Gatsby: - **`gatsby-source-*`** — a source plugin loads data from a given source (e.g. WordPress, MongoDB, the file system). Use this plugin type if you are connecting a new source of data to Gatsby. - - Example: `gatsby-source-contentful` + - Example: [`gatsby-source-contentful`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful) - Docs: [create a source plugin](/docs/create-source-plugin/) -- **`gatsby-transformer-*`** — a transformer plugin converts data from one format to another (e.g. CSV to JSON). Use this naming convention - - Example: `gatsby-transformer-yaml` +- **`gatsby-transformer-*`** — a transformer plugin converts data from one format (e.g. CSV, YAML) to a JavaScript object. Use this naming convention if your plugin will be transforming data from one format to another. + - Example: [`gatsby-transformer-yaml`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-yaml) - **`gatsby-[plugin-name]-*`** — if a plugin is a plugin for another plugin 😅, it should be prefixed with the name of the plugin it extends (e.g. if it adds emoji to the output of `gatsby-transformer-remark`, call it `gatsby-remark-add-emoji`). Use this naming convention whenever your plugin will be included as a plugin in the `options` object of another plugin. - - Example: `gatsby-remark-images` + - Example: [`gatsby-remark-images`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-images) - **`gatsby-plugin-*`** — this is the most general plugin type. Use this naming convention if your plugin doesn’t meet the requirements of any other plugin types. - - Example: `gatsby-plugin-sass` + - Example: [`gatsby-plugin-sharp`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp) ## What files does Gatsby look for in a plugin? @@ -47,12 +47,9 @@ All files are optional unless specifically marked as required. ## Local plugins -When you want to work on a new plugin, or maybe write one that is only relevant -to your specific use-case, a locally defined plugin is more convenient than -having to create an NPM package for it. +If a plugin is only relevant to your specific use-case, or if you’re developing a plugin and want a simpler workflow, a locally defined plugin is a convenient way to create and manage your plugin code. -You can place the code in the `plugins` folder in the root of your project like -this: +Place the code in the `plugins` folder in the root of your project like this: ``` plugins From d5a711841f859e78fcee43512a6465923f20ffd5 Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Wed, 28 Feb 2018 17:51:22 -0600 Subject: [PATCH 10/12] docs: improve wording around plugin documentation re #4266 --- docs/docs/plugins.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index ac425bc9db280..1c30d27244b0f 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -37,15 +37,14 @@ module.exports = { Plugins can take options. Note that plugin options will be stringified by Gatsby, so they cannot be functions. -See each plugin page below for more detailed -documentation on using each plugin. - ## Creating your own plugins If you’d like to create a custom Gatsby plugin, check out the [plugin authoring guide](/docs/plugin-authoring/). ## Official plugins +For usage instructions and options, see the plugin repo (linked below). + * [gatsby-plugin-aphrodite](/packages/gatsby-plugin-aphrodite/) * [gatsby-plugin-canonical-urls](/packages/gatsby-plugin-canonical-urls/) * [gatsby-plugin-catch-links](/packages/gatsby-plugin-catch-links/) From 6a203eaae50ace1def40f9444db041d55ed13a8f Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Wed, 28 Feb 2018 18:14:56 -0600 Subject: [PATCH 11/12] docs: minor tweaks --- docs/docs/plugin-authoring.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index 692bd98abe8eb..21e0811af3ba8 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -13,7 +13,7 @@ Of the many possibilities, plugins can: ## Core Concepts -- Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins) +- Each Gatsby plugin can be created as an npm package or as a [local plugin](#local-plugins) - A `package.json` is required - Plugin implement the Gatsby APIs for [Node](/docs/node-apis/), [server-side rendering](/docs/ssr-apis/), and the [browser](/docs/browser-apis/) @@ -59,7 +59,7 @@ plugins **NOTE:** You still need to add the plugin to your `gatsby-config.js`. There is no auto-detection of local plugins. -Like all `gatsby-*` files, the code is not being processed by Babel. If you want +Like all `gatsby-*` files, the code is not processed by Babel. If you want to use JavaScript syntax which isn't supported by your version of Node.js, you can place the files in a `src` subfolder and build them to the plugin folder root. From bab8c3d858144c4552111708403344f82c7f0c0e Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Wed, 28 Feb 2018 16:39:58 -0800 Subject: [PATCH 12/12] Reverse order as extending far more common --- docs/docs/plugin-authoring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md index 21e0811af3ba8..046fb76dff382 100644 --- a/docs/docs/plugin-authoring.md +++ b/docs/docs/plugin-authoring.md @@ -2,7 +2,7 @@ title: Plugin Authoring --- -One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to modify and extend just about everything Gatsby does. +One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to extend and modify just about everything Gatsby does. Of the many possibilities, plugins can: