diff --git a/docs/contributing/submit-to-plugin-library.md b/docs/contributing/submit-to-plugin-library.md index e94e20e0a9efc..e6346b2f3c4e5 100644 --- a/docs/contributing/submit-to-plugin-library.md +++ b/docs/contributing/submit-to-plugin-library.md @@ -6,9 +6,9 @@ title: Submit to Plugin Library In order to add your plugin to the [Plugin Library](/plugins/), you need to: -1. publish a package to npm (learn how [here](https://docs.npmjs.com/getting-started/publishing-npm-packages)), -2. include the [required files](/docs/how-plugins-work/#what-files-does-gatsby-look-for-in-a-plugin) in your plugin code, -3. and **include a `keywords` field** in your plugin's `package.json`, containing `gatsby` and `gatsby-plugin`. +1. publish a package to npm (learn how [here](https://docs.npmjs.com/getting-started/publishing-npm-packages)), +2. include the [required files](/docs/how-plugins-work/#what-files-does-gatsby-look-for-in-a-plugin) in your plugin code, +3. and **include a `keywords` field** in your plugin's `package.json`, containing `gatsby` and `gatsby-plugin`. After doing so, Algolia will take up to 12 hours to add it to the library search index (the exact time necessary is still unknown), and wait for the daily rebuild of https://gatsbyjs.org to automatically include your plugin page to the website. Then, all you have to do is share your wonderful plugin with the community! diff --git a/docs/docs/creating-a-local-plugin.md b/docs/docs/creating-a-local-plugin.md new file mode 100644 index 0000000000000..2115b10e1b4a6 --- /dev/null +++ b/docs/docs/creating-a-local-plugin.md @@ -0,0 +1,28 @@ +--- +Title: Creating a Local Plugin +--- + +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. + +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`. There is no auto-detection of local plugins. + +**NOTE:** For the plugin to be discovered, the plugin's root folder name is the value that needs to be referenced in order to load it (_not_ its _name_ in its package.json file). For example, in the above structure, the correct way to load the plugin is: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: ["my-own-plugin"], +} +``` + +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. diff --git a/docs/docs/creating-plugins.md b/docs/docs/creating-plugins.md new file mode 100644 index 0000000000000..9be70fc8e102e --- /dev/null +++ b/docs/docs/creating-plugins.md @@ -0,0 +1,15 @@ +--- +title: Creating Plugins +--- + +You may be looking to build and perhaps publish a plugin that doesn't exist yet, or you may just be curious to know more about the anatomy of a Gatsby plugin (file structure, etc). + +## Core concepts + +- Each Gatsby plugin can be created as an npm package or as a [local plugin](#local-plugins) +- A `package.json` is required +- Plugins implement the Gatsby APIs for [Node](/docs/node-apis/), [server-side rendering](/docs/ssr-apis/), and the [browser](/docs/browser-apis/) + +This section of the docs includes the following guides: + +[[guidelist]] diff --git a/docs/docs/files-gatsby-looks-for-in-a-plugin.md b/docs/docs/files-gatsby-looks-for-in-a-plugin.md new file mode 100644 index 0000000000000..60a8a8559dc54 --- /dev/null +++ b/docs/docs/files-gatsby-looks-for-in-a-plugin.md @@ -0,0 +1,19 @@ +--- +title: Files Gatsby Looks for in a Plugin +--- + +## What files does Gatsby look for in a plugin? + +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 + - `keywords` is used to make your plugin discoverable + - plugins published on the npm registry should have `gatsby` and `gatsby-plugin` in the `keywords` field to be added to the [Plugin Library](/packages/) +- `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/) diff --git a/docs/docs/how-plugins-work.md b/docs/docs/how-plugins-work.md deleted file mode 100644 index 9044aed0cf229..0000000000000 --- a/docs/docs/how-plugins-work.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: How Plugins Work ---- - -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: - -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. how to publish your plugin to the library - -## Core Concepts - -- Each Gatsby plugin can be created as an npm package or as a [local plugin](#local-plugins) -- A `package.json` is required -- Plugins 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`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful) - - Docs: [creating a source plugin](/docs/creating-a-source-plugin/) -- **`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) - - Docs: [creating a transformer plugin](/docs/creating-a-transformer-plugin/) -- **`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`](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-sharp`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp) - -## What files does Gatsby look for in a plugin? - -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 - - `keywords` is used to make your plugin discoverable - - plugins published on the npm registry should have `gatsby` and `gatsby-plugin` in the `keywords` field to be added to the [Plugin Library](/packages/) -- `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 - -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. - -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`. There is no auto-detection of local plugins. - -**NOTE:** For the plugin to be discovered, the plugin's root folder name is the value that needs to be referenced in order to load it (_not_ its _name_ in its package.json file). For example, in the above structure, the correct way to load the plugin is: - -```javascript:title=gatsby-config.js -module.exports = { - plugins: ["my-own-plugin"], -} -``` - -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. - -## Publishing a plugin to the library - -If you'd like to publish your plugin to the Gatsby Plugin Library (please do!), [follow these steps](/contributing/submit-to-plugin-library/). diff --git a/docs/docs/maintaining-a-plugin.md b/docs/docs/maintaining-a-plugin.md new file mode 100644 index 0000000000000..38d85daca36a4 --- /dev/null +++ b/docs/docs/maintaining-a-plugin.md @@ -0,0 +1,9 @@ +--- +title: Maintaining a Plugin +--- + +This is a stub article meant to be filled with tips on how to maintain a Gatsby plugin once you've published it as an npm package. + +Topics to be covered: + +- yarn workspaces can solve yarn link inconsistencies diff --git a/docs/docs/naming-a-plugin.md b/docs/docs/naming-a-plugin.md new file mode 100644 index 0000000000000..5945a46d77207 --- /dev/null +++ b/docs/docs/naming-a-plugin.md @@ -0,0 +1,18 @@ +--- +title: Naming a Plugin +--- + +## Plugin title 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`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful) + - Docs: [creating a source plugin](/docs/creating-a-source-plugin/) +- **`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) + - Docs: [creating a transformer plugin](/docs/creating-a-transformer-plugin/) +- **`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`](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-sharp`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp) diff --git a/docs/docs/source-plugin-tutorial.md b/docs/docs/pixabay-source-plugin-tutorial.md similarity index 99% rename from docs/docs/source-plugin-tutorial.md rename to docs/docs/pixabay-source-plugin-tutorial.md index a473e1d8e5a26..3912ac2333f55 100644 --- a/docs/docs/source-plugin-tutorial.md +++ b/docs/docs/pixabay-source-plugin-tutorial.md @@ -1,5 +1,5 @@ --- -title: "Source Plugin Tutorial" +title: "Pixabay Source Plugin Tutorial" --- Creating your own source plugin. diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index 6b094df6cd01b..6be0df84e7b6a 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -2,115 +2,8 @@ title: Plugins --- -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: - -- 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. Markdown, YAML, CSV) to JSON objects -- add third-party services (e.g. Google Analytics, Instagram) to your site -- do anything you can dream up! - 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. -## Search published 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/). - -## Learn more about plugins - -For documentation with further detail on what comprises a Gatsby plugin (file structure, etc), see the [plugin authoring page](/docs/how-plugins-work/). - -## 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/). - -## 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: - -```shell -npm install --save gatsby-transformer-json -``` - -Then in your site's `gatsby-config.js` you add `gatsby-transformer-json` to the plugins array like: - -```javascript:title=gatsby-config.js -module.exports = { - plugins: [`gatsby-transformer-json`], -} -``` - -Plugins can take options. For example: - -```javascript:title=gatsby-config.js -module.exports = { - plugins: [ - // Shortcut for adding plugins without options. - "gatsby-plugin-react-helmet", - { - // Standard plugin with options example - resolve: `gatsby-source-filesystem`, - options: { - path: `${__dirname}/src/data/`, - name: "data", - }, - }, - { - resolve: "gatsby-plugin-offline", - // Blank options, equivalent to string-only plugin - options: { - plugins: [], - }, - }, - { - resolve: `gatsby-transformer-remark`, - options: { - // plugins inside plugins - plugins: [`gatsby-remark-smartypants`], - }, - }, - ], -} -``` - -## Loading plugins from your local plugins folder - -Gatsby can also load plugins from the your local website plugins folder which is a folder named `plugins` in the website's root directory. - -```javascript:title=gatsby-config.js -module.exports = { - plugins: [`gatsby-local-plugin`], -} -``` - -If you want to reference a plugin that is not in the plugins folder then you could use something like the following: - -```javascript:title=gatsby-config.js -module.exports = { - plugins: [ - // Shortcut for adding plugins without options. - "gatsby-plugin-react-helmet", - { - // Standard plugin with options example - resolve: require.resolve(`/path/to/gatsby-local-plugin`), - }, - ], -} -``` - -## What don't you need plugins for? - -Most third-party functionality you want to add to your website will follow standard JavaScript and React.js patterns for importing packages and composing UIs. These do not require a Gatsby plugin! - -Some examples: - -- Importing JavaScript packages that provide general functionality, such as `lodash` or `axios` -- Using React components or component libraries you want to include in your UI, such as `Ant Design`, `Material UI`, or the typeahead from your component library. -- Integrating visualization libraries, such as `Highcharts` or `d3`. +Here are the guides in this section of the docs: -As a general rule, you may use _any_ npm package you might use without Gatsby, with Gatsby. What plugins offer is a prepackaged integration into the core Gatsby APIs to save you time and energy, with minimal configuration. In the case of `Styled Components`, you could manually render the `Provider` component near the root of your application, or you could just use `gatsby-plugin-styled-components` which takes care of this step for you in addition to any other difficulties you may run into configuring Styled Components to work with server side rendering. +[[guidelist]] diff --git a/docs/docs/using-a-plugin-in-your-site.md b/docs/docs/using-a-plugin-in-your-site.md new file mode 100644 index 0000000000000..f9cbb0d8443ed --- /dev/null +++ b/docs/docs/using-a-plugin-in-your-site.md @@ -0,0 +1,56 @@ +--- +title: Using 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: + +```shell +npm install --save gatsby-transformer-json +``` + +Then in your site's `gatsby-config.js` you add `gatsby-transformer-json` to the plugins array like: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [`gatsby-transformer-json`], +} +``` + +Plugins can take options. For example: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [ + // Shortcut for adding plugins without options. + "gatsby-plugin-react-helmet", + { + // Standard plugin with options example + resolve: `gatsby-source-filesystem`, + options: { + path: `${__dirname}/src/data/`, + name: "data", + }, + }, + { + resolve: "gatsby-plugin-offline", + // Blank options, equivalent to string-only plugin + options: { + plugins: [], + }, + }, + { + resolve: `gatsby-transformer-remark`, + options: { + // plugins inside plugins + plugins: [`gatsby-remark-smartypants`], + }, + }, + ], +} +``` + +Note that plugin options will be stringified by Gatsby, so they cannot be functions. diff --git a/docs/docs/what-is-a-plugin.md b/docs/docs/what-is-a-plugin.md new file mode 100644 index 0000000000000..8ea881d27b7e0 --- /dev/null +++ b/docs/docs/what-is-a-plugin.md @@ -0,0 +1,14 @@ +--- +title: "What is a Plugin?" +--- + +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. + +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: + +- 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. Markdown, YAML, CSV) to JSON objects +- add third-party services (e.g. Google Analytics, Instagram) to your site +- do anything you can dream up! diff --git a/docs/docs/what-you-dont-need-plugins-for.md b/docs/docs/what-you-dont-need-plugins-for.md new file mode 100644 index 0000000000000..49f7bef355771 --- /dev/null +++ b/docs/docs/what-you-dont-need-plugins-for.md @@ -0,0 +1,13 @@ +--- +title: What You Don't Need Plugins For +--- + +Most third-party functionality you want to add to your website will follow standard JavaScript and React.js patterns for importing packages and composing UIs. These do not require a Gatsby plugin! + +Some examples: + +- Importing JavaScript packages that provide general functionality, such as `lodash` or `axios` +- Using React components or component libraries you want to include in your UI, such as `Ant Design`, `Material UI`, or the typeahead from your component library. +- Integrating visualization libraries, such as `Highcharts` or `d3`. + +As a general rule, you may use _any_ npm package you might use without Gatsby, with Gatsby. What plugins offer is a prepackaged integration into the core Gatsby APIs to save you time and energy, with minimal configuration. In the case of `Styled Components`, you could manually render the `Provider` component near the root of your application, or you could just use `gatsby-plugin-styled-components` which takes care of this step for you in addition to any other difficulties you may run into configuring Styled Components to work with server side rendering. diff --git a/docs/loading-plugins-from-your-local-plugins-folder.md b/docs/loading-plugins-from-your-local-plugins-folder.md new file mode 100644 index 0000000000000..fa6bbe3252620 --- /dev/null +++ b/docs/loading-plugins-from-your-local-plugins-folder.md @@ -0,0 +1,26 @@ +--- +Title: Loading Plugins from Your Local Plugins Folder +--- + +Gatsby can also load plugins from the your local website plugins folder which is a folder named `plugins` in the website's root directory. + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [`gatsby-local-plugin`], +} +``` + +If you want to reference a plugin that is not in the plugins folder then you could use something like the following: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [ + // Shortcut for adding plugins without options. + "gatsby-plugin-react-helmet", + { + // Standard plugin with options example + resolve: require.resolve(`/path/to/gatsby-local-plugin`), + }, + ], +} +``` diff --git a/www/gatsby-node.js b/www/gatsby-node.js index 18a300e2c0d0e..8afe72bf3604f 100644 --- a/www/gatsby-node.js +++ b/www/gatsby-node.js @@ -237,6 +237,18 @@ exports.createPages = ({ graphql, actions, reporter }) => { isPermanent: true, }) + createRedirect({ + fromPath: `/docs/source-plugin-tutorial/`, + toPath: `/docs/pixabay-source-plugin-tutorial/`, + isPermanent: true, + }) + + createRedirect({ + fromPath: `/docs/how-plugins-work/`, + toPath: `/docs/plugins/`, + isPermanent: true, + }) + createRedirect({ fromPath: `/blog/2018-2-16-how-to-build-a-website-with-react/`, toPath: `/blog/2019-01-16-how-to-build-a-website-with-react/`, diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 6db62884cfa44..3ef982b63502a 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -147,16 +147,35 @@ - title: Plugins link: /docs/plugins/ items: - - title: How Plugins Work - link: /docs/how-plugins-work/ - - title: Creating a Transformer Plugin - link: /docs/creating-a-transformer-plugin/ - - title: Creating a Source Plugin - link: /docs/creating-a-source-plugin/ - - title: Source Plugin Tutorial - link: /docs/source-plugin-tutorial/ + - title: What is a Plugin? + link: /docs/what-is-a-plugin/ + - title: Using a Plugin in Your Site + link: /docs/using-a-plugin-in-your-site/ + - title: What You Don't Need Plugins For + link: /docs/what-you-dont-need-plugins-for/ + - title: Loading Plugins from Your Local Plugins Folder + link: /docs/loading-plugins-from-your-local-plugins-folder/ - title: Plugin Library link: /plugins/ + - title: Creating Plugins + link: /docs/creating-plugins/ + items: + - title: Naming a Plugin + link: /docs/naming-a-plugin/ + - title: Files Gatsby Looks for in a Plugin + link: /docs/files-gatsby-looks-for-in-a-plugin/ + - title: Creating a Local Plugin + link: /docs/creating-a-local-plugin/ + - title: Creating a Source Plugin + link: /docs/creating-a-source-plugin/ + - title: Creating a Transformer Plugin + link: /docs/creating-a-transformer-plugin/ + - title: Submit to Plugin Library + link: /contributing/submit-to-plugin-library/ + - title: Pixabay Source Plugin Tutorial + link: /docs/pixabay-source-plugin-tutorial/ + - title: Maintaining a Plugin + link: /docs/maintaining-a-plugin/ - title: Starters link: /docs/starters/ items: