docs: improve documentation for plugin authors #4272

jlengstorf · 2018-02-27T22:07:13Z

Opening a PR early to allow feedback early and often.

Goals for this PR:

Link to plugin docs from the "how to contribute" page
Link to API spec from the "how to contribute" page
Add a "Plugin authoring" page to the "Guides" section of the docs
Move local plugin info from core concepts to plugin authoring
Add link to core concepts plugin page to plugin authoring
Add naming convention docs to authoring page
Add a list of all files Gatsby looks for in a plugin (e.g. gatsby-node.js) to the authoring page
~~- [ ] Add a boilerplate README for a Gatsby plugin to the authoring page~~ (this was moved to [docs] Add template for plugin READMEs #4284)

re #4266

- Link to plugin docs - Link to API spec re gatsbyjs#4266

re gatsbyjs#4266

gatsbybot · 2018-02-27T22:13:49Z

Deploy preview for gatsbygram ready!

Built with commit ce9b870

https://deploy-preview-4272--gatsbygram.netlify.com

gatsbybot · 2018-02-27T22:16:58Z

Deploy preview for gatsbygram ready!

Built with commit bab8c3d

https://deploy-preview-4272--gatsbygram.netlify.com

- removes local plugin docs - adds link to plugin authoring (where local plugin docs were moved) re gatsbyjs#4266

- 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 gatsbyjs#4266

shannonbux · 2018-02-28T01:22:03Z

Super awesome stuff. @benjaminhoffman looks like Jason has got a great "how to build a plugin" guide here, so since you mentioned wanting to write something like this, maybe you'd like to hop in here and see what you think. Perhaps you could try these instructions and then offer feedback on how they work out for you?? What they are doing well and what they're missing!

benjaminhoffman · 2018-02-28T07:06:45Z

I like this. Definitely heading in the right direction. I'm still learning about how to build a plugin but so far, the PR looks great to me!

fk · 2018-02-28T10:43:19Z

docs/docs/plugin-authoring.md

+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


The first sentence mentions that "the minimum content is just an empty object". The following sentence then explains what is read from package.json. I find this a little confusing—first it's "okay to be empty", but then "things are read" only fully makes sense to me after advancing to the following paragraphs. I think an addition to the second sentence would help (me ;-)), but I'm not sure if the following is the best way to go:

If present, the name and version fields are read from the package file.

Good point — let me add what the default values are.

jlengstorf · 2018-02-28T14:45:57Z

Adding a reference to #4244 so anyone who finds that via Google can make their way to this PR and the relevant documentation.

m-allanson

This looks great! I've added some thoughts - feel free to use or ignore as you see fit. 😄

m-allanson · 2018-02-28T15:22:05Z

docs/docs/plugin-authoring.md

+
+- 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


Does this concept conflict with the first concept "Every Gatsby plugin is a standalone npm package"?

Maybe the first concept could be something like "A Gatsby plugin is a set of files that can modify Gatsby's behaviour"?

m-allanson · 2018-02-28T15:28:14Z

docs/docs/plugin-authoring.md

+- **`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`


Is it possible to add a bit more info on when you'd create a transformer vs a source plugin? Maybe this isn't the right place to write about that, but it's something that's a bit of a grey area to me.

m-allanson · 2018-02-28T15:33:31Z

docs/docs/plugin-authoring.md

+
+- `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/)


Is it worth being explicit that these three files are optional? Similar to the [required] note on package.json

m-allanson · 2018-02-28T15:37:33Z

docs/docs/plugin-authoring.md

+    └── package.json
+```
+
+**NOTE:** You still need to add the plugin to your `gatsby-config.js` like for plugins


like reads a bit strangely to me. Would any of the following work better? the same as, similarly to, as you would, or something else?

- 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 gatsbyjs#4266

- Clarify that plugins can run as npm packages or local files re gatsbyjs#4266

jlengstorf · 2018-02-28T16:41:49Z

@m-allanson Addressed your comments — thanks for those!

jlengstorf · 2018-02-28T16:43:27Z

I'm thinking we should move the README boilerplate to its own issue and look at getting this PR merged as-is (or with whatever edits have yet to come in).

@shannonbux @benjaminhoffman @m-allanson @fk @KyleAMathews Any opposition to splitting off the README?

jlengstorf · 2018-02-28T17:09:29Z

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)


🤦‍♂️ Thanks!

KyleAMathews

This is fantastic! Creating plugins is something every site should do and this is a great start to making that doable for folks.

KyleAMathews · 2018-02-28T18:54:05Z

docs/docs/plugin-authoring.md

+title: Plugin Authoring
+---
+
+Creating custom plugins in Gatsby is a breeze with our straightforward authoring process.


We've been following @robwierzbowski's suggestion to avoid indicating something is "easy" as that can intimidate newer developers for whom everything is complicated

#3159

Agreed. Another way to word this could be:

The Gatsby API is open and flexible and the number of plugins created by community members is growing. Follow these steps to create a custom plugin in Gatsby.

I don't know if that is gobbledygook language since I'm not a programmer. The essence would be to emphasize how Gatsby is meant to be open to plugins. It was built to expect them. Or something like that. Just a tone that invites people to experiment and realize that there is a lot of potential for an awesome plugin ecosystem.

Hey, thanks for remembering! My two cents:

Gatsby is designed to be extensible. One of the best ways to add functionality to Gatsby is through our plugin system. (maybe some examples of what is a good fit for a plugin...)

Good call. I'm leaning toward @robwierzbowski's wording, and I'll work in some examples of good candidates for plugins.

KyleAMathews · 2018-02-28T18:54:28Z

docs/docs/plugin-authoring.md

+
+## Core Concepts
+
+- Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins)


Capitalize NPM

Their official branding appears to keep it lowercase: https://www.npmjs.com/ 😕

KyleAMathews · 2018-02-28T18:54:54Z

docs/docs/plugin-authoring.md

+## 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


Remove "At minimum"

KyleAMathews · 2018-02-28T18:55:38Z

docs/docs/plugin-authoring.md

+
+- 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


I'd put it "Plugins implement Gatsby APIs for [Node]..."

KyleAMathews · 2018-02-28T18:58:18Z

docs/docs/plugin-authoring.md

+- **`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


"A transformer plugin converts data from one format into JavaScript objects"

I can't think of any reason why a transformer plugin wouldn't ever transform data directly into JavaScript objects. It could happen but it's unlikely.

KyleAMathews · 2018-02-28T18:58:42Z

docs/docs/plugin-authoring.md

+- **`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`


The examples should link to their package page.

KyleAMathews · 2018-02-28T18:59:45Z

docs/docs/plugin-authoring.md

+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


remove "can"

shannonbux · 2018-02-28T01:16:21Z

docs/docs/plugin-authoring.md

+## 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


*because a locally defined

shannonbux · 2018-02-28T01:17:28Z

docs/docs/plugin-authoring.md

+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:


hey hey! Nice use of a full sentence before a colon. I'm not a grammar tight wad (hopefully) but did find it interesting to learn last year that I had been using colons ineffectively for years. They are most effective after full sentences and hardly anyone does that

shannonbux · 2018-02-28T01:18:00Z

docs/docs/plugin-authoring.md

+```
+
+**NOTE:** You still need to add the plugin to your `gatsby-config.js` like for plugins
+installed from NPM.


*like you would for plugins

shannonbux · 2018-02-28T01:18:28Z

docs/docs/plugin-authoring.md

+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.


shannonbux · 2018-02-28T01:20:19Z

docs/docs/plugin-authoring.md

+  - 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.


I'm guessing plugin creators will get this, and possibly I'm just the one who is confused. Because it sounds like if you just keep adding something to the end of all applicable prefixes, wouldn't it be gatsby-transformer-remark-add-emoji? I mean, that's insanely long, but these instructions would have made me think that was correct without the helpful example. Does that make sense?

shannonbux · 2018-02-28T19:42:23Z

docs/docs/plugin-authoring.md

+title: Plugin Authoring
+---
+
+Creating custom plugins in Gatsby is a breeze with our straightforward authoring process.


Agreed. Another way to word this could be:

The Gatsby API is open and flexible and the number of plugins created by community members is growing. Follow these steps to create a custom plugin in Gatsby.

I don't know if that is gobbledygook language since I'm not a programmer. The essence would be to emphasize how Gatsby is meant to be open to plugins. It was built to expect them. Or something like that. Just a tone that invites people to experiment and realize that there is a lot of potential for an awesome plugin ecosystem.

shannonbux · 2018-02-28T19:44:27Z

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


just for less redundancy, perhaps: "see the links below for instructions on how to use each plugin"

robwierzbowski · 2018-02-28T21:07:33Z

Love the attention to docs here! You're the best 🙏🏼🙌🏼

shannonbux · 2018-02-28T21:59:49Z

This rewording seems excellent to me, @robwierzbowski

…

On Wed, Feb 28, 2018 at 2:07 PM, Rob Wierzbowski ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/docs/plugin-authoring.md <#4272 (comment)>: > @@ -0,0 +1,61 @@ +--- +title: Plugin Authoring +--- + +Creating custom plugins in Gatsby is a breeze with our straightforward authoring process. Hey, thanks for remembering! My two cents: Gatsby is designed to be extensible. One of the best ways to add functionality to Gatsby is through our plugin system. (maybe some examples of what is a good fit for a plugin...) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4272 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2sEpAdSxmgtflQq1llKy6sG0aY4aks5tZb__gaJpZM4SVueg> .

@robwierzbowski

- remove reference to plugins being “easy” - build off @robwierzbowski’s wording - add examples of what plugins can do re gatsbyjs#4266

shannonbux · 2018-02-28T23:15:11Z

@jlengstorf oh huh. Yeah, I guess we go with their official thing then!

…

On Wed, Feb 28, 2018 at 3:44 PM, Jason Lengstorf ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/docs/plugin-authoring.md <#4272 (comment)>: > @@ -0,0 +1,61 @@ +--- +title: Plugin Authoring +--- + +Creating custom plugins in Gatsby is a breeze with our straightforward authoring process. + +## Core Concepts + +- Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins) Their official branding appears to keep it lowercase: https://www.npmjs.com/ 😕 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4272 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2jcICWvxqM8rpI38UuebC4K1K3vKks5tZdbKgaJpZM4SVueg> .

@KyleAMathews

- update wording per @KyleAMathews feedback - clarify transformer description - link to example plugins - fix grammar mistakes re gatsbyjs#4266

re gatsbyjs#4266

jlengstorf · 2018-02-28T23:52:35Z

@shannonbux @KyleAMathews Addressed your feedback and pushed up changes. Let me know if you see anything else!

KyleAMathews

Couple other small needed tweaks I found

KyleAMathews · 2018-03-01T00:07:53Z

docs/docs/plugin-authoring.md

+
+## Core Concepts
+
+- Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins)


How about "Each Gatsby plugin an be created as an NPM package or as a..."

It seems odd to say you're "installing" a local plugin which you'd rarely do.

KyleAMathews · 2018-03-01T00:08:59Z

docs/docs/plugin-authoring.md

+
+**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


*is not processed

Kill "being"

jlengstorf · 2018-03-01T00:15:50Z

All set, @KyleAMathews!

KyleAMathews · 2018-03-01T00:40:57Z

Nicely done, thanks!

shannonbux · 2018-03-01T16:58:43Z

Wow it's amazing to see this getting done. Way to go, @jlengstorf et al~!

…

On Wed, Feb 28, 2018 at 5:41 PM, Kyle Mathews ***@***.***> wrote: Nicely done, thanks! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4272 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ae9o2neTs67Ukkr3QO_yDT9mp8t7ZmhRks5tZ0OfgaJpZM4SVueg> .

docs: add links for plugin authors

ce9b870

- Link to plugin docs - Link to API spec re gatsbyjs#4266

jlengstorf added the type: documentation An issue or pull request for improving or updating Gatsby's documentation label Feb 27, 2018

ghost assigned jlengstorf Feb 27, 2018

ghost added the review label Feb 27, 2018

docs: create a “plugin authoring” page

c8e65ef

re gatsbyjs#4266

jlengstorf mentioned this pull request Feb 27, 2018

[docs] Improve documentation for plugin authors #4266

Closed

8 tasks

jlengstorf added 2 commits February 27, 2018 17:16

docs: move authoring docs to authoring page

30ad745

- removes local plugin docs - adds link to plugin authoring (where local plugin docs were moved) re gatsbyjs#4266

docs: write plugin authoring docs

3ae8f92

- 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 gatsbyjs#4266

jlengstorf requested review from KyleAMathews and shannonbux February 27, 2018 23:23

fk reviewed Feb 28, 2018

View reviewed changes

m-allanson reviewed Feb 28, 2018

View reviewed changes

jlengstorf added 2 commits February 28, 2018 10:35

docs: clarify npm package core concept

eaa76ae

- Clarify that plugins can run as npm packages or local files re gatsbyjs#4266

jlengstorf changed the title ~~[WIP] docs: improve documentation for plugin authors~~ docs: improve documentation for plugin authors Feb 28, 2018

Add missing word

6d22a0b

ghost assigned m-allanson Feb 28, 2018

jlengstorf commented Feb 28, 2018

View reviewed changes

KyleAMathews suggested changes Feb 28, 2018

View reviewed changes

shannonbux reviewed Feb 28, 2018

View reviewed changes

docs: improve opening paragraph

7603426

- remove reference to plugins being “easy” - build off @robwierzbowski’s wording - add examples of what plugins can do re gatsbyjs#4266

jlengstorf added 2 commits February 28, 2018 17:47

docs: clarify and clean up

fd6a68c

- update wording per @KyleAMathews feedback - clarify transformer description - link to example plugins - fix grammar mistakes re gatsbyjs#4266

docs: improve wording around plugin documentation

d5a7118

re gatsbyjs#4266

KyleAMathews suggested changes Mar 1, 2018

View reviewed changes

docs: minor tweaks

6a203ea

Reverse order as extending far more common

bab8c3d

ghost assigned KyleAMathews Mar 1, 2018

KyleAMathews approved these changes Mar 1, 2018

View reviewed changes

KyleAMathews merged commit a5c0871 into gatsbyjs:master Mar 1, 2018

ghost removed the review label Mar 1, 2018

jlengstorf deleted the docs/plugin-authoring branch March 1, 2018 00:49


		## Core Concepts

		- Each Gatsby plugin can be installed as an npm package or as a [local plugin](#local-plugins)

		@@ -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


		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

docs: improve documentation for plugin authors #4272

docs: improve documentation for plugin authors #4272

Conversation

jlengstorf commented Feb 27, 2018 • edited Loading

Goals for this PR:

gatsbybot commented Feb 27, 2018

gatsbybot commented Feb 27, 2018 • edited Loading

shannonbux commented Feb 28, 2018

benjaminhoffman commented Feb 28, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlengstorf commented Feb 28, 2018 • edited Loading

m-allanson left a comment

Choose a reason for hiding this comment

m-allanson Feb 28, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlengstorf commented Feb 28, 2018

jlengstorf commented Feb 28, 2018

Choose a reason for hiding this comment

KyleAMathews left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

robwierzbowski commented Feb 28, 2018

shannonbux commented Feb 28, 2018 via email

shannonbux commented Feb 28, 2018 via email

jlengstorf commented Feb 28, 2018

KyleAMathews left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlengstorf commented Mar 1, 2018

KyleAMathews commented Mar 1, 2018

shannonbux commented Mar 1, 2018 via email

jlengstorf commented Feb 27, 2018 •

edited

Loading

gatsbybot commented Feb 27, 2018 •

edited

Loading

benjaminhoffman commented Feb 28, 2018 •

edited

Loading

jlengstorf commented Feb 28, 2018 •

edited

Loading

m-allanson Feb 28, 2018 •

edited

Loading