From 65d4301ccea89443a45ae26938f7c335c44bc665 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 22 Jan 2020 09:14:10 +0000 Subject: [PATCH 001/100] sync with monorepo gatsbyjs/gatsby@2a1508e3175082ec559a5405ba464bf3c9156128 - fix(gatsby): Improve `gatsby` TS types for `sourceNodes` (#20397) * fix(dts): improve `gatsby` TS types for `sourceNodes` * fix(dts): add schema prop to `NodePluginArgs` * chore: resolve PR requests Use Record instead of object mapping. --- docs/docs/how-gatsby-boosts-career.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/how-gatsby-boosts-career.md b/docs/docs/how-gatsby-boosts-career.md index 8a4784a..b10fff0 100644 --- a/docs/docs/how-gatsby-boosts-career.md +++ b/docs/docs/how-gatsby-boosts-career.md @@ -6,7 +6,7 @@ If you're a developer, and you've come to this section looking for tips about sp One, unintended, side effect: this is also good for your career. -As you ship Gatsby sites and get [other developers](/docs/winning-over-developers), [engineering leaders](/docs/winning-over-engineering-leaders), [marketers](/docs/winning-over-marketers) and [executives](/docs/winning-over-executives), and [clients](/docs/winning-over-executives) excited about Gatsby, you'll notice that you gain visibility, a reputation for driving results and business value. +As you ship Gatsby sites and get [other developers](/docs/winning-over-developers), [engineering leaders](/docs/winning-over-engineering-leaders), [marketers](/docs/winning-over-marketers) and [executives](/docs/winning-over-executives), and [clients](/docs/winning-over-clients) excited about Gatsby, you'll notice that you gain visibility, a reputation for driving results and business value. > Some insight on driving results forward from prominent React developer, Ryan Florence: https://twitter.com/ryanflorence/status/1104060348363988992 From c3cc76b560b83c5932f32fa1df94bb753ad5202b Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 22 Jan 2020 15:33:15 +0000 Subject: [PATCH 002/100] sync with monorepo gatsbyjs/gatsby@0a066b9227071c696bc4ec1db32358b7af1611df - fix italic format (#20761) --- docs/docs/recipes/styling-css.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/recipes/styling-css.md b/docs/docs/recipes/styling-css.md index 5f80bee..0c6fc9c 100644 --- a/docs/docs/recipes/styling-css.md +++ b/docs/docs/recipes/styling-css.md @@ -257,7 +257,7 @@ import "./styles.scss" import "./styles.sass" ``` -_Note: You can use Sass/SCSS files as modules too, like mentioned in the previous recipe about CSS modules, with the difference that instead of `.css` the extensions have to be `.scss` or `.sass_` +_Note: You can use Sass/SCSS files as modules too, like mentioned in the previous recipe about CSS modules, with the difference that instead of `.css` the extensions have to be `.scss` or `.sass`_ ### Additional resources From 71e12d0a77f8949d4a2cb27672a42297f12f5623 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 22 Jan 2020 19:16:22 +0000 Subject: [PATCH 003/100] sync with monorepo gatsbyjs/gatsby@930cd31b5c4bcf2b93c3297688a47c903f5af0c4 - chore(www): Make components used in MDX globally available (#20685) --- .../docs-and-website-components.md | 20 +++++++++---------- docs/contributing/index.mdx | 2 -- docs/docs/building-with-components.md | 2 -- docs/docs/gatsby-lifecycle-apis.md | 2 -- docs/docs/glossary.md | 2 -- docs/docs/graphql-concepts.md | 2 -- docs/docs/index.md | 2 -- .../overview-of-the-gatsby-build-process.md | 2 -- 8 files changed, 9 insertions(+), 25 deletions(-) diff --git a/docs/contributing/docs-and-website-components.md b/docs/contributing/docs-and-website-components.md index 0166a90..9e878dd 100644 --- a/docs/contributing/docs-and-website-components.md +++ b/docs/contributing/docs-and-website-components.md @@ -3,8 +3,6 @@ title: Docs and Website Components tableOfContentsDepth: 2 --- -import LayerModel from "../../www/src/components/layer-model" -import HorizontalNavList from "../../www/src/components/horizontal-nav-list" import Breadcrumb from "../../www/src/components/docs-breadcrumb" import { itemListContributing } from "../../www/src/utils/sidebar/item-list" import TableOfContents from "../../www/src/components/docs-table-of-contents" @@ -130,14 +128,6 @@ Rendered, the component looks like this: To improve is to change, so to be perfect is to have changed often. ---- - -## Other available components - -Other less commonly used components aren't globally available, but can imported at the top of a Markdown file and used in other docs. - ---- - ### Layer Model The `` was made to help explain concepts of how Gatsby works at a high level. It conceptually breaks Gatsby into different layers and shows how data is pulled, aggregated, and eventually rendered as an app. It's used on docs pages to help explain how Gatsby works at different levels. @@ -168,7 +158,7 @@ When used, it looks like this: ### Horizontal Navigation List -The `` was made for the [Glossary](/docs/glossary/), and renders a list of links to alphabetical subheadings on the page in a horizontal format. Because of its specific use case, it isn't made globally available but can be imported if needed on other pages. +The `` was made for the [Glossary](/docs/glossary/), and renders a list of links to alphabetical subheadings on the page in a horizontal format. #### Usage @@ -212,6 +202,14 @@ items={[ slug={props.slug} /> +--- + +## Other available components + +Other less commonly used components aren't globally available, but can imported at the top of a Markdown file and used in other docs. + +--- + ### Breadcrumb The `` component is used in layout files to display the hierarchy of pages a user is currently browsing on. diff --git a/docs/contributing/index.mdx b/docs/contributing/index.mdx index 798daf0..07b3cde 100644 --- a/docs/contributing/index.mdx +++ b/docs/contributing/index.mdx @@ -3,8 +3,6 @@ title: Contributing to Gatsby.js disableTableOfContents: true --- -import EmailCaptureForm from "../../www/src/components/email-capture-form" - Thanks for being interested in contributing! We're so glad you want to help! Below you'll find guides on the Gatsby.js community, code of conduct, and how to get started contributing: diff --git a/docs/docs/building-with-components.md b/docs/docs/building-with-components.md index 0e6ad13..d72ce31 100644 --- a/docs/docs/building-with-components.md +++ b/docs/docs/building-with-components.md @@ -2,8 +2,6 @@ title: Building with Components --- -import LayerModel from "../../www/src/components/layer-model" - To use Gatsby, you will need a basic understanding of React components. The [official tutorial](https://reactjs.org/tutorial/tutorial.html) diff --git a/docs/docs/gatsby-lifecycle-apis.md b/docs/docs/gatsby-lifecycle-apis.md index 8497bcd..64d7780 100644 --- a/docs/docs/gatsby-lifecycle-apis.md +++ b/docs/docs/gatsby-lifecycle-apis.md @@ -2,8 +2,6 @@ title: Gatsby Lifecycle APIs --- -import LayerModel from "../../www/src/components/layer-model" - Gatsby provides a rich set of lifecycle APIs to hook into its bootstrap, build, and client runtime operations. diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 18244e6..6aa376e 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -3,8 +3,6 @@ title: Glossary disableTableOfContents: true --- -import HorizontalNavList from "../../www/src/components/horizontal-nav-list.js" - When you're new to Gatsby there can be a lot of words to learn. This glossary aims to give you a 10,000-foot overview of common terms and what they mean for Gatsby sites. _This is a high-level overview about the steps in the Gatsby build process. For more detailed information about specific steps, check out the [Gatsby Internals](/docs/gatsby-internals) section of the docs._ From 0d19d3854e59c11251f912820a12938e4db1cb8c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 23 Jan 2020 14:33:28 +0000 Subject: [PATCH 004/100] sync with monorepo gatsbyjs/gatsby@3880394feccacc3e5503f02c7c5b3a3b784fb2a9 - fix: remove 1px line from gatsby-announcer on 100vh pages (#20781) --- docs/docs/performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/performance.md b/docs/docs/performance.md index cc49c73..469fd96 100644 --- a/docs/docs/performance.md +++ b/docs/docs/performance.md @@ -5,7 +5,7 @@ overview: true While performance is already at the heart of Gatsby, it's important to ensure you are doing all you can to make your content available to your users as fast as possible. Not all users are enjoying high speed connections, or browsing from a desktop. It's important to make no assumptions, and serve the smallest and fastest site possible, to provide an optimal experience for wherever your users might be coming from. Since Gatsby is already doing a lot of the heavy lifting for you there isn't a lot required to make your site blazing fast, but by following these guides you can ensure the best possible performance and delivery of your content to your users. -In this section we'll cover some ways you can optimize caching, set up `https` on `localhost` for easier testing of performance features, as well as how to measure the performance of your websites, giving you all the tools you need to max out your website's performance. If you would like a more in-depth explanation of why performance matters so much, check out [this article](https://medium.com/@addyosmani/the-cost-of-javascript-in-2018-7d8950fbb5d4) by Addy Osmani on the Cost of JavaScript. +In this section we'll cover some ways you can optimize caching, set up `https` on `localhost` for easier testing of performance features, as well as how to measure the performance of your websites, giving you all the tools you need to max out your website's performance. If you would like a more in-depth explanation of why performance matters so much, check out [this article](https://v8.dev/blog/cost-of-javascript-2019) by Addy Osmani on the Cost of JavaScript. May your Lighthouse scores all be in the green. 😀 From 4968ece62ea808565e99977a0a5764844c70af16 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 23 Jan 2020 17:30:52 +0000 Subject: [PATCH 005/100] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@119c345bd4cb8f45649fe547bdfcbdf38a56e8e1=20-=20chore(doc):=20?= =?UTF-8?q?Listing=20new=20gatsby=20theme=20recipe=20on=20recipes=20landin?= =?UTF-8?q?g=E2=80=A6=20(#20817)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/recipes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md index f3bc3e5..13e6d53 100644 --- a/docs/docs/recipes.md +++ b/docs/docs/recipes.md @@ -64,6 +64,7 @@ There are so many ways to add styles to your website; Gatsby supports almost eve A Gatsby theme lets you centralize the look-and-feel of your site. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another. +- [Creating a new site using a theme](/docs/recipes/working-with-themes#creating-a-new-site-using-a-theme) - [Creating a new site using a theme starter](/docs/recipes/working-with-themes#creating-a-new-site-using-a-theme-starter) - [Building a new theme](/docs/recipes/working-with-themes#building-a-new-theme) From 15e5ec76b528862c9b5f0753ad46d53a17497b7e Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 23 Jan 2020 19:02:00 +0000 Subject: [PATCH 006/100] sync with monorepo gatsbyjs/gatsby@631a3aeb4d1760ccc3df1cde2097fe36b5629c92 - Fix typos in recipes/working-with-themes.md (#20775) A few various typos on this file (most likely due to haste in writing!). Have found and corrected all typos. --- docs/docs/recipes/working-with-themes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/recipes/working-with-themes.md b/docs/docs/recipes/working-with-themes.md index 23df826..4fd2059 100644 --- a/docs/docs/recipes/working-with-themes.md +++ b/docs/docs/recipes/working-with-themes.md @@ -10,7 +10,7 @@ Found a theme you'd like to use on your project? Awesome! You can configure it f > If you'd like to take a look at more theme options, check out [list of themes](https://www.npmjs.com/search?q=gatsby-theme). -### Prerequisities +### Prerequisites Make sure you have the following installed: @@ -60,9 +60,9 @@ module.exports = { } ``` -4. Run `yarn develop` , the theme should be avaliable at `http://localhost:8000/{basePath}` +4. Run `yarn develop` , the theme should be available at `http://localhost:8000/{basePath}` -> To learn how to further customize a theme,check out the avaliabe paths on [Gatsby-theme-blog Documentation](https://www.npmjs.com/package/gatsby-theme-blog). +> To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](https://www.npmjs.com/package/gatsby-theme-blog). ### Additional resources From f61463a0b1ce6852907b5d9cf0a5cac014b5775c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 23 Jan 2020 20:50:05 +0000 Subject: [PATCH 007/100] sync with monorepo gatsbyjs/gatsby@d5f6bebe56fa74b3a33be77a35d0e9e9c17fadd5 - chore(docs): Use soft wraps for old docs (#20813) * use-soft-line-wraps-for-docs/how-shadowing-works * use-soft-line-wraps-for-docs/add-404-page * use-soft-line-wraps-for-docs/add-custom-webpack-config * use-soft-line-wraps-for-docs/basic-hardware-software-requirements --- docs/docs/add-404-page.md | 21 +-- docs/docs/add-custom-webpack-config.md | 43 ++---- .../basic-hardware-software-requirements.md | 3 +- docs/docs/how-shadowing-works.mdx | 135 +++++------------- 4 files changed, 52 insertions(+), 150 deletions(-) diff --git a/docs/docs/add-404-page.md b/docs/docs/add-404-page.md index 9a1f0cb..967057b 100644 --- a/docs/docs/add-404-page.md +++ b/docs/docs/add-404-page.md @@ -2,26 +2,15 @@ title: Adding a 404 Page --- -To create a 404 page create a page whose path matches the regex -`^\/?404\/?$` (`/404/`, `/404`, `404/` or `404`). Most often you'll want to create a React component page at -`src/pages/404.js`. +To create a 404 page create a page whose path matches the regex `^\/?404\/?$` (`/404/`, `/404`, `404/` or `404`). Most often you'll want to create a React component page at `src/pages/404.js`. -Gatsby ensures that your 404 page is built as `404.html` as many static hosting -platforms default to using this as your 404 error page. If you're hosting your -site another way, you'll need to set up a custom rule to serve this file for 404 -errors. +Gatsby ensures that your 404 page is built as `404.html` as many static hosting platforms default to using this as your 404 error page. If you're hosting your site another way you'll need to set up a custom rule to serve this file for 404 errors. -Because Gatsby creates this page for you by default, there is no need to configure -it in your `gatsby-node.js` file. +Because Gatsby creates this page for you by default, there is no need to configure it in your `gatsby-node.js` file. -When developing using `gatsby develop`, Gatsby uses a default 404 page that -overrides your custom 404 page. However, you can still preview your 404 page by -clicking "Preview custom 404 page" to verify that it's working as expected. This is -useful when you're developing so that you can see all the available pages. +When developing using `gatsby develop`, Gatsby uses a default 404 page that overrides your custom 404 page. However, you can still preview your 404 page by clicking "Preview custom 404 page" to verify that it's working as expected. This is useful when you're developing so that you can see all the available pages. -The screenshot below shows the default 404 page that Gatsby creates. -It also lists out all the pages on your website. Clicking the "Preview custom 404 -page" button will allow you to view the 404 page you created. +The screenshot below shows the default 404 page that Gatsby creates. It also lists out all the pages on your website. Clicking the "Preview custom 404 page" button will allow you to view the 404 page you created. ![Gatsby Default 404 Page](./images/gatsby-default-404.png) The screenshot below shows the custom 404 page. diff --git a/docs/docs/add-custom-webpack-config.md b/docs/docs/add-custom-webpack-config.md index 70384ee..60a40ee 100644 --- a/docs/docs/add-custom-webpack-config.md +++ b/docs/docs/add-custom-webpack-config.md @@ -2,39 +2,22 @@ title: "Adding a Custom Webpack Config" --- -_Before creating custom webpack configuration, check to see if there's a Gatsby -plugin already built that handles your use case in the -[plugins section](/docs/plugins/). If there's not yet one and your use case is a -general one, it is highly encouraged you to contribute back your plugin to the -Gatsby Plugin Library so it's available to others (including your future self)._ - -To add custom webpack configurations, create (if there's not one already) a -`gatsby-node.js` file in your root directory. Inside this file, export a -function called `onCreateWebpackConfig`. - -When Gatsby creates its webpack config, this function will be called allowing -you to modify the default webpack config using -[webpack-merge](https://github.com/survivejs/webpack-merge). - -Gatsby does multiple webpack builds with somewhat different configuration. Gatsby -calls each build type a "stage". The following stages exist: - -1. develop: when running the `gatsby develop` command. Has configuration for hot - reloading and CSS injection into page -2. develop-html: same as develop but without react-hmre in the babel config for - rendering the HTML component. -3. build-javascript: production JavaScript and CSS build. Creates route JS bundles as well - as common chunks for JS and CSS. +_Before creating custom webpack configuration, check to see if there's a Gatsby plugin already built that handles your use case in the [plugins section](/docs/plugins/). If there's not yet one and your use case is a general one, it is highly encouraged you to contribute back your plugin to the Gatsby Plugin Library so it's available to others (including your future self)._ + +To add custom webpack configurations, create (if there's not one already) a `gatsby-node.js` file in your root directory. Inside this file, export a function called `onCreateWebpackConfig`. + +When Gatsby creates its webpack config, this function will be called allowing you to modify the default webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge). + +Gatsby does multiple webpack builds with somewhat different configuration. Gatsby calls each build type a "stage". The following stages exist: + +1. develop: when running the `gatsby develop` command. Has configuration for hot reloading and CSS injection into page +2. develop-html: same as develop but without react-hmre in the babel config for rendering the HTML component. +3. build-javascript: production JavaScript and CSS build. Creates route JS bundles as well as common chunks for JS and CSS. 4. build-html: production build static HTML pages -Check -[webpack.config.js](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/webpack.config.js) -for the source. +Check [webpack.config.js](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/webpack.config.js) for the source. -There are many plugins in the Gatsby repo using this API to look to for examples -e.g. [Sass](/packages/gatsby-plugin-sass/), -[TypeScript](/packages/gatsby-plugin-typescript/), -[Glamor](/packages/gatsby-plugin-glamor/), and many more! +There are many plugins in the Gatsby repo using this API to look to for examples e.g. [Sass](/packages/gatsby-plugin-sass/), [TypeScript](/packages/gatsby-plugin-typescript/), [Glamor](/packages/gatsby-plugin-glamor/), and many more! ## Examples diff --git a/docs/docs/basic-hardware-software-requirements.md b/docs/docs/basic-hardware-software-requirements.md index 302b65b..4c125f9 100644 --- a/docs/docs/basic-hardware-software-requirements.md +++ b/docs/docs/basic-hardware-software-requirements.md @@ -4,5 +4,4 @@ title: Basic Hardware and Software Requirements This is a stub. Help our community expand it. -Please use the [Gatsby Style Guide](/contributing/gatsby-style-guide/) to ensure your -pull request gets accepted. +Please use the [Gatsby Style Guide](/contributing/gatsby-style-guide/) to ensure your pull request gets accepted. diff --git a/docs/docs/how-shadowing-works.mdx b/docs/docs/how-shadowing-works.mdx index c2bd169..c255837 100644 --- a/docs/docs/how-shadowing-works.mdx +++ b/docs/docs/how-shadowing-works.mdx @@ -2,25 +2,17 @@ title: How Shadowing Works --- -Shadowing is a powerful feature that allows theme users to override components, -objects, and anything else in a theme's `src` directory. +Shadowing is a powerful feature that allows theme users to override components, objects, and anything else in a theme's `src` directory. > **Note** This is a technical deep dive into how Shadowing works. If you'd > like to learn about what Shadowing is, see the [What is Component Shadowing?](/blog/2019-04-29-component-shadowing/) > blog post. -Shadowing works by using a [webpack resolver plugin](https://webpack.js.org/api/resolvers/) -that maps themes in a `gatsby-config.js` to possible shadowed files. This gets -especially mind melty because themes can add parent themes to a configuration so you -need to be able to walk the composition of themes to determine the "last shadow" -since the last shadowed theme file wins in the algorithm. +Shadowing works by using a [webpack resolver plugin](https://webpack.js.org/api/resolvers/) that maps themes in a `gatsby-config.js` to possible shadowed files. This gets especially mind melty because themes can add parent themes to a configuration so you need to be able to walk the composition of themes to determine the "last shadow" since the last shadowed theme file wins in the algorithm. ## Theme Composition -It's important to begin discussing how the composition of themes works. An -end user of a theme can configure any number of themes. Each of these -themes are considered sibling themes. Here is a `gatsby-config.js` that -configures two sibling themes: +It's important to begin discussing how the composition of themes works. An end user of a theme can configure any number of themes. Each of these themes are considered sibling themes. Here is a `gatsby-config.js` that configures two sibling themes: ```js:title=gatsby-config.js module.exports = { @@ -31,9 +23,7 @@ module.exports = { } ``` -Both of the themes above (blog and portfolio) can install and configure -any other theme so you end up with a tree of themes which we call a theme -composition. +Both of the themes above (blog and portfolio) can install and configure any other theme so you end up with a tree of themes which we call a theme composition. The theme composition itself has a few properties: @@ -42,10 +32,7 @@ The theme composition itself has a few properties: - a theme that is used by another theme is the parent theme - theme trees are flattened during resolution -These characteristics are used in the component shadowing algorithm -to decide which component to render. So, for example, if `gatsby-theme-tomato-blog` -has `gatsby-theme-parent` as a parent theme it results in the following themes -array: +These characteristics are used in the component shadowing algorithm to decide which component to render. So, for example, if `gatsby-theme-tomato-blog` has `gatsby-theme-parent` as a parent theme it results in the following themes array: ```js const themesArray = [ @@ -55,14 +42,11 @@ const themesArray = [ ] ``` -This means that `gatsby-theme-tomato-portfolio` receives priority for -component resolution, because it is last in the array. +This means that `gatsby-theme-tomato-portfolio` receives priority for component resolution, because it is last in the array. ## Modifying the webpack Config -Component shadowing is a bit meta because it is implemented as an internal -Gatsby plugin that applies a webpack plugin which modifies how module -resolution happens for files that are shadowed. +Component shadowing is a bit meta because it is implemented as an internal Gatsby plugin that applies a webpack plugin which modifies how module resolution happens for files that are shadowed. The plugin consists of a `gatsby-node.js` and the webpack plugin code. The `gatsby-node` file is pretty straightforward: @@ -95,18 +79,11 @@ exports.onCreateWebpackConfig = ( } ``` -We first check for themes in the redux store. This is for -backwards-compatibility since themes are now merged with -plugins. If the `themes` key was used in the user's -`gatsby-config.js` those are passed to the shadowing resolver -plugin. Otherwise, the flattened plugin list is passed. +We first check for themes in the redux store. This is for backwards-compatibility since themes are now merged with plugins. If the `themes` key was used in the user's `gatsby-config.js` those are passed to the shadowing resolver plugin. Otherwise, the flattened plugin list is passed. ## Structure of a webpack Plugin -The webpack plugin itself has a constructor and an apply function which -webpack calls as part of module resolution. We tie into the "relative" -hook in [the -pipeline](https://github.com/webpack/enhanced-resolve/blob/5c1495a947060cf11106abc325b8adf1a0eff9b1/lib/ResolverFactory.js#L158). +The webpack plugin itself has a constructor and an apply function which webpack calls as part of module resolution. We tie into the "relative" hook in [the pipeline](https://github.com/webpack/enhanced-resolve/blob/5c1495a947060cf11106abc325b8adf1a0eff9b1/lib/ResolverFactory.js#L158). ```js:title=packages/gatsby/src/internal-plugins/webpack-theme-component-shadowing/index.js module.exports = class GatsbyThemeComponentShadowingResolverPlugin { @@ -126,8 +103,7 @@ module.exports = class GatsbyThemeComponentShadowingResolverPlugin { ### Get matching themes -The `request` contains the path of the file which we want to use to find -potential matches in themes. +The `request` contains the path of the file which we want to use to find potential matches in themes. ```js resolver.plugin(`relative`, (request, callback) => { @@ -156,28 +132,17 @@ module.exports = class GatsbyThemeComponentShadowingResolverPlugin { } ``` -This is run for all files in the site bundle and checks for potential matches. -So, if a request is `/some/path/my-site/gatsby-theme-tomato/src/button/heading.js` -and `gatsby-theme-tomato` is installed on the site, we'll return `gatsby-theme-tomato`. +This is run for all files in the site bundle and checks for potential matches. So, if a request is `/some/path/my-site/gatsby-theme-tomato/src/button/heading.js` and `gatsby-theme-tomato` is installed on the site, we'll return `gatsby-theme-tomato`. -We perform this match so that we can determine the theme that is being required -from so we can check for shadowed files in the user's site or other themes to match -against. We also make sure the matched themes are unique because two themes can -bring in the same theme to the theme composition. When that's the case we won't worry -about them being different. Though, it is important to note that when performing -resolution to build the site, the last theme added will always win. +We perform this match so that we can determine the theme that is being required from so we can check for shadowed files in the user's site or other themes to match against. We also make sure the matched themes are unique because two themes can bring in the same theme to the theme composition. When that's the case we won't worry about them being different. Though, it is important to note that when performing resolution to build the site, the last theme added will always win. #### Handle too many matches -Next, we check to make sure that if there is more than one matching theme there -is some sort of ambiguity and we should return an error. This can happen if there's -a path like `gatsby-theme-blog/src/components/gatsby-theme-something/src/components` -in the project. +Next, we check to make sure that if there is more than one matching theme there is some sort of ambiguity and we should return an error. This can happen if there's a path like `gatsby-theme-blog/src/components/gatsby-theme-something/src/components` in the project. #### No matches -If there are no theme matches we return the invoked callback because there's nothing -more to do, time to let webpack continue on it's way with module resolution. +If there are no theme matches we return the invoked callback because there's nothing more to do, time to let webpack continue on it's way with module resolution. ```js if (matchingThemes.length === 0) { @@ -187,26 +152,18 @@ if (matchingThemes.length === 0) { ### The matched theme -Now, if we still haven't returned the callback or thrown an error (due to ambiguity) it means we -have a file being required from a theme. The file being required will look something -like `/some/path/my-site/gatsby-theme-tomato/src/box` and so the first thing we -want to do is get the relative path for the file within the theme's `src` directory: +Now, if we still haven't returned the callback or thrown an error (due to ambiguity) it means we have a file being required from a theme. The file being required will look something like `/some/path/my-site/gatsby-theme-tomato/src/box` and so the first thing we want to do is get the relative path for the file within the theme's `src` directory: ```js const [theme] = matchingThemes const [, component] = request.path.split(path.join(theme, `src`)) ``` -So, with the example path above we'll end up with `/box`. This can then be used to -see if the user's site or any other themes are shadowing the file. +So, with the example path above we'll end up with `/box`. This can then be used to see if the user's site or any other themes are shadowing the file. ### The component shadow -Since a file from a theme is being required we need to figure out which path should -be resolved for the requested component. We do this by calling `resolveComponentPath` -which uses the theming algorithm to attempt to find a shadowed component. If nothing -is found we return the original request which points at the original theme's -component. +Since a file from a theme is being required we need to figure out which path should be resolved for the requested component. We do this by calling `resolveComponentPath` which uses the theming algorithm to attempt to find a shadowed component. If nothing is found we return the original request which points at the original theme's component. ```js const builtComponentPath = this.resolveComponentPath({ @@ -224,9 +181,7 @@ return resolver.doResolve( ) ``` -We call `doResolve` on the resolver which specifies the shadowed component path if -one is found, otherwise the original request. This is what tells webpack to resolve -and bundle that particular file. +We call `doResolve` on the resolver which specifies the shadowed component path if one is found, otherwise the original request. This is what tells webpack to resolve and bundle that particular file. #### Resolving a shadowed component @@ -237,18 +192,11 @@ When looking for a component we perform a search that occurs in two locations: ##### User's project -In order to ensure that the user's project always takes precedence in terms of shadowing -it's prepended to the theme list when attempting to resolve the component. This ensures that -`my-site/src/gatsby-theme-tomato/box.js` will take priority over any other theme that -might want to shadow the same component. +In order to ensure that the user's project always takes precedence in terms of shadowing it's prepended to the theme list when attempting to resolve the component. This ensures that `my-site/src/gatsby-theme-tomato/box.js` will take priority over any other theme that might want to shadow the same component. ##### Themes -As discussed before, themes are flattened into a list and then all possible shadow -paths are constructed to match against. When concatenating with the user's project it's -important to note again that the themes array is reversed. This is how we ensure that -"the last theme wins" when resolving a shadowed file. We walk the list for matches -from start to finish. +As discussed before, themes are flattened into a list and then all possible shadow paths are constructed to match against. When concatenating with the user's project it's important to note again that the themes array is reversed. This is how we ensure that "the last theme wins" when resolving a shadowed file. We walk the list for matches from start to finish. ```js const locationsToCheck = [ @@ -263,8 +211,7 @@ const locationsToCheck = [ ) ``` -Additionally, the original theme is removed because that's the default -behavior of webpack so we don't need to resolve a theme to itself. +Additionally, the original theme is removed because that's the default behavior of webpack so we don't need to resolve a theme to itself. ```js const themes = ogThemes.filter(({ themeName }) => themeName !== theme) @@ -272,8 +219,7 @@ const themes = ogThemes.filter(({ themeName }) => themeName !== theme) #### All together -The shadowing algorithm can be boiled down the following function that's -roughly 20 lines of code: +The shadowing algorithm can be boiled down the following function that's roughly 20 lines of code: ```js resolveComponentPath({ @@ -322,9 +268,7 @@ resolveComponentPath({ ### Handling component extending -This is where things begin to get a bit whacky. In addition to overriding a file, -we want it to be possible to import the very component you're shadowing so that -you can wrap it or even add props. +This is where things begin to get a bit whacky. In addition to overriding a file, we want it to be possible to import the very component you're shadowing so that you can wrap it or even add props. ```js import React from "react" @@ -342,12 +286,10 @@ export default props => ( This is the first case we'll handle when attempting to resolve the file. -In order to do this we need to leverage the **issuer** of the request. This points to -the file that the request came from. This means it refers to _where_ the `import` occurs. +In order to do this we need to leverage the **issuer** of the request. This points to the file that the request came from. This means it refers to _where_ the `import` occurs. The **request** refers to what the import points to. -This is implemented by another method on the plugin's class which we call -`requestPathIsIssuerShadowPath` which has the following method signature: +This is implemented by another method on the plugin's class which we call `requestPathIsIssuerShadowPath` which has the following method signature: ```js requestPathIsIssuerShadowPath({ @@ -358,9 +300,7 @@ requestPathIsIssuerShadowPath({ }) ``` -`requestPathIsIssuerShadowPath` checks all possible directories for shadowing and -then returns whether the issuer's path is found. Let's first take a look at the -code and then unpack what's happening here. +`requestPathIsIssuerShadowPath` checks all possible directories for shadowing and then returns whether the issuer's path is found. Let's first take a look at the code and then unpack what's happening here. ```js requestPathIsIssuerShadowPath({ requestPath, issuerPath, theme }) { @@ -391,15 +331,11 @@ const fullPaths = [ ] ``` -We then know that if the issuer _matches_ one of these components that it's -being extended. This means that a shadowed component is extending the same component -from its parent. +We then know that if the issuer _matches_ one of these components that it's being extended. This means that a shadowed component is extending the same component from its parent. -When this happens, we return the next path, so here the original location of the theme: -`/Users/johno/c/gatsby-theme-example-component-extending/gatsby-theme-tomato/src/box`. +When this happens, we return the next path, so here the original location of the theme: `/Users/johno/c/gatsby-theme-example-component-extending/gatsby-theme-tomato/src/box`. -This means that when our shadowed file imports Box from a shadowed file we return the -original box component defined in the theme. +This means that when our shadowed file imports Box from a shadowed file we return the original box component defined in the theme. As a result, the following will work as we expect: @@ -415,21 +351,16 @@ export default props => ( ) ``` -Now, all usages of the Box in `gatsby-theme-tomato` will be also wrapped in a purple -box. +Now, all usages of the Box in `gatsby-theme-tomato` will be also wrapped in a purple box. #### An edge case -If a theme sets [`module` config](https://webpack.js.org/configuration/resolve/#resolvemodules) -the issuer will be null. As such we need to first check that the `request.context.issuer` -is present before we attempt to resolve the shadowed component. +If a theme sets [`module` config](https://webpack.js.org/configuration/resolve/#resolvemodules) the issuer will be null. As such we need to first check that the `request.context.issuer` is present before we attempt to resolve the shadowed component. It's important to note that we don't recommend appending to the modules list in themes. Though, if you do, we will make sure we don't arbitrarily error. ## Summary -Shadowing uses a predictable algorithm that leverages webpack to dynamically -change module resolution based on a `gatsby-config` and theme composition. -The last theme will take precedence in the shadowing algorithm, and the -user's `src` directory is always take into account first. +Shadowing uses a predictable algorithm that leverages webpack to dynamically change module resolution based on a `gatsby-config` and theme composition. +The last theme will take precedence in the shadowing algorithm, and the user's `src` directory is always take into account first. From e7860d092d7b1f5a2acd507d8159c535ae41c9de Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 24 Jan 2020 15:18:46 +0000 Subject: [PATCH 008/100] sync with monorepo gatsbyjs/gatsby@6c7b2160e5a81bedc4d5418cbf72e1f4f218052e - Update sites.yml (#20792) Adding the personal website of Maarten Afink (https://www.maarten.im/) Co-authored-by: Ekwuno Obinna --- docs/docs/glossary.md | 2 +- docs/docs/glossary/headless-cms.md | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 docs/docs/glossary/headless-cms.md diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 6aa376e..45b6d98 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -148,7 +148,7 @@ A [query](#query) language that allows you to pull data into your website or app A markup language that every web browser is able to understand. It stands for Hypertext Markup Language. [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) gives your web content a universal informational structure, defining things like headings, paragraphs, and more. It is also key to providing an accessible website. -### Headless CMS +### [Headless CMS](/docs/glossary/headless-cms) A [CMS](#cms) that only handles the [backend](#backend) content management instead of handling both the backend and [frontend](#frontend). This type of setup is also referred to as [Decoupled](#decoupled). diff --git a/docs/docs/glossary/headless-cms.md b/docs/docs/glossary/headless-cms.md new file mode 100644 index 0000000..7fb2d54 --- /dev/null +++ b/docs/docs/glossary/headless-cms.md @@ -0,0 +1,22 @@ +--- +title: Headless CMS +disableTableOfContents: true +--- + +Learn what a Headless CMS is, how it differs from traditional content management systems, and why you might choose a headless CMS for your project. + +## What is a Headless CMS? + +A _headless content management system_ or _headless CMS_, is a CMS in which the content is separated from its presentation. Content management systems such as WordPress and Drupal store content in a database, and use a collection of HTML-based template files to manage how that content gets presented to visitors. + +Headless content mananagement systems, on the other hand, return structured data from an [API](/docs/glossary/#api). Rather than merging templates and content to create HTML, a headless CMS returns JSON or unstyled XML. Content creators still use an editing interface to add content to a headless CMS, but the [backend](/docs/glossary#backend) management of the site's content is [_decoupled_](/docs/glossary#decoupled) from the [frontend](/docs/glossary#frontend) that displays it. + +When your content is available as structured data, it's available to any client or application that can consume that data whether a [JAMStack](/docs/glossary/jamstack) application, or a mobile device. You can use a headless CMS to provide [JSON content source](/docs/sourcing-content-from-json-or-yaml/) for your Gatsby site and your other content channels. + +With plugins, Gatsby supports several [headless CMS](/docs/headless-cms/) services, including [Contentful](https://www.contentful.com/), [Ghost](https://ghost.org/pricing/) and [Prismic](https://prismic.io/). If you use WordPress, there's no need to switch. You can use WordPress' [REST API](/docs/sourcing-from-wordpress/) as a headless CMS, so that your content team can continue to use the editing tools with which they're familiar. + +## Learn More + +- [What is a Headless CMS and How to Source Content from One](/docs/headless-cms/), from the Gatsby docs +- [3 Free Headless CMS's for Your Next Project](/blog/2019-10-15-free-headless-cms/), from the Gatsby blog +- [Building Sites with Headless CMSs](/blog/2018-2-3-sites-with-headless-cms/#reach-skip-nav), also from Gatsby blog From af309728b5c205ee31da0d13dae0dcd5b2041b12 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 24 Jan 2020 15:22:31 +0000 Subject: [PATCH 009/100] sync with monorepo gatsbyjs/gatsby@e77f39c0f53ec571184c189521b0437a85341c88 - chore: add inline codeblocks around some text for readability (#20720) * Update post-css.md * Update tailwind-css.md * Update bulma.md --- docs/docs/bulma.md | 4 ++-- docs/docs/post-css.md | 2 +- docs/docs/tailwind-css.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/bulma.md b/docs/docs/bulma.md index ea00f39..8c06590 100644 --- a/docs/docs/bulma.md +++ b/docs/docs/bulma.md @@ -22,7 +22,7 @@ plugins: [`gatsby-plugin-sass`], Now is the time to create a scss-file that holds your simple style customisation and the import statement for bulma. -(To keep things simple, insert the file next to index.js in the pages-directory) +(To keep things simple, insert the file next to `index.js` in the pages-directory) ```scss:title=mystyles.scss @charset "utf-8"; @@ -37,7 +37,7 @@ $title-color: #ff0000; The last step is to import the style and use it. -Replace the default contents of the index.js file. +Replace the default contents of the `index.js` file. ```jsx:title=index.js import React from "react" diff --git a/docs/docs/post-css.md b/docs/docs/post-css.md index d2eec9e..8c94af5 100644 --- a/docs/docs/post-css.md +++ b/docs/docs/post-css.md @@ -22,7 +22,7 @@ plugins: [`gatsby-plugin-postcss`], > **Note**: If you need to pass options to PostCSS use the plugins options; see [postcss-loader](https://github.com/postcss/postcss-loader) for all available options. -3. Write your stylesheets using PostCSS (.css files) and require or import them as normal. +3. Write your stylesheets using PostCSS (`.css` files) and require or import them as normal. ```css:title=styles.css @custom-media --med (width <= 50rem); diff --git a/docs/docs/tailwind-css.md b/docs/docs/tailwind-css.md index b65fbbf..b3ace84 100644 --- a/docs/docs/tailwind-css.md +++ b/docs/docs/tailwind-css.md @@ -50,7 +50,7 @@ plugins: [`gatsby-plugin-postcss`], 3. Configure PostCSS to use Tailwind -Create a postcss.config.js in your project's root folder with the following contents. +Create a `postcss.config.js` in your project's root folder with the following contents. ```javascript:title=postcss.config.js module.exports = () => ({ @@ -89,7 +89,7 @@ npm install tailwindcss@0.7.4 npm install tailwind.macro ``` -2. Use the Babel Macro (tailwind.macro) in your styled component +2. Use the Babel Macro (`tailwind.macro`) in your styled component ```javascript import styled from "styled-components" From 79514160bec1688f9af7941941bb3dac3225b5da Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 24 Jan 2020 21:53:03 +0000 Subject: [PATCH 010/100] sync with monorepo gatsbyjs/gatsby@8d521b25496ddd38700939ef85d5bf3283b010d6 - Update file path for bio-content (#20845) Minor path change: Src needed to come first. --- docs/tutorial/using-a-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/using-a-theme.md b/docs/tutorial/using-a-theme.md index c02fea4..d7f5ff5 100644 --- a/docs/tutorial/using-a-theme.md +++ b/docs/tutorial/using-a-theme.md @@ -65,7 +65,7 @@ module.exports = { When using Gatsby themes, you can take advantage of something called component shadowing. This allows you to override the default component included in the theme with a custom one you've created. -The Gatsby blog theme package has a component that contains the content of the site author's biography. The file path to that component (in the blog theme package, not your site) is `gatsby-theme-blog/src/components/bio-content.js`. You can find this path by looking through the theme in your site's `node_modules/gatsby-theme-blog` directory. +The Gatsby blog theme package has a component that contains the content of the site author's biography. The file path to that component (in the blog theme package, not your site) is `src/gatsby-theme-blog/components/bio-content.js`. You can find this path by looking through the theme in your site's `node_modules/gatsby-theme-blog` directory. If you look at the file tree of your site, you'll see it looks like this: From 2f756f780eabbac3f358d7bb49f118971bc9ba44 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 24 Jan 2020 22:22:32 +0000 Subject: [PATCH 011/100] sync with monorepo gatsbyjs/gatsby@106e74f4a4f1424aa0e32663c14cea6c74bf78b0 - Update docs on creating redirects (#20806) --- docs/contributing/docs-contributions.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md index b6af6c8..d3e48c8 100644 --- a/docs/contributing/docs-contributions.md +++ b/docs/contributing/docs-contributions.md @@ -109,14 +109,11 @@ Sometimes it makes sense to move or rename a file as part of docs restructuring - Run proposed structure changes by the Gatsby docs team in [a GitHub issue](/contributing/how-to-file-an-issue/) to ensure your change is accepted. - Update all instances of the old URL to your new one. [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) in VS Code can help. Check that the context of the original link reference still makes sense with the new one. -- For SEO purposes, add a redirect to the `createPages` function in [`www/gatsby-node.js`](https://github.com/gatsbyjs/gatsby/tree/master/www/gatsby-node.js). Here's an example: - -```js:title=www/gatsby-node.js -createRedirect({ - fromPath: `/docs/source-plugin-tutorial/`, - toPath: `/docs/pixabay-source-plugin-tutorial/`, - isPermanent: true, -}) +- For SEO purposes, add a redirect to [`www/redirects.yaml`](https://github.com/gatsbyjs/gatsby/tree/master/www/redirects.yaml). Here's an example: + +```yaml:title=www/redirects.yaml +- fromPath: /docs/source-plugin-tutorial/ + toPath: /docs/pixabay-source-plugin-tutorial/ ``` ## Claim your swag From 33261b04622a9ee8e556dd9f5c47275393dbf242 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sat, 25 Jan 2020 07:05:00 +0000 Subject: [PATCH 012/100] sync with monorepo gatsbyjs/gatsby@232de9bb554af3101ef64eb549054d48f3982a6f - Docs: fix typo (#20859) --- docs/tutorial/ecommerce-tutorial/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/ecommerce-tutorial/index.md b/docs/tutorial/ecommerce-tutorial/index.md index 57c648f..8c89e76 100644 --- a/docs/tutorial/ecommerce-tutorial/index.md +++ b/docs/tutorial/ecommerce-tutorial/index.md @@ -87,7 +87,7 @@ Stripe provides a JavaScript library the allows you to securely redirect your cu to the end of the `` tag across all of your pages. This helps facilitate Stripe's [fraud detection](https://stripe.com/docs/stripe-js/reference#including-stripejs). -If you want to further customise the checkout process or pull Stripe data into your site, check out [Gatsby's plugin library for more Stripe plugins](https://www.gatsbyjs.org/plugins/?=stripe). +If you want to further customize the checkout process or pull Stripe data into your site, check out [Gatsby's plugin library for more Stripe plugins](https://www.gatsbyjs.org/plugins/?=stripe). ### Getting your Stripe test keys @@ -185,7 +185,7 @@ export default Checkout #### What did you just do? -You imported React, added a button with some styles, and introduced some React functions. The `componentDidMount()` and `redirectToCheckout()` functions are most important for the Stripe functionality. The `componentDidMount()` function is a React lifecycle method that launches when the component is first mounted to the DOM, making it a good place to initialise the Stripe.js client. It looks like this: +You imported React, added a button with some styles, and introduced some React functions. The `componentDidMount()` and `redirectToCheckout()` functions are most important for the Stripe functionality. The `componentDidMount()` function is a React lifecycle method that launches when the component is first mounted to the DOM, making it a good place to initialize the Stripe.js client. It looks like this: ```jsx:title=src/components/checkout.js componentDidMount() { From 887dd5b4c8b2d9ed2e77322c0f4c4df001ee5989 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sat, 25 Jan 2020 17:38:32 +0000 Subject: [PATCH 013/100] sync with monorepo gatsbyjs/gatsby@fe40bcead7200f0c9eed122c7affb76fe476bfca - fixed a typo (#20868) changed "mananagement" to "management" in "Content Management System" --- docs/docs/glossary/headless-cms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary/headless-cms.md b/docs/docs/glossary/headless-cms.md index 7fb2d54..e5e76ca 100644 --- a/docs/docs/glossary/headless-cms.md +++ b/docs/docs/glossary/headless-cms.md @@ -9,7 +9,7 @@ Learn what a Headless CMS is, how it differs from traditional content management A _headless content management system_ or _headless CMS_, is a CMS in which the content is separated from its presentation. Content management systems such as WordPress and Drupal store content in a database, and use a collection of HTML-based template files to manage how that content gets presented to visitors. -Headless content mananagement systems, on the other hand, return structured data from an [API](/docs/glossary/#api). Rather than merging templates and content to create HTML, a headless CMS returns JSON or unstyled XML. Content creators still use an editing interface to add content to a headless CMS, but the [backend](/docs/glossary#backend) management of the site's content is [_decoupled_](/docs/glossary#decoupled) from the [frontend](/docs/glossary#frontend) that displays it. +Headless content management systems, on the other hand, return structured data from an [API](/docs/glossary/#api). Rather than merging templates and content to create HTML, a headless CMS returns JSON or unstyled XML. Content creators still use an editing interface to add content to a headless CMS, but the [backend](/docs/glossary#backend) management of the site's content is [_decoupled_](/docs/glossary#decoupled) from the [frontend](/docs/glossary#frontend) that displays it. When your content is available as structured data, it's available to any client or application that can consume that data whether a [JAMStack](/docs/glossary/jamstack) application, or a mobile device. You can use a headless CMS to provide [JSON content source](/docs/sourcing-content-from-json-or-yaml/) for your Gatsby site and your other content channels. From 1ca4bab73097d478211c965fcb399282f1f6476d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sat, 25 Jan 2020 20:01:23 +0000 Subject: [PATCH 014/100] sync with monorepo gatsbyjs/gatsby@342444bd0aa34dc9433116d7f57c46949db97b37 - Fixed typo: Issue #20790 (#20873) Closes #20790" in the pull request description --- docs/docs/building-an-e-commerce-site.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/building-an-e-commerce-site.md b/docs/docs/building-an-e-commerce-site.md index 87ddc4f..6e48ffc 100644 --- a/docs/docs/building-an-e-commerce-site.md +++ b/docs/docs/building-an-e-commerce-site.md @@ -1,11 +1,11 @@ --- -title: Building an E-commerce Site +title: Building an e-commerce Site --- -The speed and performance of sites built with Gatsby make it a great tool for building E-commerce sites. There are existing plugins for connecting services like [Shopify](/packages/gatsby-source-shopify/) and [Snipcart](/packages/gatsby-plugin-snipcart/) to Gatsby, and this section contains reference guides to help get things setup. +The speed and performance of sites built with Gatsby make it a great tool for building e-commerce sites. There are existing plugins for connecting services like [Shopify](/packages/gatsby-source-shopify/) and [Snipcart](/packages/gatsby-plugin-snipcart/) to Gatsby, and this section contains reference guides to help get things setup. -To see examples of E-commerce sites built with Gatsby, check out the [showcase](/showcase/?filters%5B0%5D=eCommerce). +To see examples of e-commerce sites built with Gatsby, check out the [showcase](/showcase/?filters%5B0%5D=eCommerce). -_You can also check out the ["Making an E-commerce Site with Stripe" tutorial](/tutorial/ecommerce-tutorial/) for more information._ +_You can also check out the ["Making an e-commerce Site with Stripe" tutorial](/tutorial/ecommerce-tutorial/) for more information._ From 288884b3337b1fb58e99cd8d99bc50f1f28809fa Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sat, 25 Jan 2020 20:03:08 +0000 Subject: [PATCH 015/100] sync with monorepo gatsbyjs/gatsby@eb2348cfb585492c632ac5c91bdc86a47271a0ff - Fixed type: Issue #20790 (#20874) closes #20790 in the pull request description --- docs/tutorial/ecommerce-tutorial/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorial/ecommerce-tutorial/index.md b/docs/tutorial/ecommerce-tutorial/index.md index 8c89e76..8177169 100644 --- a/docs/tutorial/ecommerce-tutorial/index.md +++ b/docs/tutorial/ecommerce-tutorial/index.md @@ -1,5 +1,5 @@ --- -title: "Gatsby E-Commerce Tutorial" +title: "Gatsby e-commerce Tutorial" --- # Table of Contents @@ -65,7 +65,7 @@ Open the root site directory in a text editor and navigate to `gatsby-config.js` ```js:title=gatsby-config.js module.exports = { siteMetadata: { - title: "Gatsby E-Commerce Starter", + title: "Gatsby e-commerce Starter", }, plugins: ["gatsby-plugin-react-helmet", "gatsby-plugin-stripe"], } @@ -277,7 +277,7 @@ Now you can add the plugin configuration in your `gatsby-config` file: ```js:title=gatsby-config.js module.exports = { siteMetadata: { - title: `Gatsby E-Commerce Starter`, + title: `Gatsby e-commerce Starter`, }, plugins: [ `gatsby-plugin-react-helmet`, From d663c45fb88369cfc616c958fb9ac537613eda5d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sun, 26 Jan 2020 20:25:53 +0000 Subject: [PATCH 016/100] sync with monorepo gatsbyjs/gatsby@8561d104f81e7037761e247b7e7a53df01580745 - docs: Update build-caching.md to mention that build outputs are also in public (#20869) --- docs/docs/build-caching.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/build-caching.md b/docs/docs/build-caching.md index fc95f39..991f923 100644 --- a/docs/docs/build-caching.md +++ b/docs/docs/build-caching.md @@ -9,7 +9,7 @@ Caching is already used by Gatsby and plugins for example: - any nodes created by source/transformer plugins are cached - `gatsby-plugin-sharp` caches built thumbnails -Data is stored in the `.cache` directory relative to your project root. +Build outputs are stored in the `.cache` and `public` directories relative to your project root. ## The cache API From e31fff80a02d3f7670b2590d60fba4b52bd6b069 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 27 Jan 2020 09:14:46 +0000 Subject: [PATCH 017/100] sync with monorepo gatsbyjs/gatsby@ea65aea62fd9a74f107440911b9fe9e4302adf20 - docs: fix React terminology (#20896) --- docs/docs/sourcing-content-from-json-or-yaml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/sourcing-content-from-json-or-yaml.md b/docs/docs/sourcing-content-from-json-or-yaml.md index 470afe4..2dc01d3 100644 --- a/docs/docs/sourcing-content-from-json-or-yaml.md +++ b/docs/docs/sourcing-content-from-json-or-yaml.md @@ -65,7 +65,7 @@ const YAMLbuildtime = () => ( export default YAMLbuildtime ``` -The above code imports YAML source data as an array, iterates over it with the `Array.map` method, and renders the data-filled markup through a functional stateless React component. +The above code imports YAML source data as an array, iterates over it with the `Array.map` method, and renders the data-filled markup through a functional React component. ## Directly import data with JSON From 5a41510aa90cfbc3434edc4750a21353487d0343 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 27 Jan 2020 15:03:49 +0000 Subject: [PATCH 018/100] sync with monorepo gatsbyjs/gatsby@1417195c0e618cfbd832d9bd286ba1faa10e5bfe - docs(tutorial): fix typo (#20878) --- docs/tutorial/gatsby-image-tutorial/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/gatsby-image-tutorial/index.md b/docs/tutorial/gatsby-image-tutorial/index.md index f2b6846..812a480 100644 --- a/docs/tutorial/gatsby-image-tutorial/index.md +++ b/docs/tutorial/gatsby-image-tutorial/index.md @@ -99,7 +99,7 @@ You might expect the relative path to be relative to the file the code sits in, ### Image fragments -Another thing to note about this query is how it uses the fragment `GatsbyImageSharpFixed` to return a fixed width and height image. You could also use the fragment `GatsbyImageSharpFluid` which produces scalable images that fill their container instead of fitting specific dimensions. In `gatsby-image`, _fluid_ images are meant for images that don’t have a finite size depending on the screen, where as other images are _fixed_. +Another thing to note about this query is how it uses the fragment `GatsbyImageSharpFixed` to return a fixed width and height image. You could also use the fragment `GatsbyImageSharpFluid` which produces scalable images that fill their container instead of fitting specific dimensions. In `gatsby-image`, _fluid_ images are meant for images that don’t have a finite size depending on the screen, whereas other images are _fixed_. The query will return a data object including the processed image in a format usable by the `gatsby-image` component. The returned result will be automatically passed into the component and attached to the `data` prop. You can then display the image using JSX to automatically output responsive, highly performant HTML. From 471c8b90bc254608afefc2ef742ca636fe575a3d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 27 Jan 2020 15:45:10 +0000 Subject: [PATCH 019/100] sync with monorepo gatsbyjs/gatsby@c8a0240fbd53a43e030454f583a5165ab537aaf9 - Added source guide for Seams-CMS (#20240) * Added source guide for Seams-CMS * Ran prettier over markdown file * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/docs/sourcing-from-seams-cms.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Updated some wording and clarifications * Added some more details * Updated documentation according to the tutorial doc-styles * Fixed small typo * Added some more information about Seams-CMS * Fixed typo * Removed space * Applied suggestions from code review to fix up language Co-Authored-By: Aisha Blake * Removed empty line * Adjust heading levels * Remove comment Co-authored-by: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: Aisha Blake --- docs/docs/headless-cms.md | 1 + docs/docs/sourcing-from-seams-cms.md | 189 +++++++++++++++++++++++++++ 2 files changed, 190 insertions(+) create mode 100644 docs/docs/sourcing-from-seams-cms.md diff --git a/docs/docs/headless-cms.md b/docs/docs/headless-cms.md index b6c427a..3b9ddba 100644 --- a/docs/docs/headless-cms.md +++ b/docs/docs/headless-cms.md @@ -45,6 +45,7 @@ Here are more resources for guides, plugins, and starters for CMS systems you ca | [AgilityCMS](https://agilitycms.com/) | [guide](/docs/sourcing-from-agilitycms/) | [docs](/packages/@agility/gatsby-source-agilitycms/) | [starter](/starters/agility/agility-gatsby-starter/) | | [Forestry](https://forestry.io/) | [guide](/docs/sourcing-from-forestry/) | | | | [Gentics Mesh](https://getmesh.io) | [guide](/docs/sourcing-from-gentics-mesh) | | | +| [Seams-CMS](https://seams-cms.com/) | [guide](/docs/sourcing-from-seams-cms) | | | ## How to add new guides to this section diff --git a/docs/docs/sourcing-from-seams-cms.md b/docs/docs/sourcing-from-seams-cms.md new file mode 100644 index 0000000..f7d524c --- /dev/null +++ b/docs/docs/sourcing-from-seams-cms.md @@ -0,0 +1,189 @@ +--- +title: Sourcing from Seams-CMS +--- + +[Seams-CMS](https://seams-cms.com) is a [headless CMS](/docs/glossary/headless-cms/) system in which you can manage everything from blog posts to complex data structures like products and translations. After defining your data types, you can add content based on your specific structures. Seams-CMS allows you to localize your content and has an advanced security and workflow model. Your content can be retrieved through different JSON APIs and GraphQL endpoints, which allows you to use your content as you see fit. + +Seams-CMS makes it possible use your content in different scenarios: on your website, in your blogs, and in your apps while managing your content in a single location. + +Creating a Seams-CMS account is free for hobby or small sites. The code samples in this guide assume you're using the demo workspace that is automatically generated when you create a new account. Make sure you add an API key to this workspace in the API key settings. You will need your workspace ID and the (read-only) API key shortly. + +## Setup + +Create a new Gatsby site with the [default starter](https://github.com/gatsbyjs/gatsby-starter-default) and install the source plugin. + +Run this in your terminal: + +```shell +gatsby new seamscms-site +cd seamscms-site +npm install --save seams-cms-gatsby-source +``` + +### Configuring the source plugin + +Once you have installed the plugin, it's time to configure it. Add the following code to the `gatsby-config.js` file found in the root of your project. + +```javascript:title=gatsby-config.js +module.exports = { + ... + plugins: [ + ... + { + resolve: 'seams-cms-gatsby-source', + options: { + workspace: , + apiKey: , + contentTypes: ['blogpost'], + }, + } + ... + ], + ... +} +``` + +Change `` and `` into the ID of the workspace from your own Seams-CMS account and the newly generated API key inside that workspace. Within the `contentTypes` array, you can list all the IDs of the content types you'd like to import from Seams-CMS into your Gatsby site. For this tutorial, you'll only want to import the `blogpost` content. + +## Checking your connection + +Run `gatsby develop` to fetch your blog posts from Seams-CMS: + +```shell +gatsby develop +``` + +To check if it worked, you can check the GraphQL playground at `http://localhost:8000/___graphql` and look for an `allSeamsCmsBlogpost` section. If found, it means that your blog posts are correctly fetched and stored in the GraphQL layer of Gatsby, ready to be consumed. + +To see what kind of data it holds, try running the following query: + +```graphql +query MyQuery { + allSeamsCmsBlogpost { + edges { + node { + content { + title { + value + } + content { + value + } + author { + value { + content { + name { + value + } + } + } + } + categories { + value { + content { + name { + value + } + } + } + } + } + } + } + } +} +``` + +This will return the title, content, author name, and categories for each blog post. + +## Generating a blog post page + +You can create a simple site with just one page holding all blog posts. You can do this by creating a template blog index file at `src/templates/blog-index.js` with the following content: + +```javascript:title=src/templates/blog-index.js +import React from "react" + +import Layout from "../components/layout" + +const BlogIndex = ({ pageContext: { blogPosts } }) => ( + + {blogPosts.map(blogPost => ( + <> +

Title: {blogPost.node.content.title.value}

+

+ Author: {blogPost.node.content.author.value[0].content.name.value} +

+

{blogPost.node.content.content.value}

+
+ + ))} + +) + +export default BlogIndex +``` + +This template fetches your blog posts from the `pageContext` (passing your data along with this variable), and iterates over all the posts. For each post, it prints the title, the author's name, the content, and whatever you'd like to add that is present in the GraphQL data. For instance, you might also fetch things like tags, categories, snippets, image headers, etc. + +Once you have created your template, connect your data to it! Check out the `gatsby-node.js` file found in your root directory. Note that you will need a GraphQL query that you can generate automatically through the web interface. Select all the fields you want to use in your template and copy/paste this query into the new file: + +```javascript:title=gatsby-node.js +const blogQuery = ` + query MyQuery { + allSeamsCmsBlogpost { + edges { + node { + content { + title { + value + } + content { + value + } + author { + value { + content { + name { + value + } + } + } + } + categories { + value { + content { + name { + value + } + } + } + } + } + } + } + } + } +` +``` + +You're almost there! Next, create and export a `createPages` function in the same `gatsby-node.js` file that will create your page: + +```javascript:title=gatsby-node.js +exports.createPages = async ({ graphql, actions: { createPage } }) => { + const query = await graphql(blogQuery) + + createPage({ + path: `/blogs`, + component: require.resolve("./src/templates/blog-index.js"), + context: { + blogPosts: query.data.allSeamsCmsBlogpost.edges, + }, + }) +} +``` + +Finally, when you run `gatsby develop` again, it should generate a `/blogs` page with your content. You can visit this at `http://localhost:8000/blogs`. + +## Other resources + +For more detailed information about setting up Seams-CMS with Gatsby, see the [Seams-CMS blog](https://blog.seams-cms.com/entry/using-seams-cms-with-gatsbyjs/). From 2ac3637f2524e7982f5e234c3681dca4b2b168ad Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 27 Jan 2020 16:16:41 +0000 Subject: [PATCH 020/100] sync with monorepo gatsbyjs/gatsby@6618f02b7eb3378173c040989f769930be35d5cf - chore(docs): Use soft wraps for old docs (#20887) * fix-docs/docs/api-proxy * fix-docs/docs/api-specification * fix-docs/docs/babel-plugin-macros * fix-docs/docs/babel * fix-docs/docs/browser-support * fix-docs/docs/best-practices-for-orgs --- docs/docs/api-proxy.md | 17 ++--- docs/docs/api-specification.md | 107 ++++++++------------------- docs/docs/babel-plugin-macros.md | 29 ++------ docs/docs/babel.md | 20 ++--- docs/docs/best-practices-for-orgs.md | 3 +- docs/docs/browser-support.md | 30 ++------ 6 files changed, 55 insertions(+), 151 deletions(-) diff --git a/docs/docs/api-proxy.md b/docs/docs/api-proxy.md index 7d1517b..3c9fcfe 100644 --- a/docs/docs/api-proxy.md +++ b/docs/docs/api-proxy.md @@ -8,11 +8,9 @@ If you’re not familiar with Gatsby’s lifecycle, see the overview [Gatsby Lif ## Proxying API requests in development -People often serve the frontend React app from the same host and port as their -backend implementation. +People often serve the frontend React app from the same host and port as their backend implementation. -To tell the development server to proxy any unknown requests to your API server -in development, add a `proxy` field to your `gatsby-config.js`, for example: +To tell the development server to proxy any unknown requests to your API server in development, add a `proxy` field to your `gatsby-config.js`, for example: ```javascript:title=gatsby-config.js module.exports = { @@ -40,18 +38,13 @@ module.exports = { } ``` -This way, when you `fetch('/api/todos')` in development, the development server -will recognize that it’s not a static asset, and will proxy your request to -`http://dev-mysite.com/api/todos` as a fallback. +This way, when you `fetch('/api/todos')` in development, the development server will recognize that it’s not a static asset, and will proxy your request to `http://dev-mysite.com/api/todos` as a fallback. -Keep in mind that `proxy` only has effect in development (with `gatsby develop`), and it is up to you to ensure that URLs like `/api/todos` point to -the right place in production. +Keep in mind that `proxy` only has effect in development (with `gatsby develop`), and it is up to you to ensure that URLs like `/api/todos` point to the right place in production. ## Advanced proxying -Sometimes you need more granular/flexible access to the development server. -Gatsby exposes the [Express.js](https://expressjs.com/) development server to your site's `gatsby-config.js` where you -can add Express middleware as needed. +Sometimes you need more granular/flexible access to the development server. Gatsby exposes the [Express.js](https://expressjs.com/) development server to your site's `gatsby-config.js` where you can add Express middleware as needed. ```javascript:title=gatsby-config.js var proxy = require("http-proxy-middleware") diff --git a/docs/docs/api-specification.md b/docs/docs/api-specification.md index 8e560c3..e4bc392 100644 --- a/docs/docs/api-specification.md +++ b/docs/docs/api-specification.md @@ -2,12 +2,9 @@ title: API Specification --- -Gatsby's APIs are tailored conceptually to some extent after React.js to improve -the coherence between the two systems. +Gatsby's APIs are tailored conceptually to some extent after React.js to improve the coherence between the two systems. -The two top priorities of the API are a) enable a broad and robust plugin -ecosystem and b) on top of that a broad and robust theme ecosystem (themes are -on the back burner btw until after v1 comes out). +The two top priorities of the API are a) enable a broad and robust plugin ecosystem and b) on top of that a broad and robust theme ecosystem (themes are on the back burner btw until after v1 comes out). ## Prerequisites @@ -19,62 +16,34 @@ Plugins can extend Gatsby in many ways: - Sourcing data (e.g. from the filesystem or an API or a database) - Transforming data from one type to another (e.g. a markdown file to HTML) -- Creating pages (e.g. a directory of markdown files all gets turned into pages - with URLs derived from their file names). -- Modifying webpack config (e.g. for styling options, adding support for other - compile-to-js languages) -- Adding things to the rendered HTML (e.g. meta tags, analytics JS snippets like - Google Analytics) -- Writing out things to build directory based on site data (e.g. service worker, - sitemap, RSS feed) - -A single plugin can use multiple APIs to accomplish its purpose. E.g. the plugin -for the CSS-in-JS library [Glamor](/packages/gatsby-plugin-glamor/): +- Creating pages (e.g. a directory of markdown files all gets turned into pages with URLs derived from their file names). +- Modifying webpack config (e.g. for styling options, adding support for other compile-to-js languages) +- Adding things to the rendered HTML (e.g. meta tags, analytics JS snippets like Google Analytics) +- Writing out things to build directory based on site data (e.g. service worker, sitemap, RSS feed) + +A single plugin can use multiple APIs to accomplish its purpose. E.g. the plugin for the CSS-in-JS library [Glamor](/packages/gatsby-plugin-glamor/): 1. modifies the webpack config to add its plugin 2. adds a Babel plugin to replace React's default createElement -3. modifies server rendering to extract out the critical CSS for each rendered - page and inline the CSS in the `` of that HTML page. - -Plugins can also depend on other plugins. [The Sharp -plugin](/packages/gatsby-plugin-sharp/) exposes a number of high-level APIs for -transforming images that several other Gatsby image plugins depend on. -[gatsby-transformer-remark](/packages/gatsby-transformer-remark/) does basic -markdown->html transformation but exposes an API to allow other plugins to -intervene in the conversion process e.g. -[gatsby-remark-prismjs](/packages/gatsby-remark-prismjs/) which adds -highlighting to code blocks. - -Transformer plugins are decoupled from source plugins. Transformer plugins look -at the media type of new nodes created by source plugins to decide if they can -transform it or not. Which means that a markdown transformer plugin can -transform markdown from any source without any other configuration e.g. from a -file, a code comment, or external service like Trello which supports markdown -in some of its data fields. - -See -[the full list of (official only for now — adding support for community plugins later) plugins](/docs/plugins/). +3. modifies server rendering to extract out the critical CSS for each rendered page and inline the CSS in the `` of that HTML page. + +Plugins can also depend on other plugins. [The Sharp plugin](/packages/gatsby-plugin-sharp/) exposes a number of high-level APIs for transforming images that several other Gatsby image plugins depend on. [gatsby-transformer-remark](/packages/gatsby-transformer-remark/) does basic markdown->html transformation but exposes an API to allow other plugins to intervene in the conversion process e.g. [gatsby-remark-prismjs](/packages/gatsby-remark-prismjs/) which adds highlighting to code blocks. + +Transformer plugins are decoupled from source plugins. Transformer plugins look at the media type of new nodes created by source plugins to decide if they can transform it or not. Which means that a markdown transformer plugin can transform markdown from any source without any other configuration e.g. from a file, a code comment, or external service like Trello which supports markdown in some of its data fields. + +See [the full list of (official only for now — adding support for community plugins later) plugins](/docs/plugins/). ## API ### Concepts -- _Page_ — a site page with a pathname, a template component, and optional - GraphQL query. -- _Page Component_ — React.js component that renders a page and can optionally - specify a GraphQL query -- _Component extensions_ — extensions that are resolvable as components. `.js` - and `.jsx` are supported by core. But plugins can add support for other - compile-to-js languages. -- _Dependency_ — Gatsby automatically tracks dependencies between different - objects e.g. a page can depend on certain nodes. This allows for hot - reloading, caching, incremental rebuilds, etc. +- _Page_ — a site page with a pathname, a template component, and optional GraphQL query. +- _Page Component_ — React.js component that renders a page and can optionally specify a GraphQL query +- _Component extensions_ — extensions that are resolvable as components. `.js` and `.jsx` are supported by core. But plugins can add support for other compile-to-js languages. +- _Dependency_ — Gatsby automatically tracks dependencies between different objects e.g. a page can depend on certain nodes. This allows for hot reloading, caching, incremental rebuilds, etc. - _Node_ — a data object - _Node Field_ — a field added by a plugin to a node that it doesn't control -- _Node Link_ — a connection between nodes that gets converted to GraphQL - relationships. Can be created in a variety of ways as well as automatically - inferred. Parent/child links from nodes and their transformed derivative nodes - are first class links. +- _Node Link_ — a connection between nodes that gets converted to GraphQL relationships. Can be created in a variety of ways as well as automatically inferred. Parent/child links from nodes and their transformed derivative nodes are first class links. _More definitions and terms are defined in the [Glossary](/docs/glossary/)_ @@ -88,36 +57,18 @@ _More definitions and terms are defined in the [Glossary](/docs/glossary/)_ ### Extension APIs -Gatsby has multiple processes. The most prominent is the "bootstrap" process. It -has several subprocesses. One tricky part to their design is that they run both -once during the initial bootstrap but also stay alive during development to -continue to respond to changes. This is what drives hot reloading that all -Gatsby data is "alive" and reacts to changes in the environment. +Gatsby has multiple processes. The most prominent is the "bootstrap" process. It has several subprocesses. One tricky part to their design is that they run both once during the initial bootstrap but also stay alive during development to continue to respond to changes. This is what drives hot reloading that all Gatsby data is "alive" and reacts to changes in the environment. The bootstrap process is as follows: -load site config -> load plugins -> source nodes -> transform nodes -> create -graphql schema -> create pages -> compile component queries -> run queries -> -fin +load site config -> load plugins -> source nodes -> transform nodes -> create graphql schema -> create pages -> compile component queries -> run queries -> fin Once the initial bootstrap is finished, a `webpack-dev-server` and express server are started for serving files for the development workflow with live updates. For a production build, Gatsby skips the development server and instead builds the CSS, then JavaScript, then static HTML with webpack. -During these processes there are various extension points where plugins can -intervene. All major processes have an `onPre` and `onPost` e.g. `onPreBootstrap` -and `onPostBootstrap` or `onPreBuild` or `onPostBuild`. During bootstrap, -plugins can respond at various stages to APIs like `onCreatePages`, -`onCreateBabelConfig`, and `onSourceNodes`. - -At each extension point, Gatsby identifies the plugins which implement the API -and calls them in serial following their order in the site's `gatsby-config.js`. - -In addition to extension APIs in a node, plugins can also implement extension APIs -in the server rendering process and the browser e.g. `onClientEntry` or -`onRouteUpdate` - -The three main inspirations for this API and spec are React.js' API specifically -[@leebyron's email on the React API](https://gist.github.com/vjeux/f2b015d230cc1ab18ed1df30550495ed), -this talk -["How to Design a Good API and Why it Matters" by Joshua Bloch](https://www.youtube.com/watch?v=heh4OeB9A-c&app=desktop) -who designed many parts of Java, and [Hapi.js](https://hapijs.com/api)' plugin -design. +During these processes there are various extension points where plugins can intervene. All major processes have an `onPre` and `onPost` e.g. `onPreBootstrap` and `onPostBootstrap` or `onPreBuild` or `onPostBuild`. During bootstrap plugins can respond at various stages to APIs like `onCreatePages`, `onCreateBabelConfig`, and `onSourceNodes`. + +At each extension point, Gatsby identifies the plugins which implement the API and calls them in serial following their order in the site's `gatsby-config.js`. + +In addition to extension APIs in a node, plugins can also implement extension APIs in the server rendering process and the browser e.g. `onClientEntry` or `onRouteUpdate`. + +The three main inspirations for this API and spec are React.js' API specifically [@leebyron's email on the React API](https://gist.github.com/vjeux/f2b015d230cc1ab18ed1df30550495ed), this talk ["How to Design a Good API and Why it Matters" by Joshua Bloch](https://www.youtube.com/watch?v=heh4OeB9A-c&app=desktop) who designed many parts of Java, and [Hapi.js](https://hapijs.com/api)' plugin design. diff --git a/docs/docs/babel-plugin-macros.md b/docs/docs/babel-plugin-macros.md index 9b8f924..6b0f033 100644 --- a/docs/docs/babel-plugin-macros.md +++ b/docs/docs/babel-plugin-macros.md @@ -2,34 +2,24 @@ title: Using Babel Plugin Macros --- -Gatsby includes a powerful new way of applying compile-time code -transformations, -[Babel macros](https://github.com/kentcdodds/babel-plugin-macros)! Macros are -like Babel plugins, but instead of adding them to your `.babelrc`, you import them in -the file you want to use them. This has two big advantages: - -- No confusion about where a non-standard syntax is coming from. Macros are - explicitly imported wherever they are used. +Gatsby includes a powerful new way of applying compile-time code transformations, [Babel macros](https://github.com/kentcdodds/babel-plugin-macros)! Macros are like Babel plugins, but instead of adding them to your `.babelrc`, you import them in the file you want to use them. This has two big advantages: + +- No confusion about where a non-standard syntax is coming from. Macros are explicitly imported wherever they are used. - No configuration files. Macros are included directly in your code as needed. -Like Babel plugins, macros run only at compile time. They are not included in -the public JavaScript bundle. As such, macros have no effect on your code -beyond the transformations they apply. +Like Babel plugins, macros run only at compile time. They are not included in the public JavaScript bundle. As such, macros have no effect on your code beyond the transformations they apply. ## Installing macros -Just like plugins, many macros are published as npm packages. By convention, -they are named by their function, followed by `.macro`. +Just like plugins, many macros are published as npm packages. By convention, they are named by their function, followed by `.macro`. -For example, [`preval.macro`](https://www.npmjs.com/package/preval.macro) is a -macro that pre-evaluates JavaScript code. You can install it by running: +For example, [`preval.macro`](https://www.npmjs.com/package/preval.macro) is a macro that pre-evaluates JavaScript code. You can install it by running: ```shell npm install --save-dev preval.macro ``` -Some macros are instead included in larger packages. To install and use them, -refer to their documentation. +Some macros are instead included in larger packages. To install and use them, refer to their documentation. ## Using macros @@ -55,7 +45,4 @@ const x = 1 ## Discovering available macros -Take a look at the -[Awesome babel macros](https://github.com/jgierer12/awesome-babel-macros) -list to find available macros you can use. Additionally, this list contains -helpful resources for using macros and developing them yourself. +Take a look at the [Awesome babel macros](https://github.com/jgierer12/awesome-babel-macros) list to find available macros you can use. Additionally, this list contains helpful resources for using macros and developing them yourself. diff --git a/docs/docs/babel.md b/docs/docs/babel.md index 218507c..afc3036 100644 --- a/docs/docs/babel.md +++ b/docs/docs/babel.md @@ -2,29 +2,19 @@ title: Babel --- -Gatsby uses the phenomenal project [Babel](https://babeljs.io/) to enable -support for writing modern JavaScript — while still supporting older browsers. +Gatsby uses the phenomenal project [Babel](https://babeljs.io/) to enable support for writing modern JavaScript — while still supporting older browsers. ## How to specify which browsers to support -Gatsby supports by default the last two versions of major browsers, IE 9+, as well as -any browser that still has 1%+ browser share. +Gatsby supports by default the last two versions of major browsers, IE 9+, as well as any browser that still has 1%+ browser share. -This means that your JavaScript is automatically compiled to ensure it works on older browsers. -Polyfills are also automatically added — no more shipping code which mysteriously -breaks on older browsers! +This means that your JavaScript is automatically compiled to ensure it works on older browsers. Polyfills are also automatically added — no more shipping code which mysteriously breaks on older browsers! -If you only target newer browsers, see the [Browser -Support](/docs/browser-support/) docs page for how to instruct Gatsby on which -browsers you support and then Babel will start compiling for only these -browsers. +If you only target newer browsers, see the [Browser Support](/docs/browser-support/) docs page for how to instruct Gatsby on which browsers you support and then Babel will start compiling for only these browsers. ## How to use a custom .babelrc file -Gatsby ships with a default .babelrc setup that should work for most sites. If you'd like -to add custom Babel presets or plugins, you can create your own `.babelrc` at the root of -your site, import [`babel-preset-gatsby`](https://github.com/gatsbyjs/gatsby/tree/master/packages/babel-preset-gatsby), -and add additional plugins, presets, and pass options to `babel-preset-gatsby`, e.g. `targets`. +Gatsby ships with a default .babelrc setup that should work for most sites. If you'd like to add custom Babel presets or plugins, you can create your own `.babelrc` at the root of your site, import [`babel-preset-gatsby`](https://github.com/gatsbyjs/gatsby/tree/master/packages/babel-preset-gatsby), and add additional plugins, presets, and pass options to `babel-preset-gatsby`, e.g. `targets`. ```shell npm install --save-dev babel-preset-gatsby diff --git a/docs/docs/best-practices-for-orgs.md b/docs/docs/best-practices-for-orgs.md index 7e23900..16de825 100644 --- a/docs/docs/best-practices-for-orgs.md +++ b/docs/docs/best-practices-for-orgs.md @@ -11,5 +11,4 @@ When you have multiple teams building Gatsby sites, there are some best practice This is a stub. Help our community expand it. -Please use the [Gatsby Style Guide](/contributing/gatsby-style-guide/) to ensure your -pull request gets accepted. +Please use the [Gatsby Style Guide](/contributing/gatsby-style-guide/) to ensure your pull request gets accepted. diff --git a/docs/docs/browser-support.md b/docs/docs/browser-support.md index 018e5aa..eebaad9 100644 --- a/docs/docs/browser-support.md +++ b/docs/docs/browser-support.md @@ -2,36 +2,21 @@ title: Browser Support --- -Gatsby supports -[the same browsers as the current stable version of React.js](https://facebook.github.io/react/docs/react-dom.html#browser-support) -which is currently IE9+ as well as the most recent versions of other popular -browsers. +Gatsby supports [the same browsers as the current stable version of React.js](https://facebook.github.io/react/docs/react-dom.html#browser-support) which is currently IE9+ as well as the most recent versions of other popular browsers. ## Polyfills -Gatsby leverages Babel 7's ability to automatically add polyfills for your -target browsers. +Gatsby leverages Babel 7's ability to automatically add polyfills for your target browsers. -Newer browsers support more JavaScript APIs than older browsers. For older -versions, Gatsby (via Babel) automatically adds the minimum "polyfills" -necessary for your code to work in those browsers. +Newer browsers support more JavaScript APIs than older browsers. For older versions, Gatsby (via Babel) automatically adds the minimum "polyfills" necessary for your code to work in those browsers. -If you start using a newer JavaScript API like `[].includes` that isn't -supported by some of your targeted browsers, you won't have to worry about it -breaking the older browsers as Babel will automatically add the needed polyfill -`core-js/modules/es7.array.includes`. +If you start using a newer JavaScript API like `[].includes` that isn't supported by some of your targeted browsers, you won't have to worry about it breaking the older browsers as Babel will automatically add the needed polyfill `core-js/modules/es7.array.includes`. ## Specify what browsers your project supports using "Browserslist" -You may customize your list of supported browser versions by declaring a -[`"browserslist"`](https://github.com/ai/browserslist) key within your -`package.json`. Changing these values will modify your JavaScript (via -[`babel-preset-env`](https://github.com/babel/babel-preset-env#targetsbrowsers)) -and your CSS (via [`autoprefixer`](https://github.com/postcss/autoprefixer)) -output. +You may customize your list of supported browser versions by declaring a [`"browserslist"`](https://github.com/ai/browserslist) key within your `package.json`. Changing these values will modify your JavaScript (via[`babel-preset-env`](https://github.com/babel/babel-preset-env#targetsbrowsers)) and your CSS (via [`autoprefixer`](https://github.com/postcss/autoprefixer)) output. -This article is a good introduction to the growing community of tools around -Browserslist — https://css-tricks.com/browserlist-good-idea/ +This article is a good introduction to the growing community of tools around Browserslist — https://css-tricks.com/browserlist-good-idea/ By default, Gatsby emulates the following config: @@ -41,5 +26,4 @@ By default, Gatsby emulates the following config: } ``` -If you only support newer browsers, make sure to specify this in your -`package.json`. This will often enable you to ship smaller JavaScript files. +If you only support newer browsers, make sure to specify this in your `package.json`. This will often enable you to ship smaller JavaScript files. From 650d085273f7046ca7003c30c45c2cbe0fd86f36 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 27 Jan 2020 17:30:37 +0000 Subject: [PATCH 021/100] sync with monorepo gatsbyjs/gatsby@7c604e02afde37472342650c99122ab6ddf9e426 - fix docs:ecommerce tutorial (#20889) * fix gatsby-config.js * fix some words --- docs/tutorial/ecommerce-tutorial/index.md | 30 +++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/ecommerce-tutorial/index.md b/docs/tutorial/ecommerce-tutorial/index.md index 8177169..ef99f7a 100644 --- a/docs/tutorial/ecommerce-tutorial/index.md +++ b/docs/tutorial/ecommerce-tutorial/index.md @@ -65,9 +65,35 @@ Open the root site directory in a text editor and navigate to `gatsby-config.js` ```js:title=gatsby-config.js module.exports = { siteMetadata: { - title: "Gatsby e-commerce Starter", + title: `Gatsby e-Commerce Starter`, + description: `Kick off your next, great Gatsby project with this default starter. This barebones starter ships with the main Gatsby configuration files you might need.`, + author: `@gatsbyjs`, }, - plugins: ["gatsby-plugin-react-helmet", "gatsby-plugin-stripe"], + plugins: [ + `gatsby-plugin-react-helmet`, + { + resolve: `gatsby-source-filesystem`, + options: { + name: `images`, + path: `${__dirname}/src/images`, + }, + }, + `gatsby-transformer-sharp`, + `gatsby-plugin-sharp`, + { + resolve: `gatsby-plugin-manifest`, + options: { + name: `gatsby-starter-default`, + short_name: `starter`, + start_url: `/`, + background_color: `#663399`, + theme_color: `#663399`, + display: `minimal-ui`, + icon: `src/images/gatsby-icon.png`, // This path is relative to the root of the site. + }, + }, + `gatsby-plugin-stripe`, + ], } ``` From 52cf779068efeb5c7199c25e208ac30eaa0e8d04 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 28 Jan 2020 08:19:29 +0000 Subject: [PATCH 022/100] sync with monorepo gatsbyjs/gatsby@094ca4cfa5fc5f973e953eaae389122a2db7967b - fix(gatsby): Fix stack overflow on queries with circular fragments (#20936) * Add failing test * Fix stack overflow when analysing fragments * Eslint fixes --- docs/docs/sourcing-from-netlify-cms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/sourcing-from-netlify-cms.md b/docs/docs/sourcing-from-netlify-cms.md index c77ffd6..b194e66 100644 --- a/docs/docs/sourcing-from-netlify-cms.md +++ b/docs/docs/sourcing-from-netlify-cms.md @@ -63,7 +63,7 @@ backend: name: test-repo media_folder: static/assets -public_folder: assets +public_folder: /assets collections: - name: blog From 7a7d17dc7e9d710ec257854a62f4640cadb22c61 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 28 Jan 2020 21:47:13 +0000 Subject: [PATCH 023/100] sync with monorepo gatsbyjs/gatsby@8d204404df2cf82ed19d65ce99430c325fb987e4 - chore(recipe): Replaced yarn commands with npm (#20965) * chore(doc): Replaced yarn instructions with npm in Creating a new site using a theme doc * chore(doc): Replaced yarn instructions with npm in Creating a new site using a theme doc --- docs/docs/recipes/working-with-themes.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/docs/recipes/working-with-themes.md b/docs/docs/recipes/working-with-themes.md index 4fd2059..5550219 100644 --- a/docs/docs/recipes/working-with-themes.md +++ b/docs/docs/recipes/working-with-themes.md @@ -12,10 +12,7 @@ Found a theme you'd like to use on your project? Awesome! You can configure it f ### Prerequisites -Make sure you have the following installed: - -- [Gatsby CLI](/docs/gatsby-cli) -- [Yarn](https://yarnpkg.com/lang/en/docs/install/#mac-stable) +- Make sure you have the [Gatsby CLI](/docs/gatsby-cli) installed ### Directions @@ -60,7 +57,7 @@ module.exports = { } ``` -4. Run `yarn develop` , the theme should be available at `http://localhost:8000/{basePath}` +4. Run `gatsby develop` , the theme should be available at `http://localhost:8000/{basePath}` > To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](https://www.npmjs.com/package/gatsby-theme-blog). From e477aa47e2eda3244bfe75073dcbb452a2f5e60d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 29 Jan 2020 13:38:52 +0000 Subject: [PATCH 024/100] sync with monorepo gatsbyjs/gatsby@4ad2a241e4f5a24490838a397c70de5e41ee10ec - chore(docs): fix case of Homebrew (#20955) --- docs/docs/upgrading-node-js.md | 2 +- docs/tutorial/part-zero/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/upgrading-node-js.md b/docs/docs/upgrading-node-js.md index 99b606e..3b8e3e1 100644 --- a/docs/docs/upgrading-node-js.md +++ b/docs/docs/upgrading-node-js.md @@ -35,7 +35,7 @@ There are multiple ways to update your version of Node.js depending on how you o This is the recommended way to install a newer version of Node. -You will have homebrew installed on your computer if you [followed part zero of the Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-zero/#-install-nodejs-and-npm). Homebrew is a program that allows you to install specific versions of Node.js (and other software). +You will have Homebrew installed on your computer if you [followed part zero of the Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-zero/#-install-nodejs-and-npm). Homebrew is a program that allows you to install specific versions of Node.js (and other software). To update from Node.js 8 to Node.js 10 using Homebrew, open a terminal and run the following commands: diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md index 38ef37b..6ce7dfd 100644 --- a/docs/tutorial/part-zero/index.md +++ b/docs/tutorial/part-zero/index.md @@ -40,7 +40,7 @@ To install Gatsby and Node.js on a Mac, it is recommended to use [Homebrew](http 1. Open your Terminal 2. Run `brew install node` - - If you don't want to install it through homebrew, download the latest Node.js version from [the official Node.js website](https://nodejs.org/en/), double click on the downloaded file and go through the installation process. + - If you don't want to install it through Homebrew, download the latest Node.js version from [the official Node.js website](https://nodejs.org/en/), double click on the downloaded file and go through the installation process. ### Windows Instructions From 102617d7c86ba325b72d5b5168fef1df03a233cf Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 29 Jan 2020 15:30:32 +0000 Subject: [PATCH 025/100] sync with monorepo gatsbyjs/gatsby@f062e6e45a34110e30aa3bea775d063c25bb81aa - chore(docs): add KintoHub deployment guide (#20733) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore(docs): add KintoHub deployment guide * 🐛 fix prettier issues * 🚧 Fix PR comments * 🐛 fix typo per comment --- docs/docs/deploying-to-kintohub.md | 114 ++++++++++++++++++++++++++ docs/docs/preparing-for-deployment.md | 1 + 2 files changed, 115 insertions(+) create mode 100644 docs/docs/deploying-to-kintohub.md diff --git a/docs/docs/deploying-to-kintohub.md b/docs/docs/deploying-to-kintohub.md new file mode 100644 index 0000000..c2c9a18 --- /dev/null +++ b/docs/docs/deploying-to-kintohub.md @@ -0,0 +1,114 @@ +--- +title: Deploying to KintoHub +--- + +[KintoHub](https://www.kintohub.com) is a next-gen cloud package manager. Making it easy to host and manage websites, backend APIs, cron jobs, databases and more in a production grade fashion for all your apps. + +KintoHub has a free tier that you can use to deploy your static sites. Here are some features that come with it: + +- **CICD from GitHub** - You can build different branches and tag them to make sure the websites you deploy into staging and production environments are the same. +- Automatic **[Let's Encrypt](https://letsencrypt.org) certificates.** +- **Teams** - invite your collaborators on your workspace to work with you. +- Setup **custom domain names** with automatic Let's Encrypt certificates. +- Multiple **environments** (development, staging, production). +- **Password Protection**. + +## Prerequisites + +This guide assumes you already have a Gatsby project to deploy. If you need a project, you can use the [Quick Start](/docs/quick-start) or KintoHub's template [Gatsby Template](https://github.com/kintohub/gatsby-example) before continuing. + +## Setup + +In order to deploy a Gatsby site on KintoHub, you will need to create and deploy a **KintoBlock** into an **Environment** (development, staging, production). + +_Note: A **KintoBlock** is connected to a Github repository. Accessing the kintoblock page will allow you to build, manage or tags any branches of your repository._ + +### Create a KintoBlock + +1. Register on [KintoHub](https://beta.kintohub.com). +2. Create a new **KintoBlock** of type **Website** and give KintoHub permission to access your GitHub repo. +3. Select your Github repo from the list and press **Continue**. +4. Choose **Static from Build** with the following values: + + | | | + | ----------------------- | ---------------------------------------------------------- | + | **Name** | `Gatsby Website` (or your own name) | + | **Language** | `Node.js` | + | **Version** | `latest` (or your own node.js version) | + | **Build Command** | `npm install && npm run build` (or your own build command) | + | **Build Output Folder** | `public` (or your own output directory) | + +5. Press **Create Website**. + +The build will automatically start on the default Github branch of your repository. +Wait for your build to be successful (green). + +#### Multiple Branches + +When you create a new **KintoBlock**, KintoHub imports all your branches and you can access them from your kintoblock page (new branches will also be automatically picked up). +You can switch from one branch to another by pressing the branch name on the side panel on the left. + +#### Continuous Integration + +By default, KintoHub will build all the changes you push on your default branch. +If you want to disable it: + +1. Disable the toggle **Build New Commits**. +2. Press **Save Changes**. + +Your new changes will not be automatically picked up anymore and you will have to press **Build Latest Commit** to trigger a build. + +### Deploy your KintoBlock + +From your KintoBlock page, you will need to deploy your website first before accessing it. + +1. Press **Deploy Now** and then **New Project**. +2. You can change the default values (optional). +3. Press **Create New Project**. + +The deployment will start. +Wait for it to be successful (green). + +_Note: you can disable Continuous Deployments for future builds._ + +### Access your KintoBlock + +From your Project page. + +1. Scroll down to the **Added KintoBlocks** list. +2. Press **Open** on your kintoblock (`Gatsby Website`). + +And that's it! + +## Deployment Configuration + +You can configure additional features directly from your Project page. +If you're not already there, select **Projects** on the left-hand navigation bar, and then click on the project you want to configure. + +### Basic Auth + +1. Scroll down to the **Added KintoBlocks** list. +2. Click on the cog next to your kintoblock (`Gatsby Website`). +3. Enable **Password Protected**. +4. Enter **Username** and **Password**. +5. Press **Done Configuring** and then **Deploy**. +6. You'll see a **Compare Versions** screen. Click **Confirm Deployment**. + +Wait for the deployment to be successful. +Refresh the page, your website is now protected. + +### Custom domain + +1. Scroll down to the **Added KintoBlocks** list. +2. Click on the cog next to your kintoblock (`Gatsby Website`). +3. Under **Custom Domain**, enter your custom domain name. +4. Follow the instructions under _Setup_. +5. Press **Done Configuring** and then **Deploy**. +6. You'll see a **Compare Versions** screen. Click **Confirm Deployment**. + +Wait for the deployment to be successful. +Access your new custom domain. + +## Support + +Chat with KintoHub developers on [Discord](https://discordapp.com/invite/QVgqWuw) or email `ben@kintohub.com`. diff --git a/docs/docs/preparing-for-deployment.md b/docs/docs/preparing-for-deployment.md index 47814bf..0bcf234 100644 --- a/docs/docs/preparing-for-deployment.md +++ b/docs/docs/preparing-for-deployment.md @@ -53,5 +53,6 @@ If you have a server from one of the following providers, you should read the in - [Surge](/docs/deploying-to-surge) - [GitHub Pages](/docs/how-gatsby-works-with-github-pages) - [Microsoft Internet Information Server (IIS)](/docs/deploying-to-iis) +- [KintoHub](/docs/deploying-to-kintohub) If you don't see the hosting you are interested, it's possible to add other hosting providers through [contributions to the docs](/contributing/docs-contributions). From ae2f3d456c8f1e6f6f161c03b5a63e063bfebb64 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 29 Jan 2020 23:06:54 +0000 Subject: [PATCH 026/100] sync with monorepo gatsbyjs/gatsby@8bce690c1f69f56391a8009515e41c20af6254df - Make all docs use `.md` instead of `.mdx` for consistency (#20768) * Rename index.mdx to index.md * standardize the remaining docs * Update how-shadowing-works.md * Update how-shadowing-works.md * reformat so prettier doesnt complain --- docs/contributing/{index.mdx => index.md} | 0 .../docs/{how-shadowing-works.mdx => how-shadowing-works.md} | 5 +---- 2 files changed, 1 insertion(+), 4 deletions(-) rename docs/contributing/{index.mdx => index.md} (100%) rename docs/docs/{how-shadowing-works.mdx => how-shadowing-works.md} (99%) diff --git a/docs/contributing/index.mdx b/docs/contributing/index.md similarity index 100% rename from docs/contributing/index.mdx rename to docs/contributing/index.md diff --git a/docs/docs/how-shadowing-works.mdx b/docs/docs/how-shadowing-works.md similarity index 99% rename from docs/docs/how-shadowing-works.mdx rename to docs/docs/how-shadowing-works.md index c255837..b429508 100644 --- a/docs/docs/how-shadowing-works.mdx +++ b/docs/docs/how-shadowing-works.md @@ -16,10 +16,7 @@ It's important to begin discussing how the composition of themes works. An end u ```js:title=gatsby-config.js module.exports = { - plugins: [ - "gatsby-theme-tomato-blog", - "gatsby-theme-tomato-portfolio", - ], + plugins: ["gatsby-theme-tomato-blog", "gatsby-theme-tomato-portfolio"], } ``` From 806f02d0c376e752118939b132f35815915363a8 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 07:38:31 +0000 Subject: [PATCH 027/100] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@91bb25a15cd684d910bbf2575aae9f2a6fa3c02a=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=94=92=20Fix=20missing=20HTTPS=20on=20links=20(#21029)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contributing/managing-pull-requests.md | 4 ++-- docs/tutorial/blog-netlify-cms-tutorial/index.md | 2 +- docs/tutorial/part-eight/index.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/contributing/managing-pull-requests.md b/docs/contributing/managing-pull-requests.md index 40bcf89..7fdec9f 100644 --- a/docs/contributing/managing-pull-requests.md +++ b/docs/contributing/managing-pull-requests.md @@ -158,13 +158,13 @@ Alternatively, you can manage forks and branches with [hub](https://github.com/g ### Who can review a PR? -If you're a member of the [gatsbyjs](http://github.com/gatsbyjs) organization on GitHub, you can review **most** PRs. PRs with [`topic: internal`](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aopen+is%3Aissue+label%3A%22topic%3A+internal%22) are reserved for Core and Learning team members as they are typically part of an internal project or hiring process. +If you're a member of the [gatsbyjs](https://github.com/gatsbyjs) organization on GitHub, you can review **most** PRs. PRs with [`topic: internal`](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aopen+is%3Aissue+label%3A%22topic%3A+internal%22) are reserved for Core and Learning team members as they are typically part of an internal project or hiring process. > 💡 Not a member yet? Want to [get involved in contributing](/contributing/how-to-contribute/) to open source projects? Make your first contribution and you'll be invited automatically! ### Who can approve a PR? -Every PR opened in the repository needs to be approved before it can be merged. While anyone who is a member of the [gatsbyjs](http://github.com/gatsbyjs) organization can approve a PR, to be merged in, it needs to be reviewed by a member of the team that owns that part of Gatsby. +Every PR opened in the repository needs to be approved before it can be merged. While anyone who is a member of the [gatsbyjs](https://github.com/gatsbyjs) organization can approve a PR, to be merged in, it needs to be reviewed by a member of the team that owns that part of Gatsby. Typically this is: diff --git a/docs/tutorial/blog-netlify-cms-tutorial/index.md b/docs/tutorial/blog-netlify-cms-tutorial/index.md index 259d173..63c20fe 100644 --- a/docs/tutorial/blog-netlify-cms-tutorial/index.md +++ b/docs/tutorial/blog-netlify-cms-tutorial/index.md @@ -54,7 +54,7 @@ You'll likely also want to edit the `README.md` and `package.json` files to incl ### Step 4 -Open [github.com](http://github.com) and create a new repository, with the same name as your project. Push your new Gatsby site's code to GitHub using the following Terminal commands: +Open [github.com](https://github.com) and create a new repository, with the same name as your project. Push your new Gatsby site's code to GitHub using the following Terminal commands: ```shell git init diff --git a/docs/tutorial/part-eight/index.md b/docs/tutorial/part-eight/index.md index 33b8977..cd4583c 100644 --- a/docs/tutorial/part-eight/index.md +++ b/docs/tutorial/part-eight/index.md @@ -355,8 +355,8 @@ Lighthouse is a great tool for site improvements and learning -- Continue lookin ### Official Starters -1. [Gatsby's Default Starter](https://github.com/gatsbyjs/gatsby-starter-default): Kick off your project with this default boilerplate. This barebones starter ships with the main Gatsby configuration files you might need. _[working example](http://gatsbyjs.github.io/gatsby-starter-default/)_ -2. [Gatsby's Blog Starter](https://github.com/gatsbyjs/gatsby-starter-blog): Gatsby starter for creating an awesome and blazing-fast blog. _[working example](http://gatsbyjs.github.io/gatsby-starter-blog/)_ +1. [Gatsby's Default Starter](https://github.com/gatsbyjs/gatsby-starter-default): Kick off your project with this default boilerplate. This barebones starter ships with the main Gatsby configuration files you might need. _[working example](https://gatsbyjs.github.io/gatsby-starter-default/)_ +2. [Gatsby's Blog Starter](https://github.com/gatsbyjs/gatsby-starter-blog): Gatsby starter for creating an awesome and blazing-fast blog. _[working example](https://gatsbyjs.github.io/gatsby-starter-blog/)_ 3. [Gatsby's Hello-World Starter](https://github.com/gatsbyjs/gatsby-starter-hello-world): Gatsby Starter with the bare essentials needed for a Gatsby site. _[working example](https://gatsby-starter-hello-world-demo.netlify.com/)_ ## That's all, folks From b45c769924fcfd0333f09d8731b09c6875ee58ce Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 08:09:08 +0000 Subject: [PATCH 028/100] sync with monorepo gatsbyjs/gatsby@ef59c5d56a7b2561ce66a51e7094711ea66cf19a - fix(docs): Fix link to graphql docs (#21008) --- docs/docs/using-gatsby-without-graphql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/using-gatsby-without-graphql.md b/docs/docs/using-gatsby-without-graphql.md index 97235b7..82b9849 100644 --- a/docs/docs/using-gatsby-without-graphql.md +++ b/docs/docs/using-gatsby-without-graphql.md @@ -85,7 +85,7 @@ Using Gatsby's data layer provides the following benefits: - Improves performance by removing data bloat — GraphQL is a big part of why Gatsby is so fast as it enables lazy-loading the exact data in the exact form each view needs - Enables you to take advantage of hot reloading when developing; For example, in this post's example "Pokémon" site, if you wanted to add a "see other pokémon" section to the pokémon detail view, you would need to change your `gatsby-node.js` to pass all pokémon to the page, and restart the dev server. In contrast, when using queries, you can add a query and it will hot reload. -> Learn more about [GraphQL in Gatsby](/docs/querying-with-graphql/). +> Learn more about [GraphQL in Gatsby](/docs/graphql/). Working outside of the data layer also means foregoing the optimizations provided by transformer plugins, like: From 5b8fce8cdbd854aaeafc1b6977148d92235b331d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 12:56:48 +0000 Subject: [PATCH 029/100] sync with monorepo gatsbyjs/gatsby@98cf04200829e8157dd910ffe3fcbd8f1fc47452 - docs: Update bootstrap sequence (#19775) * update Bootstrap sequence docs * update Bootstrap sequence docs * udpate docs for gatsby lifecycle apis --- docs/docs/gatsby-lifecycle-apis.md | 48 ++++++++++++++---------------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/docs/docs/gatsby-lifecycle-apis.md b/docs/docs/gatsby-lifecycle-apis.md index 64d7780..2f95ae5 100644 --- a/docs/docs/gatsby-lifecycle-apis.md +++ b/docs/docs/gatsby-lifecycle-apis.md @@ -21,37 +21,33 @@ The following model gives a conceptual overview of how data is sourced and trans ## Bootstrap sequence -During "bootstrap" Gatsby: - -- reads `gatsby-config.js` to load in your list of plugins -- initializes its cache (stored in `/.cache`) -- pulls in and preprocesses data ("source and transform nodes") into a GraphQL schema -- creates pages in memory - - from your `/pages` folder - - from your `gatsby-node.js` if you implement `createPages`/`createPagesStatefully` (e.g. templates) - - from any plugins that implement `createPages`/`createPagesStatefully` -- extracts, runs, and replaces graphql queries for pages and `StaticQuery`s -- writes out the pages to cache +During the main bootstrap sequence, Gatsby (in this order): + +- reads and validates `gatsby-config.js` to load in your list of plugins (it doesn't run them yet). +- deletes HTML and CSS files from previous builds (public folder) +- initializes its cache (stored in `/.cache`) and checks if any plugins have been updated since the last run, if so it deletes the cache +- sets up `gatsby-browser` and `gatsby-ssr` for plugins that have them +- starts main bootstrap process + - runs [onPreBootstrap](/docs/node-apis/#onPreBootstrap). e.g. implemented by [`gatsby-plugin-typography`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-typography/src/gatsby-node.js) +- runs [sourceNodes](/docs/node-apis/#sourceNodes) e.g. implemented by [`gatsby-source-wikipedia`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wikipedia/src/gatsby-node.js) + - within this, `createNode` can be called multiple times, which then triggers [onCreateNode](/docs/node-apis/#onCreateNode) +- creates initial GraphQL schema +- runs [resolvableExtensions](/docs/node-apis/#resolvableExtensions) which lets plugins register file types or extensions e.g. [`gatsby-plugin-typescript`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-typescript/src/gatsby-node.js) +- runs [createPages](/docs/node-apis/#createPages) from the gatsby-node.js in the root directory of the project e.g. implemented by [`page-hot-reloader`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/page-hot-reloader.js) + - within this, `createPage` can be called any number of times, which then triggers [onCreatePage](/docs/node-apis/#onCreatePage) +- runs [createPagesStatefully](/docs/node-apis/#createPagesStatefully) +- runs source nodes again and updates the GraphQL schema to include pages this time +- runs [onPreExtractQueries](/docs/node-apis/#onPreExtractQueries) e.g. implemented by [`gatsby-transformer-sharp`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-sharp/src/gatsby-node.js) and [`gatsby-source-contentful`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-contentful/src/gatsby-node.js), and extracts queries from pages and components (`StaticQuery`) +- compiles GraphQL queries and creates the Abstract Syntax Tree (AST) +- runs query validation based on schema +- executes queries and stores their respective results +- writes page redirects (if any) to `.cache/redirects.json` +- the [onPostBootstrap](/docs/node-apis/#onPostBootstrap) lifecycle is executed In development this is a running process powered by [Webpack](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L128) and [`react-hot-loader`](https://github.com/gatsbyjs/gatsby/blob/dd91b8dceb3b8a20820b15acae36529799217ae4/packages/gatsby/package.json#L104), so changes to any files get re-run through the sequence again, with [smart cache invalidation](https://github.com/gatsbyjs/gatsby/blob/ffd8b2d691c995c760fe380769852bcdb26a2278/packages/gatsby/src/bootstrap/index.js#L141). For example, `gatsby-source-filesystem` watches files for changes, and each change triggers re-running queries. Other plugins may also perform this service. Queries are also watched, so if you modify a query, your development app is hot reloaded. The core of the bootstrap process is the "api-runner", which helps to execute APIs in sequence, with state managed in Redux. Gatsby exposes a number of lifecycle APIs which can either be implemented by you (or any of your configured plugins) in `gatsby-node.js`, `gatsby-browser.js` or `gatsby-ssr.js`. -The sequence of the **main** bootstrap Node API lifecycles are: - -- [onPreBootstrap](/docs/node-apis/#onPreBootstrap) e.g. implemented by [`gatsby-plugin-typography`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-typography/src/gatsby-node.js) -- [sourceNodes](/docs/node-apis/#sourceNodes) e.g. implemented by [`gatsby-source-wikipedia`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wikipedia/src/gatsby-node.js) - - within this `createNode` can be called multiple times, which then triggers [onCreateNode](/docs/node-apis/#onCreateNode). -- (the first schema build happens here) -- [resolvableExtensions](/docs/node-apis/#resolvableExtensions) for filetype/language extensions e.g. [`gatsby-plugin-typescript`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-typescript/src/gatsby-node.js) -- [createPages](/docs/node-apis/#createPages) e.g. implemented by [`page-hot-reloader`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/page-hot-reloader.js) - - within this `createPage` can be called any number of times, which then triggers [onCreatePage](/docs/node-apis/#onCreatePage) -- [onPreExtractQueries](/docs/node-apis/#onPreExtractQueries) e.g. implemented by [`gatsby-transformer-sharp`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-transformer-sharp/src/gatsby-node.js) and [`gatsby-source-contentful`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-contentful/src/gatsby-node.js) -- (schema update happens here) -- **extract queries from components** where the [queryCompiler](https://github.com/gatsbyjs/gatsby/blob/6de0e4408e14e599d4ec73948eb4153dc3cde849/packages/gatsby/src/internal-plugins/query-runner/query-compiler.js#L189) replaces page GraphQL queries and `StaticQueries` -- The [queries are run](https://github.com/gatsbyjs/gatsby/blob/6de0e4408e14e599d4ec73948eb4153dc3cde849/packages/gatsby/src/internal-plugins/query-runner/page-query-runner.js#L120), and [the pages are written out](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/query/redirects-writer.js) -- [onPostBootstrap](/docs/node-apis/#onPostBootstrap) is called (but it is not often used) - ## Build sequence (to be written) From cd2f0ce3e65b108e3763c27b312faf564fc4b944 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 13:26:03 +0000 Subject: [PATCH 030/100] sync with monorepo gatsbyjs/gatsby@ae6d47471b8e39ecb7e1a2a6d5644c052a8101af - docs: codesandbox graphql embeds (#21000) * add lazy loading and remove explorer from some embeds * add note about contributing graphql examples * Apply suggestions from code review Co-Authored-By: LB * Update docs/contributing/docs-contributions.md Co-Authored-By: LB * Update docs/contributing/docs-contributions.md Co-authored-by: LB Co-authored-by: GatsbyJS Bot --- docs/contributing/docs-contributions.md | 16 +++++++++ docs/docs/graphql-reference.md | 44 ++++++++++++------------- 2 files changed, 38 insertions(+), 22 deletions(-) diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md index d3e48c8..f7cd45e 100644 --- a/docs/contributing/docs-contributions.md +++ b/docs/contributing/docs-contributions.md @@ -103,6 +103,22 @@ It can be necessary to change a heading within the docs. It's important to note - Determine the URL you're looking for. `Changing headers` is linked with a URL ending in `changing-headers`, `Docs renaming instructions` becomes `docs-renaming-instructions`, etc. - Update all instances of the old URL to your new one. [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) in VS Code can help. Check that the context of the original link reference still makes sense with the new one. +## Adding embedded GraphQL examples + +There are embedded examples in a few places in the docs (like the [GraphQL Reference guide](/docs/graphql-reference/)) that provide a working version of the code described. In the specific example of the GraphQL Query Options Reference page, these examples of the GraphiQL interface show how data can be queried from Gatsby's data layer. + +To write a new GraphQL example, a Codesandbox project with a Gatsby site can be opened at its server container link, for example: [https://711808k40x.sse.codesandbox.io/](https://711808k40x.sse.codesandbox.io/). Because Codesandbox is running a Gatsby site in [`develop` mode instead of `build` mode](/docs/overview-of-the-gatsby-build-process/) you can navigate to GraphiQL by adding `/___graphql` to the link. Write an example query, and when you have a query you are satisfied with, the query fields and names will be saved as URL parameters so you can share the link. Copy the URL and use it as the `src` of an iframe: + +```mdx +Here's an example of a GraphQL query inline: + + + Try editing the query to include the `description` from `siteMetadata`. When typing in the query editor you can use `Ctrl + Space` to see autocomplete options and `Ctrl + Enter` to run the current query. @@ -22,7 +22,7 @@ Try editing the query to include the `description` from `siteMetadata`. When typ Gatsby structures its content as collections of `nodes`, which are connected to each other with `edges`. In this query you ask for the total count of plugins in this Gatsby site, along with specific information about each one. - + Try using the editor's autocomplete (`Ctrl + Space`) to get extended details from the `packageJson` nodes. @@ -30,19 +30,19 @@ Try using the editor's autocomplete (`Ctrl + Space`) to get extended details fro There are several ways to reduce the number of results from a query. Here `totalCount` tells you there's 8 results, but `limit` is used to show only the first three. - + ## Skip Skip over a number of results. In this query `skip` is used to omit the first 3 results. - + ## Filter In this query `filter` and the `ne` (not equals) operator is used to show only results that have a title. You can find a good video tutorial on this [here](https://www.youtube.com/watch?v=Lg1bom99uGM). - + Gatsby relies on [Sift](https://www.npmjs.com/package/sift) to enable MongoDB-like query syntax for object filtering. This allows Gatsby to support operators like `eq`, `ne`, `in`, `regex` and querying nested fields through the `__` connector. @@ -54,11 +54,11 @@ filter: { contentType: { in: ["post", "page"] }, draft: { eq: false } } In this query the fields `categories` and `title` are filtered to find the book that has `Fantastic` in its title and belongs to the `magical creatures` category. - + You can also combine the mentioned operators. This query filters on `/History/` for the `regex` operator. The result is `Hogwarts: A History` and `History of Magic`. You can filter out the latter with the `ne` operator. - + ### Complete list of possible operators @@ -76,7 +76,7 @@ _In the playground below the list, there is an example query with a description - `lte`: short for **less than or equal**, must be less than or equal to given value - `elemMatch`: short for **element match**, this indicates that the field you are filtering will return an array of elements, on which you can apply a filter using the previous operators - + If you want to understand more how these filters work, looking at the corresponding [tests](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/schema/__tests__/run-query.js) in the codebase could be very useful. @@ -84,17 +84,17 @@ If you want to understand more how these filters work, looking at the correspond The ordering of your results can be specified with `sort`. Here the results are sorted in ascending order of `frontmatter`'s `date` field. - + You can also sort on multiple fields but the `sort` keyword can only be used once. The second sort field gets evaluated when the first field (here: `date`) is identical. The results of the following query are sorted in ascending order of `date` and `title` field. - + `Children's Anthology of Monsters` and `Break with Banshee` both have the same date (`1992-01-02`) but in the first query (only one sort field) the latter comes after the first. The additional sorting on the `title` puts `Break with Banshee` in the right order. By default, sort `fields` will be sorted in ascending order. Optionally, you can specify a sort `order` per field by providing an array of `ASC` (for ascending) or `DESC` (for descending) values. For example, to sort by `frontmatter.date` in ascending order, and additionally by `frontmatter.title` in descending order, you would use `sort: { fields: [frontmatter___date, frontmatter___title], order: [ASC, DESC] }`. Note that if you only provide a single sort `order` value, this will affect the first sort field only, the rest will be sorted in default ascending order. - + ## Format @@ -102,31 +102,31 @@ By default, sort `fields` will be sorted in ascending order. Optionally, you can Dates can be formatted using the `formatString` function. - + Gatsby relies on [Moment.js](https://momentjs.com/) to format the dates. This allows you to use any tokens in your string. See [moment.js documentation](https://momentjs.com/docs/#/displaying/format/) for more tokens. You can also pass in a `locale` to adapt the output to your language. The above query gives you the english output for the weekdays, this example outputs them in german. - + Example: [`anotherDate(formatString: "dddd, MMMM Do YYYY, h:mm:ss a") # Sunday, August 5th 2018, 10:56:14 am`]() Dates also accept the `fromNow` and `difference` function. The former returns a string generated with Moment.js' [`fromNow`](https://momentjs.com/docs/#/displaying/fromnow/) function, the latter returns the difference between the date and current time (using Moment.js' [`difference`](https://momentjs.com/docs/#/displaying/difference/) function). - + ### Excerpt Excerpts accept three options: `pruneLength`, `truncate`, and `format`. `format` can be `PLAIN` or `HTML`. - + ## Sort, filter, limit & format together This query combines sorting, filtering, limiting and formatting together. - + ## Query variables @@ -136,7 +136,7 @@ The query below is the same one as the previous example, but with the input argu To add variables to page component queries, pass these in the `context` object [when creating pages](/docs/creating-and-modifying-pages/#creating-pages-in-gatsby-nodejs). - + ## Group @@ -144,7 +144,7 @@ You can also group values on the basis of a field e.g. the title, date or catego The query below gets you all categories (`fieldValue`) applied to a book and how many books (`totalCount`) a given category is applied to. In addition you are grabbing the `title` of books in a given category. You can see for example that there are 3 books in the `magical creatures` category. - + ## Fragments @@ -152,13 +152,13 @@ Fragments are a way to save frequently used queries for re-use. To create a frag The query below defines a fragment to get the site title, and then uses the fragment to access this information. - + ## Aliasing Want to run two queries on the same datasource? You can do this by aliasing your queries. See the query below for an example: - + When you use your data, you will be able to reference it using the alias instead of the root query name. In this example, that would be `data.someEntries` or `data.someMoreEntries` instead of `data.allMarkdownRemark`. @@ -168,13 +168,13 @@ GraphQL allows you to skip a piece of a query depending on variables. This is ha Try changing variable `withDate` in the example query below: - + Use directive `@include(if: $variable)` to conditionally include a part of a query or `@skip(if: $variable)` to exclude it. You can use those directives on any level of the query and even on fragments. Take a look at an advanced example: - + ## Where next? From e3afa263340ae1dc9792fe91afe4448ec30737d0 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 13:26:30 +0000 Subject: [PATCH 031/100] sync with monorepo gatsbyjs/gatsby@adfb8671d49d7be144813b22579a40f75e0acff8 - docs: plugin authoring workflow overview pages (#20847) * additional examples to loading/creating, and plugin authoring overview pages * correct minor errors and add tweaks to titles * Apply suggestions from code review Co-Authored-By: LB * added example repo * Update docs/docs/creating-a-local-plugin.md * simplify the site readme * update readme for clearer instructions and explanations * Apply suggestions from code review Co-Authored-By: LB Co-authored-by: LB Co-authored-by: GatsbyJS Bot --- docs/docs/creating-a-local-plugin.md | 58 +++++++++++++++--- ...-plugins-from-your-local-plugins-folder.md | 60 +++++++++++++++---- docs/docs/naming-a-plugin.md | 7 ++- docs/docs/plugins.md | 4 +- 4 files changed, 106 insertions(+), 23 deletions(-) diff --git a/docs/docs/creating-a-local-plugin.md b/docs/docs/creating-a-local-plugin.md index 87266e7..1b2adff 100644 --- a/docs/docs/creating-a-local-plugin.md +++ b/docs/docs/creating-a-local-plugin.md @@ -4,24 +4,68 @@ 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. +## Project structure for a local plugin + Place the code in the `plugins` folder in the root of your project like this: -```text -plugins -└── my-own-plugin - └── package.json +``` +/my-gatsby-site +└── gatsby-config.js +└── /src +└── /plugins + └── /my-own-plugin + └── package.json +``` + +The plugin also needs to be added to your `gatsby-config.js`, because there is no auto-detection of plugins. It can be added alongside any other 3rd party Gatsby plugins already included in your config. + +For the plugin to be discovered when you run `gatsby develop`, the plugin's root folder name needs to match the name used in the `gatsby-config.js` (_not_ the _name_ it goes by in your `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: [ + `gatsby-third-party-plugin`, + `my-own-plugin`, // highlight-line + ], +} ``` -**NOTE:** You still need to add the plugin to your `gatsby-config.js`. There is no auto-detection of local plugins. +Then the plugin can begin to hook into Gatsby through [Node](/docs/node-apis/) and [SSR](/docs/ssr-apis/) APIs. -**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: +## Developing a local plugin that is outside your project + +Your plugin doesn't have to be in your project in order to be tested or worked on. If you'd like to [decouple](/docs/glossary#decoupled) your plugin from your site you can follow one of the methods described below. This is a useful thing to do if you want to publish the plugin as its own package, or test/develop a forked version of a community authored plugin. + +### Using `require.resolve` and a filepath + +Including a `plugins` folder is not the only way to reference a local plugin. Alternatively, you can include a plugin in your `gatsby-config.js` file by directly referencing its path (relative to the `gatsby-config.js` file) with `require`. ```javascript:title=gatsby-config.js module.exports = { - plugins: ["my-own-plugin"], + plugins: [ + `gatsby-plugin-react-helmet`, + // highlight-start + { + // including a plugin from outside the plugins folder needs the path to it + resolve: require.resolve(`../path/to/gatsby-local-plugin`), + }, + // highlight-end + ], } ``` +### Using `npm link` or `yarn link` + +You can use [`npm link`](https://docs.npmjs.com/cli/link.html) or [`yarn link`](https://yarnpkg.com/lang/en/docs/cli/link/) to reference a package from another location on your machine. + +By running `npm link ../path/to/my-plugin` in the root of your Gatsby site, your computer will create a symlink to your package. + +This is a similar process to setting up yarn workspaces for development with Gatsby themes (which is the recommended approach for developing themes). You can read how to setup a site in this manner in the [Building a Theme guide](/tutorial/building-a-theme/#set-up-yarn-workspaces). + +**Note**: See an example of using a local plugin from the plugins folder, with `require.resolve`, and `npm link` in [this example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-local-plugins). + +## Compilation and processing with Babel + 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 diff --git a/docs/docs/loading-plugins-from-your-local-plugins-folder.md b/docs/docs/loading-plugins-from-your-local-plugins-folder.md index 92d9b59..ac2b396 100644 --- a/docs/docs/loading-plugins-from-your-local-plugins-folder.md +++ b/docs/docs/loading-plugins-from-your-local-plugins-folder.md @@ -2,25 +2,61 @@ title: Loading Plugins from Your Local Plugins Folder --- -Gatsby can also load plugins from your website's local plugins folder which is a folder named `plugins` in the website's root directory. +Gatsby can load plugins from your website's local 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`], -} +Consider this example project structure which includes a local plugin called `gatsby-local-plugin`: + +``` +/my-gatsby-site +└── /src + └── /pages + └── /components + +└── /plugins + └── /gatsby-local-plugin + └── /package.json + └── /gatsby-node.js + +└── gatsby-config.js +└── gatsby-node.js +└── package.json ``` -If you want to reference a plugin that is not in the plugins folder then you could use something like the following: +Like the name of the plugins folder implies, you can include multiple plugins in your local plugin folder. + +Including a local plugin in your plugins folder also requires a configuration step (similar to a third-party plugin you've installed in your `node_modules` folder by running `npm install`); just as plugins installed from npm need to be included in your `gatsby-config`, you need to add the name of your local plugin to the plugins array as well: ```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`), - }, + `gatsby-third-party-plugin`, + `gatsby-local-plugin`, // highlight-line ], } ``` + +## Verifying your plugin is loading + +To verify that your plugin is available for use in your Gatsby site, you can add a small snippet of code to a `gatsby-node.js` file (you may need to add the `gatsby-node.js` file if there isn't one already) in the root of your plugin: + +```javascript:title=plugins/gatsby-local-plugin/gatsby-node.js +exports.onPreInit = () => { + console.log("Testing...") +} +``` + +_The [`onPreInit` API](/docs/node-apis/#onPreInit) is the first Node API called by Gatsby right after plugins are loaded._ + +Then, when running your site in develop or build mode, you should see "Testing..." logged in your terminal: + +```sh +success open and validate gatsby-configs - 0.051s +success load plugins - 1.047s +Testing... // highlight-line +success onPreInit - 0.023s +... +``` + +## Loading local plugins from _outside_ the plugins folder + +If you want to reference a plugin that is not in the plugins folder, there are several options that are described in more detail in the [Creating a Local Plugin guide](/docs/creating-a-local-plugin/). diff --git a/docs/docs/naming-a-plugin.md b/docs/docs/naming-a-plugin.md index 98315b5..955989e 100644 --- a/docs/docs/naming-a-plugin.md +++ b/docs/docs/naming-a-plugin.md @@ -4,7 +4,7 @@ title: Naming a Plugin ## Plugin title naming conventions -There are four standard plugin naming conventions for Gatsby: +There are five 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) @@ -14,6 +14,9 @@ There are four standard plugin naming conventions for Gatsby: - 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-theme-*`** — this naming convention must be used for [Gatsby themes](/docs/themes/), which are a type of plugin. + - Docs: [creating a remark plugin](/docs/remark-plugin-tutorial/) +- **`gatsby-theme-*`** — this naming convention **must** be used for [Gatsby themes](/docs/themes/), which are a type of plugin. Without following this naming convention, the plugin will not be recognized as a theme and it will not be able to utilize the powerful [shadowing](/docs/themes/shadowing/) feature of themes. + - Example: [`gatsby-theme-blog`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog) + - Docs: [creating a theme](/tutorial/building-a-theme/) - **`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/plugins.md b/docs/docs/plugins.md index 76a9700..fc860e5 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -4,9 +4,9 @@ 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. -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/)! +There are many types of Gatsby plugins, including [data sourcing](/plugins/?=gatsby-source), [SEO](/plugins/?=seo), [responsive images](/packages/gatsby-image/?=gatsby-image), [offline support](/packages/gatsby-plugin-offline/), [Sass support](/packages/gatsby-plugin-sass/), [sitemaps](/packages/gatsby-plugin-sitemap/), [RSS feeds](/packages/gatsby-plugin-feed/), [TypeScript](/packages/gatsby-plugin-typescript/), [Google Analytics](/packages/gatsby-plugin-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/). +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/). To learn about how plugins differ from themes and starters refer to the [Plugins, Themes, & Starters conceptual guide](/docs/plugins-themes-and-starters/). Here are the guides in the Plugins section of the docs: From de3677b40b7043d14311bdffc518067d5134ddc7 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 13:41:01 +0000 Subject: [PATCH 032/100] sync with monorepo gatsbyjs/gatsby@1320250da59b6ff325929371daef7fc07f60a3a0 - minor Typos fixed ! (#21034) --- docs/tutorial/part-seven/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/part-seven/index.md b/docs/tutorial/part-seven/index.md index d42ebab..cdee90a 100644 --- a/docs/tutorial/part-seven/index.md +++ b/docs/tutorial/part-seven/index.md @@ -382,7 +382,7 @@ export default ({ data }) => { {node.frontmatter.title}{" "} — {node.frontmatter.date} From a2bcf608137ef156afe80ffa1097f29b77e3d612 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 13:47:39 +0000 Subject: [PATCH 033/100] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@cfcf0f2c8da7f778c54abd15bc40a2a1d64d6295=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=A7=B9=20Fix=20case=20of=20GitHub=20(#21033)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/deploying-to-kintohub.md | 6 +++--- docs/docs/processing-payments-with-stripe.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/deploying-to-kintohub.md b/docs/docs/deploying-to-kintohub.md index c2c9a18..f34d7ba 100644 --- a/docs/docs/deploying-to-kintohub.md +++ b/docs/docs/deploying-to-kintohub.md @@ -21,13 +21,13 @@ This guide assumes you already have a Gatsby project to deploy. If you need a pr In order to deploy a Gatsby site on KintoHub, you will need to create and deploy a **KintoBlock** into an **Environment** (development, staging, production). -_Note: A **KintoBlock** is connected to a Github repository. Accessing the kintoblock page will allow you to build, manage or tags any branches of your repository._ +_Note: A **KintoBlock** is connected to a GitHub repository. Accessing the kintoblock page will allow you to build, manage or tags any branches of your repository._ ### Create a KintoBlock 1. Register on [KintoHub](https://beta.kintohub.com). 2. Create a new **KintoBlock** of type **Website** and give KintoHub permission to access your GitHub repo. -3. Select your Github repo from the list and press **Continue**. +3. Select your GitHub repo from the list and press **Continue**. 4. Choose **Static from Build** with the following values: | | | @@ -40,7 +40,7 @@ _Note: A **KintoBlock** is connected to a Github repository. Accessing the kinto 5. Press **Create Website**. -The build will automatically start on the default Github branch of your repository. +The build will automatically start on the default GitHub branch of your repository. Wait for your build to be successful (green). #### Multiple Branches diff --git a/docs/docs/processing-payments-with-stripe.md b/docs/docs/processing-payments-with-stripe.md index ec04129..e29db0b 100644 --- a/docs/docs/processing-payments-with-stripe.md +++ b/docs/docs/processing-payments-with-stripe.md @@ -53,7 +53,7 @@ Check out the [Gatsby E-Commerce Tutorial](https://www.gatsbyjs.org/tutorial/eco Stripe Elements are prebuilt UI components that help you create checkout flows on the web. Unlike Checkout, Elements give you complete control over the payment experience. Elements require you to write both client-side and server-side code. -React Stripe Elements is a wrapper around Stripe Elements that help you add Elements to React applications and manage the state and lifecycle of Elements. Documentation can be found at the [React Stripe Elements Github](https://github.com/stripe/react-stripe-elements). +React Stripe Elements is a wrapper around Stripe Elements that help you add Elements to React applications and manage the state and lifecycle of Elements. Documentation can be found at the [React Stripe Elements GitHub](https://github.com/stripe/react-stripe-elements). The Stripe documentation explains how to [accept a payment](https://stripe.com/docs/payments/accept-a-payment-charges#node) using Elements. @@ -98,5 +98,5 @@ Stripe Billing is an excellent tool for creating recurring payments, even provid - [Stripe website](https://stripe.com/) - [Stripe API documentation](https://stripe.com/docs/api) - [Stripe testing documentation](https://stripe.com/docs/testing). -- [React Stripe Elements Github](https://github.com/stripe/react-stripe-elements) +- [React Stripe Elements GitHub](https://github.com/stripe/react-stripe-elements) - [Making an e-commerce Gatsby Site with Stripe](https://www.gatsbyjs.org/tutorial/ecommerce-tutorial/) From 7d864a6a2f28a2e3160da0325c3abb841ca21e25 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 16:34:44 +0000 Subject: [PATCH 034/100] sync with monorepo gatsbyjs/gatsby@fad926e49ef878b478c85608a7c63f7338a7cc59 - Remove misleading configuration from gatsby themes example (#20966) --- docs/docs/recipes/working-with-themes.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/docs/recipes/working-with-themes.md b/docs/docs/recipes/working-with-themes.md index 5550219..e995e52 100644 --- a/docs/docs/recipes/working-with-themes.md +++ b/docs/docs/recipes/working-with-themes.md @@ -48,9 +48,6 @@ module.exports = { - mdx defaults to `true` */ basePath: `/blog`, - contentPath: `content/blogPosts`, - assetPath: `content/blogAssets`, - mdx: false, }, }, ], From 56f44fc2e9f9a5a2fc224639fe03dd4f584ab5d2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 30 Jan 2020 16:57:00 +0000 Subject: [PATCH 035/100] sync with monorepo gatsbyjs/gatsby@7edd54fba33fe35abc8b2b94826df9ea45290253 - Localhost urls (#21047) * Mark localhost URLs as code snippets * Mark localhost URLs as code snippets * mark all localhost URL references as code highlighted strings instead of links * Update docs/contributing/gatsby-style-guide.md Co-Authored-By: Marcy Sutton * Update docs/docs/pixabay-source-plugin-tutorial.md Co-Authored-By: Marcy Sutton * chore: format Co-authored-by: Brittney Ball Co-authored-by: Marcy Sutton Co-authored-by: GatsbyJS Bot --- docs/contributing/gatsby-style-guide.md | 4 ++++ docs/docs/adding-an-rss-feed.md | 2 +- docs/docs/adding-search-with-js-search.md | 4 ++-- docs/docs/building-an-ecommerce-site-with-shopify.md | 2 +- docs/docs/creating-dynamic-navigation.md | 4 ++-- docs/docs/graphql-api.md | 2 +- docs/docs/mdx/programmatically-creating-pages.md | 2 +- docs/docs/running-queries-with-graphiql.md | 6 +++--- docs/docs/schema-customization.md | 2 +- docs/docs/sourcing-content-from-json-or-yaml.md | 2 +- docs/docs/sourcing-from-contentstack.md | 4 ++-- docs/docs/sourcing-from-gentics-mesh.md | 6 +++--- docs/docs/sourcing-from-graphcms.md | 2 +- docs/docs/sourcing-from-kentico-kontent.md | 8 ++++---- docs/docs/sourcing-from-prismic.md | 2 +- docs/docs/sourcing-from-sanity.md | 4 ++-- docs/docs/typography-js.md | 2 +- docs/docs/visual-testing-with-storybook.md | 2 +- docs/tutorial/part-five/index.md | 2 +- docs/tutorial/part-seven/index.md | 2 +- 20 files changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/contributing/gatsby-style-guide.md b/docs/contributing/gatsby-style-guide.md index 3a48496..3ea27a2 100644 --- a/docs/contributing/gatsby-style-guide.md +++ b/docs/contributing/gatsby-style-guide.md @@ -135,6 +135,10 @@ Hyperlinks should contain the clearest words to indicate where the link will lea In tutorials that are meant for beginners, use as few hyperlinks as possible to minimize distractions. In docs, it's ok to include as many hyperlinks as necessary to provide relevant and interesting information and resources. +### Mark localhost URLs as code strings + +Unless you're running `gatsby develop` or `gatsby build` locally, localhost links will not work. Therefore it's recommended to list these URL references as code blocks so there aren't invalid links throughout the docs on Gatsbyjs.org. + ### Indicate when something is optional When a paragraph or sentence offers an optional path, the beginning of the first sentence should indicate that it's optional. For example, "if you'd like to learn more about xyz, see our reference guide" is clearer than "Go to the reference guide if you'd like to learn more about xyz." diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index e3f2a07..053d9f5 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -132,7 +132,7 @@ The `output` field in your feed object allows you to customize the filename for By default, feed is referenced in every page. You can customize this behavior by providing an extra field `match` of type `string`. This string will be used to build a `RegExp`, and this regular expression will be used to test the `pathname` of current page. Only pages that satisfied the regular expression will have feed reference included. -To see your feed in action, run `gatsby build && gatsby serve` and you can then inspect the content and URLs in your RSS file at . +To see your feed in action, run `gatsby build && gatsby serve` and you can then inspect the content and URLs in your RSS file at `http://localhost:9000/rss.xml`. > NOTE: if your blog has custom permalinks, such as links with or without dates in them, you may need to [customize `gatsby-node.js`](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/gatsby-node.js#L57) to output the correct URLs in your RSS feed. [Get in touch with us](/contributing/how-to-contribute/) if you need any help! diff --git a/docs/docs/adding-search-with-js-search.md b/docs/docs/adding-search-with-js-search.md index e0b00db..251a814 100644 --- a/docs/docs/adding-search-with-js-search.md +++ b/docs/docs/adding-search-with-js-search.md @@ -253,7 +253,7 @@ Breaking down the code into smaller parts: In order to get it working in your site, you would only need to import the newly created component to a page. As you can see [in the example site](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-js-search/src/pages/index.js). -Run `gatsby develop` and if all went well, open your browser of choice and enter the url - you'll have a fully functional search at your disposal. +Run `gatsby develop` and if all went well, open your browser of choice and enter the url `http://localhost:8000` - you'll have a fully functional search at your disposal. ## JS-Search with a big dataset @@ -571,7 +571,7 @@ Once again to get it to work on your site you would only need to copy over [the And both the [template](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-js-search/src/templates/ClientSearchTemplate.js) and the [search component](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-js-search/src/components/ClientSearch.js). -Issuing `gatsby develop` again, and if all went without any issues one more time, open your browser of choice and enter the url , you'll have a fully functional search at your disposal coupled with Gatsby API. +Issuing `gatsby develop` again, and if all went without any issues one more time, open your browser of choice and enter the url `http://localhost:8000/search`, you'll have a fully functional search at your disposal coupled with Gatsby API. Hopefully this rather extensive guide has shed some insights on how to implement client search using js-search. diff --git a/docs/docs/building-an-ecommerce-site-with-shopify.md b/docs/docs/building-an-ecommerce-site-with-shopify.md index f55cbba..2611b6c 100644 --- a/docs/docs/building-an-ecommerce-site-with-shopify.md +++ b/docs/docs/building-an-ecommerce-site-with-shopify.md @@ -44,7 +44,7 @@ plugins: [ ## Querying Shopify data and listing products -Open the Gatsby GraphiQL interface by visiting . With at least one example product added into Shopify you should see several new types of nodes in the Explorer tab, like `allShopifyProduct`. To query all products in your store sorted by title, try running the query: +Open the Gatsby GraphiQL interface by visiting `http://localhost:8000/___graphql`. With at least one example product added into Shopify you should see several new types of nodes in the Explorer tab, like `allShopifyProduct`. To query all products in your store sorted by title, try running the query: ```graphql { diff --git a/docs/docs/creating-dynamic-navigation.md b/docs/docs/creating-dynamic-navigation.md index d0c3890..c52da25 100644 --- a/docs/docs/creating-dynamic-navigation.md +++ b/docs/docs/creating-dynamic-navigation.md @@ -42,7 +42,7 @@ module.exports = { GraphQL can be used to query for information contained in the `siteMetadata` object located in your project's `gatsby-config.js`. In order to test this out, you can start the `default-starter-project` in development mode by running `npm run develop`. -Navigate to in your browser to view the GraphiQL editor, which enables you to test GraphQL queries on the underlying APIs. Using the documentation explorer you can view the current GraphQL schema for your project, which is an invaluable resource during development. +Navigate to `http://localhost:8000/___graphql` in your browser to view the GraphiQL editor, which enables you to test GraphQL queries on the underlying APIs. Using the documentation explorer you can view the current GraphQL schema for your project, which is an invaluable resource during development. Examining the available types in GraphQL you will notice that you can query `site`. This GraphQL type further returns the `siteMetadata` which needs to be accessed to create the dynamic navigation. At this point, it is useful if you know a little GraphQL in order to extract the menu links. If you are unfamiliar with GraphQL, there is some excellent documentation available at GraphQL's official website found [here](https://graphql.org/learn/) that you can use to brush up on your skills! The query below will return the menu links. @@ -263,7 +263,7 @@ Header.defaultProps = { export default Header ``` -Starting the development server by running `npm run develop` and navigating to you should now see some dynamically generated menu links on your page. +Starting the development server by running `npm run develop` and navigating to `http://localhost:8000` you should now see some dynamically generated menu links on your page. If you have made it this far, good job! You can now add new site links to your website dynamically by adding entries to the `gatsby-config.js` file. diff --git a/docs/docs/graphql-api.md b/docs/docs/graphql-api.md index ef76c6c..d64f64e 100644 --- a/docs/docs/graphql-api.md +++ b/docs/docs/graphql-api.md @@ -12,7 +12,7 @@ This doc serves as a reference for GraphQL features built into Gatsby, including ## Getting started with GraphQL -GraphQL is available in Gatsby without a special install: a schema is automatically inferred and created when you run `gatsby develop` or `gatsby build`. When the site compiles, the data layer can be [explored](/docs/running-queries-with-graphiql/) at: +GraphQL is available in Gatsby without a special install: a schema is automatically inferred and created when you run `gatsby develop` or `gatsby build`. When the site compiles, the data layer can be [explored](/docs/running-queries-with-graphiql/) at: `http://localhost:8000/___graphql` ## Sourcing data diff --git a/docs/docs/mdx/programmatically-creating-pages.md b/docs/docs/mdx/programmatically-creating-pages.md index 2c5da23..9446d20 100644 --- a/docs/docs/mdx/programmatically-creating-pages.md +++ b/docs/docs/mdx/programmatically-creating-pages.md @@ -147,7 +147,7 @@ to construct a query that finds all MDX nodes and pulls out the `slug` field added earlier. > **Note**: You can open up a GraphiQL console for query testing -> in your browser at +> in your browser at `http://localhost:8000/___graphql` ```graphql query { diff --git a/docs/docs/running-queries-with-graphiql.md b/docs/docs/running-queries-with-graphiql.md index 9122473..e5c282a 100644 --- a/docs/docs/running-queries-with-graphiql.md +++ b/docs/docs/running-queries-with-graphiql.md @@ -10,11 +10,11 @@ GraphiQL is the GraphQL integrated development environment (IDE). It's a powerfu you'll use often while building Gatsby websites. You can access it when your site's development server is running--normally at -. +`http://localhost:8000/___graphql`. ## Example of using GraphiQL -When you have open, it will look something like what this video shows. In the video below, watch someone poke around the built-in `Site` "type" and see what fields are available +When you have `http://localhost:8000/___graphql` open, it will look something like what this video shows. In the video below, watch someone poke around the built-in `Site` "type" and see what fields are available on it—including the `siteMetadata` object.