Skip to content

[v2] docs "Plugins" overview #7229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
m-allanson merged 1 commit into from
Aug 13, 2018
Merged

[v2] docs "Plugins" overview #7229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 7 additions & 8 deletions docs/docs/plugin-authoring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
---
title: Plugin Authoring
title: Plugin authoring
Copy link
Contributor

@shannonbux shannonbux Aug 10, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@m-allanson and @pieh do you remember if there's anything else that needs to be edited about this page? (i.e. common obstacles contributors are running into when they submit plugins?). I remember Mike, you were mentioning recently that you created an issue to help plugin authors signify what version of Gatsby their plugin is compatible with. Or was it the other way around, just helping people vet which plugins work for v2? Either way, wondering if there's something that needs to be edited here in this doc)

Copy link
Contributor

@m-allanson m-allanson Aug 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh good idea - here the issue: #7143.

I think we could merge this PR and then make another pass on the plugin docs to mention the Gatsby peerDependency?

Copy link
Contributor

@m-allanson m-allanson Aug 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure where it would fit in - but maybe this could mention something about learning from the source code of existing plugins?

Most plugins are open source and the code is often quite readable - if you're looking to write your own plugin it can be useful to review the source of similar plugins.

Copy link
Contributor

@m-allanson m-allanson Aug 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking further on this - maybe encourage people to write in a style that others can learn from?

That could be going too far off-track for this doc though. Sometimes people just need to get their stuff done and move on to the next job, so being told how to write your code here could be counter-productive.

---

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.
You may be looking to build a plugin that doesn't exist yet, or you may just be curious to know more about the anatomy of a Gatsby plugin. We'll review:

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!
1. the core concepts of what a Gatsby plugin is
2. naming conventions for the plugin title
3. expected files in a plugin package
4. defining a local (unpublished) plugin for your own use case
5. what a plugin is _not_

## Core Concepts

Expand Down
44 changes: 26 additions & 18 deletions docs/docs/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,50 @@
title: Plugins
---

Plugins are Node.js packages that implement Gatsby APIs. They enable you to
easily solve common website build problems e.g. setup Sass, add markdown
support, process images, etc.
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.

For larger / complex sites, they let you modularize your site customizations
into site-specific plugins.
Of the many possibilities, plugins can:

Gatsby has a large and growing set of plugins. To search/browse official and
community plugins and their documentation, visit the [Plugin Library](/plugins/).
- add external data or content (e.g. your CMS, static files, a REST API) to your Gatsby GraphQL data
Copy link
Contributor

@shannonbux shannonbux Aug 10, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, this does seem to belong here rather than in /plugin-authoring/. These docs have needed to be re-organized for a long time! What a relief!

- transform data from other formats (e.g. Markdown, YAML, CSV) to JSON objects
- add third-party services (e.g. Google Analytics, Instagram) to your site
- anything you can dream up!

For documentation on the different types of plugins and the functionality provided by each, see the [Plugin Authoring page](/docs/plugin-authoring/).
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.

For a walkthrough of how to build and publish your own plugin, see the [Source Plugin Tutorial](/docs/source-plugin-tutorial/).
## Search published plugins

## How to use Gatsby plugins?
Gatsby has a large and growing ecosystem of official and community plugins. To browse plugins and their documentation, visit the [Gatsby Plugin Library](/plugins/).

Gatsby plugins are Node.js packages, so you can install them like other packages in
node using NPM.
## Learn more about plugins

For example, `gatsby-transformer-json` is a package which adds support for JSON
files to the Gatsby data layer.
For documentation with further detail on what comprises a Gatsby plugin (file structure, etc), see the [plugin authoring page](/docs/plugin-authoring/).

## Build and publish a plugin

For a walkthrough of how to build and publish your own plugin, see the [source plugin tutorial](/docs/source-plugin-tutorial/).
Copy link
Contributor

@shannonbux shannonbux Aug 10, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would it make sense to link to a stub article(s) for other plugin tutorials (transformer plugin tutorial, for example)?

Copy link
Contributor Author

@amberleyromo amberleyromo Aug 11, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! Great idea. Let me know if I'm missing any:


## Use a plugin in your site

Gatsby plugins are Node.js packages, so you can install them like other packages in node using NPM.

For example, `gatsby-transformer-json` is a package which adds support for JSON files to the Gatsby data layer.

To install it, in the root of your site you run:

`npm install --save gatsby-transformer-json`
```bash
npm install --save gatsby-transformer-json
```

Then in your site's `gatsby-config.js` you add `gatsby-transformer-json`
to the plugins array like:
Then in your site's `gatsby-config.js` you add `gatsby-transformer-json` to the plugins array like:

```javascript
module.exports = {
plugins: [`gatsby-transformer-json`],
}
```

Plugins can take options. Examples:
Plugins can take options. For example:

```javascript
module.exports = {
Expand Down