From 97b6c429d7bc852cebb52b2939e5b1c9462ce405 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 19 Feb 2020 17:09:45 +0000 Subject: [PATCH 001/127] sync with monorepo gatsbyjs/gatsby@9b2d51b50fc2187138bf2ab3c94571db6fa1b580 - chore (doc): maintaining a plugin guide. (#21221) * Started work on Maintaining plugin stub * Corrected Comments that were casuing .md file form showiing in preview * added Handling patches and improvments, Updating Readme and use case sections * aAdded Tooling and dependency improvements section * updated doc to fit style guide. * Updated PR with correction from Kyle G. * Updated PR with review * Updated PR with review * Updated PR with reviews * update doc with review and remove asterisk from doc-liink yaml * add reviews from Laurie * Update * update maintianing Plugin PR with reviews from Marcy Co-authored-by: GatsbyJS Bot --- docs/docs/maintaining-a-plugin.md | 59 ++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/docs/docs/maintaining-a-plugin.md b/docs/docs/maintaining-a-plugin.md index bb05a9dcf..cbd279019 100644 --- a/docs/docs/maintaining-a-plugin.md +++ b/docs/docs/maintaining-a-plugin.md @@ -1,10 +1,61 @@ --- title: Maintaining a Plugin -issue: https://github.com/gatsbyjs/gatsby/issues/21067 --- -This is a stub article meant to be filled with tips on how to maintain a Gatsby plugin once you've published it as an npm package. +The Gatsby community thrives on the power of plugins. You often find that there is a plugin for almost everything ranging from source plugins to transformer plugins. A useful way of understanding the purpose of a plugin at a glance is by its name. Check out the [guide to naming conventions for plugins](/docs/naming-a-plugin/) to learn more. -Topics to be covered: +> Wondering how to [create a plugin](/docs/creating-plugins)? Look no further. Start contributing. -- yarn workspaces can solve yarn link inconsistencies +## What is a plugin? + +Gatsby plugins are Node.js packages that implement Gatsby APIs. To learn more take a look at the [plugin documentation](/docs/plugins/). + +In creating plugins, the bulk of the work is during the development phase. However, there’s still a need to take a look at the dependencies and security features from time to time. Keeping plugins up to date can become really tasking and it is important to be careful when updating dependencies, seeing as this could potentially break users' apps. + +However, the consequences of not updating and maintaining a plugin can introduce security issues to your users. The following are some recommendations for maintaining plugins: + +## Handling patches and improvements + +Most plugins generally follow [Semantic Versioning](https://semver.org/) to determine how many releases to do and the type of releases. + +The first public release of a plugin is 0.1.0 or 1.0.0. From there, bugs are fixed in patch releases (e.g. 0.1.1) and features are added or changed in minor releases (e.g. 0.2.0). + +Version 1.0.0 should be released when the plugin's API is considered stable. Version 2.0.0 (and subsequent major releases) would introduce breaking API changes. + +> Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version. + +Read more about this concept [in this paper on semantic versioning ](https://semver.org/). + +## Update README and document use cases + +Every major version update should also be reflected in the README of the plugin as well as the use case examples. + +It would be great for users to be able to reference several versions of the plugin with the updated examples to see if they want to keep the current version or upgrade and also to understand what the new version offers. Although this is good: + +- Try to not clog your release repository with older versions of the plugin as you update, as they’re not often needed. Instead, simply keep the last few in place. + +- Try not to push every iterative change from Git live + +## Tools for dependency version maintenance + +There are a couple of useful tools that can help with keeping dependencies up to date. + +- [Version Lens](https://marketplace.visualstudio.com/items?itemName=pflannery.vscode-versionlens) enables you to update your dependencies from your `package.json` by allowing you see the available version number the package can be updated to, right above the current version each package in dependencies or devDependencies uses. + +- The [npm check updates](https://www.npmjs.com/package/npm-check-updates) command line tool helps to check for outdated dependencies. You can also use this tool to update those dependencies by following these steps: + +1. Install the tool + +```shell + npm i -g npm-check-updates +``` + +2. Run the command to update dependencies + +```shell +ncu -u +``` + +## Community supporting content and feedback + +Having example repos and support forums on Discord, Twitter or Reddit are great ways to offer community support for your plugin. This would offer a pool of resources for users to get more information on implementations and contribute. From 90932a06db2e297cf416552b84e48b4b82e56fbc Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 19 Feb 2020 20:47:40 +0000 Subject: [PATCH 002/127] sync with monorepo gatsbyjs/gatsby@8234336d31e695ef6985c6e17bf997cb862b1357 - (docs) Update translation/style-guide.md (#21570) * Update style-guide.md * Update style-guide.md * chore: format Co-authored-by: GatsbyJS Bot --- docs/contributing/translation/style-guide.md | 34 ++++++++++++++++---- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/contributing/translation/style-guide.md b/docs/contributing/translation/style-guide.md index 1fa36b8c0..90f9a07d4 100644 --- a/docs/contributing/translation/style-guide.md +++ b/docs/contributing/translation/style-guide.md @@ -6,19 +6,41 @@ Each language translation may have some specific ways it differs from the advice Guidelines that remain firm no matter the language stem from the goals and values of Gatsby as a project: to provide a **friendly community for Gatsby learners of all skill and experience levels** that's also **safe and welcoming to contributors**. Translated docs and learning materials should [maintain these values](/blog/2019-04-19-gatsby-why-we-write/) with **high-quality spelling and grammar**, accurate information, similar structure and purpose. For any questions about guidelines, feel free to [get in touch](/contributing/how-to-contribute/#not-sure-how-to-start-contributing) with the Gatsby team. -### Glossary +## Glossary The style guide has a [glossary section](https://github.com/gatsbyjs/gatsby-i18n-source/blob/master/style-guide.md#glossary) that you can use to fill in common translations. Look at the English [Glossary](/docs/glossary/) for a list of terms that are useful to have translations for. -### Universal style guide +## Universal style guide The following rules should apply in all translations and can serve as a basis for your language-specific style guide. -#### Keep the meaning of the source +### Keep the meaning of the source Keep the meaning of the original English source even if it is confusing or has a typo. If you find an error that can be fixed, create an issue or pull request to the original [gatsby repo](https://github.com/gatsbyjs/gatsby) so that all translations can benefit from the change. -#### Text in code blocks +### Use soft line wraps + +Use soft line wraps for paragraphs: + +✅ DO: + +```md +No intuito de promover um ambiente aberto e acolhedor, nós, como contribuidores e mantenedores, nos comprometemos em tornar a participação em nossos projetos e em nossa comunidade o mais livre de assédio para todos, independentemente da idade, corpo, tamanho, deficiência, etnia, identidade ou expressão de gênero, nível de experiência, nacionalidade, aparência, raça, religião ou identidade e orientação sexual. +``` + +❌ DON'T: + +```md +No intuito de promover um ambiente aberto e acolhedor, nós, como contribuidores e mantenedores, +nos comprometemos em tornar a participação em nossos projetos e em nossa comunidade o mais livre +de assédio para todos, independentemente da idade, corpo, tamanho, deficiência, etnia, identidade +ou expressão de gênero, nível de experiência, nacionalidade, aparência, raça, religião ou identidade +e orientação sexual. +``` + +Using soft line wraps ensures that paragraphs are always matched with the original source paragraphs when syncing, and prevents weird errors with mismatched lines. + +### Text in code blocks Leave text in code blocks untranslated except for comments. You may optionally translate text in strings, but be careful not to translate strings that refer to code! @@ -62,7 +84,7 @@ exportar defecto () => ( ) ``` -#### Internal links +### Internal links Translate link text but keep all slugs and hashes in links the same as they are in English. @@ -78,7 +100,7 @@ Translate link text but keep all slugs and hashes in links the same as they are - [Configura tu entorno de desarrollo](/tutorial/configura-tu-entorno-de-desarrollo) ``` -#### External links +### External links If an external link is to an article in a reference like [MDN] or [Wikipedia], and a version of that article exists in your language that is of decent quality, consider linking to that version instead. From c42d1b3e688b964651fe56f85a4646fcb859dc74 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 20 Feb 2020 11:00:06 +0000 Subject: [PATCH 003/127] sync with monorepo gatsbyjs/gatsby@c126d044fd61440688440b487b5fe4daa8a56f71 - fix(docs): fix 404 and apply redirects (#21606) --- docs/contributing/translation/maintainers.md | 2 +- docs/contributing/translation/new-translations.md | 2 +- docs/contributing/translation/translators.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/translation/maintainers.md b/docs/contributing/translation/maintainers.md index 9fa21b515..92d14adcb 100644 --- a/docs/contributing/translation/maintainers.md +++ b/docs/contributing/translation/maintainers.md @@ -14,7 +14,7 @@ As repo maintainers and members of the Gatsby community, your responsibilities a - Act as point of contact for your language and answer questions from both contributors to your language and the core Gatsby team. - Set up a process in order to get your translation published. (details to come) -As a maintainer, you are welcome to add a contributing doc written in your language to assist with the process. You can find an example in the [gatsby-es repo](https://github.com/gatsbyjs/gatsby-es/blob/master/CONTRIBUTING.MD). Translating [this page](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/gatsby-docs-translation-guide.md) and copying it into a `contributing.md` file would be an option as well. +As a maintainer, you are welcome to add a contributing doc written in your language to assist with the process. You can find an example in the [gatsby-es repo](https://github.com/gatsbyjs/gatsby-es/blob/master/CONTRIBUTING.MD). Translating files from the folder [`docs/contributing/translation`](https://github.com/gatsbyjs/gatsby/tree/master/docs/contributing/translation) and copying it into a `contributing.md` file would be an option as well. ## Tips diff --git a/docs/contributing/translation/new-translations.md b/docs/contributing/translation/new-translations.md index 5dc91e98b..1a5a5e275 100644 --- a/docs/contributing/translation/new-translations.md +++ b/docs/contributing/translation/new-translations.md @@ -20,7 +20,7 @@ If you don't see the language among the issues listed, feel free to create a new ### Finding codeowners -For a new translation, open an issue with information about your intended language. If you already have co-contributors to act as fellow [code owners](https://help.github.com/en/articles/about-code-owners) and provide checks and balances for PR reviews and quality assurance, that would be very helpful! Otherwise, you can check out other [translation request issues](https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+%22New+Translation+Request%22) people have made and offer to join, or [get in touch with us](/contributing/how-to-contribute/#not-sure-how-to-start-contributing) at Gatsby for help in building your translation team. +For a new translation, open an issue with information about your intended language. If you already have co-contributors to act as fellow [code owners](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) and provide checks and balances for PR reviews and quality assurance, that would be very helpful! Otherwise, you can check out other [translation request issues](https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+%22New+Translation+Request%22) people have made and offer to join, or [get in touch with us](/contributing/how-to-contribute/#not-sure-how-to-start-contributing) at Gatsby for help in building your translation team. ## Criteria for translation approval diff --git a/docs/contributing/translation/translators.md b/docs/contributing/translation/translators.md index f072f4ac3..e64725248 100644 --- a/docs/contributing/translation/translators.md +++ b/docs/contributing/translation/translators.md @@ -39,4 +39,4 @@ If you would like to be a maintainer of an existing translation repo, submit a P ## When a contributor will be removed -Consistent with the [Code of Conduct](/docs/code-of-conduct/) the Gatsby team reserves the right to remove a contributor (including translation maintainers) from the Gatsby organization if necessary. Some reasons for being removed include spammy comments, closing PRs or issues without action or productive dialogue, or generally harmful or abusive behavior inconsistent with Gatsby's policies. +Consistent with the [Code of Conduct](/contributing/code-of-conduct/) the Gatsby team reserves the right to remove a contributor (including translation maintainers) from the Gatsby organization if necessary. Some reasons for being removed include spammy comments, closing PRs or issues without action or productive dialogue, or generally harmful or abusive behavior inconsistent with Gatsby's policies. From a3b358be83472e28805955c9b9faca6dd83cf3c8 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 21 Feb 2020 13:42:58 +0000 Subject: [PATCH 004/127] sync with monorepo gatsbyjs/gatsby@65d70b9c64563f257150dbd5a75f4ada878ade28 - chore(docs): Fix a line so be in context (#21639) --- docs/tutorial/part-two/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/part-two/index.md b/docs/tutorial/part-two/index.md index d84b15c76..4f6bd0812 100644 --- a/docs/tutorial/part-two/index.md +++ b/docs/tutorial/part-two/index.md @@ -32,7 +32,7 @@ One of the most straightforward ways to add global styles to a site is using a g Start by creating a new Gatsby site. It may be best (especially if you're new to the command line) to close the terminal windows you used for [part one](/tutorial/part-one/) and start a new terminal session for part two. -Open a new terminal window, create a new "hello world" gatsby site, and start the development server: +Open a new terminal window, create a new "hello world" Gatsby site in a directory called `tutorial-part-two`, and then move to this new directory: ```shell gatsby new tutorial-part-two https://github.com/gatsbyjs/gatsby-starter-hello-world From d17e2db98ee5e4faf90fce6132bd590b9c6ed3b6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 21 Feb 2020 15:34:31 +0000 Subject: [PATCH 005/127] sync with monorepo gatsbyjs/gatsby@e985d8efd477d22f7626ece9790b1511041c6ffa - chore: fix doc typo in wordpress tutorial (#20931) * chore: fix doc typo in wordpress tutorial * Update docs/tutorial/wordpress-image-tutorial.md Co-authored-by: LB Co-authored-by: GatsbyJS Bot --- docs/tutorial/wordpress-image-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/wordpress-image-tutorial.md b/docs/tutorial/wordpress-image-tutorial.md index 5f00ed65c..831ff2a0f 100644 --- a/docs/tutorial/wordpress-image-tutorial.md +++ b/docs/tutorial/wordpress-image-tutorial.md @@ -56,7 +56,7 @@ module.exports = { // Indicates whether the site is hosted on wordpress.com. // If false, then the assumption is made that the site is self hosted. // If true, then the plugin will source its content on wordpress.com using the JSON REST API V2. - // If your site is hosted on wordpress.org, then set this to false. + // If your site is hosted on wordpress.com, then set this to true. hostingWPCOM: false, // If useACF is true, then the source plugin will try to import the WordPress ACF Plugin contents. // This feature is untested for sites hosted on WordPress.com From 60599ef1a4ba93ac7ca2b8509ca0c4683066a1a2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 24 Feb 2020 08:19:41 +0000 Subject: [PATCH 006/127] sync with monorepo gatsbyjs/gatsby@a05749bbb027c74f94c7767203bab3991603d4d7 - fix(docs): GraphQL query indentation (#21687) --- docs/docs/testing-components-with-graphql.md | 32 ++++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/docs/testing-components-with-graphql.md b/docs/docs/testing-components-with-graphql.md index 03a151b86..ff920a129 100644 --- a/docs/docs/testing-components-with-graphql.md +++ b/docs/docs/testing-components-with-graphql.md @@ -109,29 +109,29 @@ you're using `gatsby-transformer-sharp` you'll find the fragments in So, for example if your query includes: ```graphql - image { - childImageSharp { - fluid(maxWidth: 1024) { - ...GatsbyImageSharpFluid - } - } +image { + childImageSharp { + fluid(maxWidth: 1024) { + ...GatsbyImageSharpFluid } + } +} ``` ...it becomes: ```graphql - image { - childImageSharp { - fluid(maxWidth: 1024) { - base64 - aspectRatio - src - srcSet - sizes - } - } +image { + childImageSharp { + fluid(maxWidth: 1024) { + base64 + aspectRatio + src + srcSet + sizes } + } +} ``` When you have the result, copy the `data` value from the output panel. Good From f76daa4a00203ebb7ac9fef479f55bec05ddfaab Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 24 Feb 2020 10:13:11 +0000 Subject: [PATCH 007/127] sync with monorepo gatsbyjs/gatsby@ff5458502473b4f50febc717266ce039ac26a93f - feat(www): update pairing session (#21603) Co-authored-by: GatsbyJS Bot --- docs/contributing/pair-programming.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/contributing/pair-programming.md b/docs/contributing/pair-programming.md index b414d39c8..b2359932e 100644 --- a/docs/contributing/pair-programming.md +++ b/docs/contributing/pair-programming.md @@ -30,8 +30,10 @@ We also expect the following from pair programming participants: ## How to sign up -We allow booking up to 30 days in advance, and spots tend to fill up fast. If we’re all booked up today, check back tomorrow for the next batch of spots. The core team is spread across North America, India, and Europe, so most time zones will have availability during working hours. +Fill in the [request a pairing session form][cal] to reserve your spot. The Gatsby team will be notified. You should get an email shortly with next steps. + +**Note:** Pairing sessions are currently paused as we establish a new process that will include recording so we can create lasting resources for the community from these sessions. We'll reach out to set up a time that works for you once we have the details ironed out. The core team is spread across North America, India, and Europe, so most time zones will have availability during working hours. [Reserve your spot today][cal] and let’s build something amazing together! -[cal]: https://calendly.com/gatsbyjs/pair-programming +[cal]: https://gatsby.dev/register-pair-programming From a9155aba1cb21dd380e4cd98e65cef2e2b4f61ff Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 24 Feb 2020 17:21:46 +0000 Subject: [PATCH 008/127] sync with monorepo gatsbyjs/gatsby@9edffa301adc0e2075c59fd19a4cd62ce94fda16 - fix(www): Remove GraphQL playground (#21703) --- docs/docs/gatsby-link.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md index f24ca64b4..7ec5089fe 100644 --- a/docs/docs/gatsby-link.md +++ b/docs/docs/gatsby-link.md @@ -282,7 +282,7 @@ const Form = () => ( It is common to host sites in a sub-directory of a site. Gatsby lets you [set the path prefix for your site](/docs/path-prefix/). After doing so, Gatsby's `` component will automatically handle constructing the correct URL in development and production. -For pathnames you construct manually, there's a helper function, `withPrefix` that prepends your path prefix in production (but doesn't during development where paths don't need prefixed). +For pathnames you construct manually, there's a helper function, `withPrefix` that prepends your path prefix in production (but doesn't during development where paths don't need to be prefixed). ```jsx import { withPrefix } from "gatsby" From 17e4c4c4eb7ee17810076e731d2597f40dc89f17 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 25 Feb 2020 12:52:35 +0000 Subject: [PATCH 009/127] sync with monorepo gatsbyjs/gatsby@4f7424a2736963946638556b4d9754e61697e485 - fix(gatsby-theme-notes): fix notes failing tests (#21709) --- docs/docs/creating-and-modifying-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/creating-and-modifying-pages.md b/docs/docs/creating-and-modifying-pages.md index a0abff99e..a6ad4a3c3 100644 --- a/docs/docs/creating-and-modifying-pages.md +++ b/docs/docs/creating-and-modifying-pages.md @@ -89,10 +89,10 @@ exports.createPages = async ({ graphql, actions, reporter }) => { createPage({ path, component: blogPostTemplate, - // In your blog post template's graphql query, you can use path + // In your blog post template's graphql query, you can use pagePath // as a GraphQL variable to query for data from the markdown file. context: { - path, + pagePath: path, }, }) }) From 569725c09f62e7f7d10662611c5a6e3b654c7f10 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 25 Feb 2020 13:20:07 +0000 Subject: [PATCH 010/127] sync with monorepo gatsbyjs/gatsby@22a05a96caa84d28a99b62326c893bfcc24a4e4f - chore(recipe):Add a recipe for using FontAwesome (#21275) * Recipe for using fontawesome * Update docs/docs/recipes/styling-css.md Co-Authored-By: Marcy Sutton * Update docs/docs/recipes/styling-css.md Co-Authored-By: Marcy Sutton * Update docs/docs/recipes/styling-css.md Co-Authored-By: Marcy Sutton * Update docs/docs/recipes/styling-css.md Co-Authored-By: Marcy Sutton * Update docs/docs/recipes/styling-css.md Co-Authored-By: Marcy Sutton * Address review comments * Break FontAwesome into two words Co-authored-by: Marcy Sutton Co-authored-by: Aisha Blake Co-authored-by: GatsbyJS Bot --- docs/docs/recipes.md | 1 + docs/docs/recipes/styling-css.md | 41 ++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md index 516f6f1e3..7a7b48bf3 100644 --- a/docs/docs/recipes.md +++ b/docs/docs/recipes.md @@ -53,6 +53,7 @@ There are so many ways to add styles to your website; Gatsby supports almost eve - [Adding a Local Font](/docs/recipes/styling-css#adding-a-local-font) - [Using Emotion](/docs/recipes/styling-css#using-emotion) - [Using Google Fonts](/docs/recipes/styling-css#using-google-fonts) +- [Using Font Awesome](/docs/recipes/styling-css#using-fontawesome) ## [3. Working with starters](/docs/recipes/working-with-starters) diff --git a/docs/docs/recipes/styling-css.md b/docs/docs/recipes/styling-css.md index af10dc88d..1bb7994f2 100644 --- a/docs/docs/recipes/styling-css.md +++ b/docs/docs/recipes/styling-css.md @@ -416,3 +416,44 @@ _NOTE: So for the above example, the relevant CSS declaration would be `font-fam - [Typography.js](/docs/typography-js/) - Another option for using Google fonts on a Gatsby site - [The Typefaces Project Docs](https://github.com/KyleAMathews/typefaces/blob/master/README.md) - [Live example on Kyle Mathews' blog](https://www.bricolage.io/typefaces-easiest-way-to-self-host-fonts/) + +## Using Font Awesome + +Using [Font Awesome](https://fontawesome.com/) gives you access to thousands of icons for use on your site. Since Gatsby sites are React sites, it's recommended to use the [react-fontawesome](https://github.com/FortAwesome/react-fontawesome) SVG library. + +### Prerequisites + +- The [Gatsby CLI](/docs/gatsby-cli/) installed +- A [Gatsby site](/docs/quick-start) + +### Directions + +1. Install the `react-fontawesome` dependencies. + +```shell +npm install @fortawesome/fontawesome-svg-core @fortawesome/free-brands-svg-icons @fortawesome/react-fontawesome +``` + +> Note that there are multiple icon libraries within `react-fontawesome`. You may also be interested in `free-regular-svg-icons` and `free-solid-svg-icons` which you would install the same way. + +2. Import the `FontAwesomeIcon` component and the icon you want to use. Then use the icon as a component directly in your JSX files: + +```jsx:title=index.js +import { FontAwesomeIcon } from "@fortawesome/react-fontawesome" +import { faReact } from "@fortawesome/free-brands-svg-icons" + +const IndexPage = () => ( + + //highlight-line + +) + +export default IndexPage +``` + +> This example imports a single, specific icon and uses it for improved performance. As an alternative, you can [import the icons and build a library](https://github.com/FortAwesome/react-fontawesome#build-a-library-to-reference-icons-throughout-your-app-more-conveniently). + +### Additional resources + +- [Font Awesome](https://fontawesome.com/) +- [react-fontawesome](https://github.com/FortAwesome/react-fontawesome) From fd13a311638dca6478c3695cd285cb76a62fdffe Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 25 Feb 2020 16:16:38 +0000 Subject: [PATCH 011/127] sync with monorepo gatsbyjs/gatsby@310aed4ba23cdf14011be8724391caa01ec05cbc - refactor(www): Change the way we determine locales (#21539) * Change the way we determine locales * update README * update with link * update * fix --- docs/contributing/translation/index.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/docs/contributing/translation/index.md b/docs/contributing/translation/index.md index 9a0664c67..82172a16e 100644 --- a/docs/contributing/translation/index.md +++ b/docs/contributing/translation/index.md @@ -14,26 +14,7 @@ Each translation has its own repository in the [gatsbyjs](https://github.com/gat Currently, the following languages are being translated: -- [Arabic](https://github.com/gatsbyjs/gatsby-ar) -- [Bengali](https://github.com/gatsbyjs/gatsby-bn) -- [German](https://github.com/gatsbyjs/gatsby-de) -- [Spanish](https://github.com/gatsbyjs/gatsby-es) -- [French](https://github.com/gatsbyjs/gatsby-fr) -- [Gujarati](https://github.com/gatsbyjs/gatsby-gu) -- [Hindi](https://github.com/gatsbyjs/gatsby-hi) -- [Indonesian](https://github.com/gatsbyjs/gatsby-id) -- [Italian](https://github.com/gatsbyjs/gatsby-it) -- [Japanese](https://github.com/gatsbyjs/gatsby-ja) -- [Korean](https://github.com/gatsbyjs/gatsby-ko) -- [Mongolian](https://github.com/gatsbyjs/gatsby-mn) -- [Dutch](https://github.com/gatsbyjs/gatsby-nl) -- [Polish](https://github.com/gatsbyjs/gatsby-pl) -- [Brazilian Portuguese](https://github.com/gatsbyjs/gatsby-pt-BR) -- [Russian](https://github.com/gatsbyjs/gatsby-ru) -- [Turkish](https://github.com/gatsbyjs/gatsby-tr) -- [Vietnamese](https://github.com/gatsbyjs/gatsby-vi) -- [Simplified Chinese](https://github.com/gatsbyjs/gatsby-zh-Hans) -- [Traditional Chinese](https://github.com/gatsbyjs/gatsby-zh-Hant) + > Note: Once a new translation repository is created, feel free to add it here in a PR! From 544ea88b26036514a0018d4526ff6b3f388823a7 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 25 Feb 2020 18:19:09 +0000 Subject: [PATCH 012/127] sync with monorepo gatsbyjs/gatsby@5b76f2550a7bf7d69db8f440e18b6853f11faf0b - docs: add missing syntax highlight (#21722) * docs: add missing syntax highlight * docs: add title to json example * Apply suggestions from code review Co-Authored-By: LB Co-authored-by: LB --- docs/docs/using-graphql-playground.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/using-graphql-playground.md b/docs/docs/using-graphql-playground.md index 8e8927114..dc63aaf34 100644 --- a/docs/docs/using-graphql-playground.md +++ b/docs/docs/using-graphql-playground.md @@ -14,19 +14,19 @@ GraphQL Playground is a way for you to interact with the data your sources and p To access this experimental feature utilizing GraphQL Playground with Gatsby, add `GATSBY_GRAPHQL_IDE` to your `develop` script in your `package.json`, like this: -```json +```json:title=package.json "develop": "GATSBY_GRAPHQL_IDE=playground gatsby develop", ``` If you are on **Windows** then you should use: -``` +```json:title=package.json "develop": "cross-env GATSBY_GRAPHQL_IDE=playground gatsby develop", ``` If you haven't installed **cross-env**, you can do it with: -``` +```shell npm install --save-dev cross-env ``` From f6257e1df808fba1bf1e8647d26067291cf156f6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 25 Feb 2020 22:11:09 +0000 Subject: [PATCH 013/127] sync with monorepo gatsbyjs/gatsby@14131a0cb3f37dea4b5098d9bdfd08f8dfe48d13 - (docs): Reference guide for using WooCommerce (#21745) * Add WooCommerce guide draft * Add WC details * chore: format * Apply suggestions from code review Co-Authored-By: LB * Remove "straightforward" sentence * Reorder sections Co-authored-by: GatsbyJS Bot Co-authored-by: LB --- docs/docs/sourcing-from-woocommerce.md | 90 ++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/docs/sourcing-from-woocommerce.md diff --git a/docs/docs/sourcing-from-woocommerce.md b/docs/docs/sourcing-from-woocommerce.md new file mode 100644 index 000000000..eed8160c8 --- /dev/null +++ b/docs/docs/sourcing-from-woocommerce.md @@ -0,0 +1,90 @@ +--- +title: Sourcing from WooCommerce +--- + +WooCommerce is the e-commerce platform for WordPress. This guide will serve as a helpful reference whether you’re interested in getting started with e-commerce for your WordPress site or beginning to use Gatsby with your current WooCommerce setup. + +## Prerequisites + +This guide assumes some familiarity with WordPress. You may want to read about [Sourcing from WordPress](/docs/sourcing-from-wordpress/) or step through a [tutorial on how to build a blog with WordPress and Gatsby](/blog/2019-04-26-how-to-build-a-blog-with-wordpress-and-gatsby-part-1) before diving in. + +You’ll need a WordPress site with the [WooCommerce](https://woocommerce.com/) plugin installed and activated. + +## Existing plugins + +This guide assumes the use of the [`gatsby-source-woocommerce` plugin](/packages/@pasdo501/gatsby-source-woocommerce/). + +Install it: + +```bash +npm install --save @pasdo501/gatsby-source-woocommerce +``` + +Configure its options: + +```js:title=gatsby-config.js +{ + resolve: "@pasdo501/gatsby-source-woocommerce", + options: { + // Base URL of Wordpress site + api: 'wordpress.domain', + // true if using https. false otherwise. + https: false, + api_keys: { + consumer_key: `your key`, + consumer_secret: `your secret`, + }, + // Array of strings with fields you'd like to create nodes for... + fields: ['products', 'products/categories', 'products/attributes'], + } +}, +``` + +The `consumer_key` and `consumer_secret` come from WooCommerce. From your dashboard, go to WooCommerce > Settings > Advanced > REST API and then add a key. You can then copy and paste both the key and secret. Make sure to store any sensitive information in [environment variables](/docs/environment-variables/)! + +It's worth noting that the offical WordPress source plugin is in active development. Knowing that this work is in-progress, if you're interested in working with a GraphQL endpoint directly in your WordPress installation, see the section below on [pending changes](#pending-changes) to get started with WPGraphQL and WooCommerce. + +## Adding products + +WooCommerce products are the core of your WooCommerce site, so you’ll want to add some to your store. When you’re first getting started, there’s no need to dump absolutely everything you want to sell into your store. Begin with a few products that you can use to verify that everything is hooked up correctly. You can also [import products from a CSV file](https://docs.woocommerce.com/document/product-csv-importer-exporter/). + +You should see a prompt to create your first product after completing the WooCommerce setup wizard. Doing so at this time will trigger a guided tour of the new product form. Walk through this process for each product you'd like to add to your store. + +Once this is done, you’ll be able to use GraphQL to query for your products by adding this query to the appropriate component: + +```graphql +allWcProducts { + edges { + node { + name + price + } + } +} +``` + +## Testing queries + +### Using GraphiQL + +You can explore the data available to your site [using GraphiQL](/docs/running-queries-with-graphiql/). This is dependent on the fields you have specified in `gatsby-config.js`. The plugin documentation has tons of [suggested GraphQL queries](/packages/@pasdo501/gatsby-source-woocommerce/#some-graphql-query-examples). If you don't see the options listed there, try adjusting the `fields` array and/or refreshing your GraphiQL tab. + +### Using WPGraphQL + +You can explore possible queries in the [WPGraphQL WooCommerce Playground](https://docs.wpgraphql.com/extensions/wpgraphql-woocommerce/#playground). Note that some queries are only available to shop managers as opposed to customers. + +## Pending Changes + +Note that `gatsby-source-wordpress` is undergoing a major rewrite at the time of writing. This new major version of the official source plugin is likely to change the optimal solution for using WooCommerce with Gatsby. For now, new projects should start with [`gatsby-source-graphql`](/packages/gatsby-source-graphql/) rather than `gatsby-source-wordpress` to ease the transition. If you’re interested in the current progress of the plugin, you can [check out the working alpha version](https://github.com/gatsbyjs/gatsby/issues/19292#issuecomment-587946239). **Once this work is done, the [`wp-graphql-woocommerce` plugin](https://github.com/wp-graphql/wp-graphql-woocommerce) will be the recommended option.** + +If you decide to go with this more experimental route, you'll need to install and activate the [WPGraphQL](https://www.wpgraphql.com/) and [wp-graphql-woocommerce](https://github.com/wp-graphql/wp-graphql-woocommerce) plugins on your WordPress site as well. + +The WPGraphQL plugin is also undergoing significant changes. It has not yet hit v1 and may therefore introduce [breaking changes](https://docs.wpgraphql.com/getting-started/install-and-activate/#breaking-change-notice) as it continues to progress through development. It can be used in production but keep this in mind when using the plugin! + +## Other resources + +- [`gatsby-source-woocommerce`](/packages/@pasdo501/gatsby-source-woocommerce/) +- [`gatsby-theme-woocommerce`](/packages/@ccerda0520/gatsby-theme-woocommerce/) +- [`wp-graphql-woocommerce` plugin](https://github.com/wp-graphql/wp-graphql-woocommerce) +- [experimental `gatsby-source-wordpress` starter](https://github.com/TylerBarnes/using-gatsby-source-wordpress-experimental) +- [Sourcing from WordPress](/docs/sourcing-from-wordpress/) From 98ef3b01cb963cdd900626b577b3c3eace75220f Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 26 Feb 2020 09:01:43 +0000 Subject: [PATCH 014/127] sync with monorepo gatsbyjs/gatsby@232cf7757e7d36223e17f914978d8e765b4b172b - docs/glossary: Add Markdown article. (#21587) * docs/glossary: Add Markdown article. Updated sidebar, glossary.md with links to new entry. * Add a Markdown example. * Add a Markdown example. * Remove a stray < from the code example. * Typo fixes, swap caption for figcaption * switch in to from * chore: format Co-authored-by: Aisha Blake Co-authored-by: GatsbyJS Bot --- docs/docs/glossary.md | 2 +- docs/docs/glossary/markdown.md | 65 ++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 docs/docs/glossary/markdown.md diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index faf6f88cc..f1f34aaf0 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -210,7 +210,7 @@ Linting is the process of running a program that will analyze code for potential Extends [Markdown](#markdown) to support [React](#react) [components](#component) within your content. -### Markdown +### [Markdown](/docs/glossary/markdown/) A way of writing HTML content with plain text, using special characters to denote content types such as hash symbols for [headings](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements), and underscores and asterisks for text emphasis. diff --git a/docs/docs/glossary/markdown.md b/docs/docs/glossary/markdown.md new file mode 100644 index 000000000..ac63aa0f9 --- /dev/null +++ b/docs/docs/glossary/markdown.md @@ -0,0 +1,65 @@ +--- +title: Markdown +disableTableOfContents: true +--- + +Learn what Markdown is, why you might use it, and how it fits into the Gatsby ecosystem. + +## What is Markdown? + +Markdown is a plain text syntax for writing text documents that can be transformed to HTML. Markdown uses punctuation characters to indicate HTML elements. That punctuation then gets converted to HTML tags during a transformation or export process. + +Markdown dates back to 2004, when John Gruber published the original [Markdown syntax guide](https://daringfireball.net/projects/markdown/syntax). Gruber, along with Aaron Swartz, created Markdown with two goals: + +1. to make Markdown as easy-to-read and easy-to-write as is feasible.; and +1. to support inline HTML within Markdown-formatted text. + +Text-to-HTML filters such as [Textile](https://textile-lang.com/) define a syntax that replaces a wide range of HTML elements. Other filters, such as [reStructuredText](https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html), do not support inline HTML tags. + +Markdown, by contrast, only defines a syntax for a small subset of HTML elements. For other elements, you use the corresponding HTML tag. In other words, Markdown makes it possible to write documents without knowing HTML, but HTML is available if you need it. A Markdown document might look like the example that follows. + +```markdown +# Markdown! + +You can use Markdown to create documents for [Gatsby](https://www.gatsbyjs.org/). + +
+ +
+ Developers who love using Gatsby versus those who haven't tried it yet. +
+
+``` + +When converted to HTML, the preceding Markdown will become the markup below. + +```html +

Markdown!

+

+ You can use Markdown to create documents for + Gatsby. +

+
+ +
+ Developers who love using Gatsby versus those who haven't tried it yet. +
+
+``` + +You can use Markdown files as a content source for your Gatsby site. To do so, you'll need to install two plugins: [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem) and [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/). As with Gatsby itself, you can install both using [npm](/docs/glossary/#npm). + +```bash +npm install --save gatsby-source-filesystem gatsby-transformer-remark +``` + +The `gatsby-source-filesystem` plugin reads files from your computer. The `gatsby-transformer-remark` plugin makes the contents of your Markdown files available to GraphQL. + +You can also try a [Gatsby starter](https://www.gatsbyjs.org/starters/?c=Markdown) package that has Markdown support already included. + +## Learn more about Markdown + +- [Markdown syntax](/docs/mdx/markdown-syntax/) from the Gatsby docs +- [CommonMark](https://commonmark.org/), a proposed Markdown specification +- [Sourcing from the Filesystem](/docs/sourcing-from-the-filesystem/) from the Gatsby docs +- [Adding Markdown Pages](/docs/adding-markdown-pages/) from the Gatsby docs From db938759bed87dd9a0f9c6031d8bc644d2e6e6f1 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 26 Feb 2020 16:23:26 +0000 Subject: [PATCH 015/127] sync with monorepo gatsbyjs/gatsby@1c9671b7df1c99e61f62460a73e4a5dc07e02823 - chore(starters): add gatsby-starter-redux-storybook (#21764) I had to close my former PR because it orphaned --- docs/docs/deploying-to-aws-amplify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/deploying-to-aws-amplify.md b/docs/docs/deploying-to-aws-amplify.md index 7987c4bdf..e493b084a 100644 --- a/docs/docs/deploying-to-aws-amplify.md +++ b/docs/docs/deploying-to-aws-amplify.md @@ -25,7 +25,7 @@ AWS Amplify is a combination of client library, CLI toolchain, and a Console for 1. Accept the default build settings. Give the Amplify Console permission to deploy backend resources with your frontend with a service role. This allows the Console to detect changes to both your backend and frontend on every code commit and make updates. If you do not have a service role follow the prompts to create one, then come back to the console and pick it from the dropdown. ![Gatsby Amplify2](./images/amplify-build-settings.gif) -1. Review your changes and then choose **Save and deploy**. The Amplify Console will pull code from your repository, build changes to the backend and frontend, and deploy your build artifacts at `https://master.unique-id.amplifyapp.com`. Bonus: Screenshots of your app on different devices to find layout issues :fire: +1. Review your changes and then choose **Save and deploy**. The Amplify Console will pull code from your repository, build changes to the backend and frontend, and deploy your build artifacts at `https://master.unique-id.amplifyapp.com`. Bonus: Screenshots of your app on different devices to find layout issues 🔥 ![Gatsby Amplify2](./images/amplify-gatsby-deploy.gif) ## References: From 8cedb6e86aa9f4b088b595b089eb90d20104cd73 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 26 Feb 2020 19:13:10 +0000 Subject: [PATCH 016/127] sync with monorepo gatsbyjs/gatsby@43fe5260f7e31a763960568894bf78de51079407 - fixed broken_link of gatsby starter #21720 (#21724) * broken link * chnge_link * link footnote * rm * chore: format Co-authored-by: GatsbyJS Bot --- docs/docs/gatsby-cli.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/gatsby-cli.md b/docs/docs/gatsby-cli.md index a061269db..e56f110b9 100644 --- a/docs/docs/gatsby-cli.md +++ b/docs/docs/gatsby-cli.md @@ -33,10 +33,10 @@ gatsby new [ []] #### Arguments -| Argument | Description | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| site-name | Your Gatsby site name, which is also used to create a project directory. | -| starter-url | A Gatsby starter URL or local file path. Defaults to [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default); see the [Gatsby starters](/docs/gatsby-starters/) docs for more information. | +| Argument | Description | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| site-name | Your Gatsby site name, which is also used to create a project directory. | +| starter-url | A Gatsby starter URL or local file path. Defaults to [gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default); see the [Gatsby starters](/docs/starters/) docs for more information. | > Note: The `site-name` should only consist of letters and numbers. If you specify a `.`, `./` or a `` in the name, `gatsby new` will throw an error. From e21a36cab038cd56401e3609d9b16e5b6b533f44 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 26 Feb 2020 21:55:51 +0000 Subject: [PATCH 017/127] sync with monorepo gatsbyjs/gatsby@bfe9c0852c0299aad4e1e1821bda90d539cdc189 - docs: add new guide and example site on plugin options (#21708) * add example for plugin options and a new guide on them * add example site to guides resources * Apply suggestions from code review Co-Authored-By: LB * hopefully fix linting errors * Apply suggestions from code review Co-Authored-By: LB Co-authored-by: LB --- .../configuring-usage-with-plugin-options.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/docs/configuring-usage-with-plugin-options.md diff --git a/docs/docs/configuring-usage-with-plugin-options.md b/docs/docs/configuring-usage-with-plugin-options.md new file mode 100644 index 000000000..e71909825 --- /dev/null +++ b/docs/docs/configuring-usage-with-plugin-options.md @@ -0,0 +1,59 @@ +--- +title: Configuring Plugin Usage with Plugin Options +--- + +Plugins loaded into a Gatsby site can have options passed in to customize how a plugin operates. + +_This guide refers to creating plugins, if you are looking for general information on using options with plugins refer to ["Using a Plugin in Your Site"](/docs/using-a-plugin-in-your-site/). If you are looking for options of a specific plugin, refer to its README._ + +## Where to access plugin options + +A Gatsby plugin with options included makes those options available in the second argument of Gatsby [Node](/docs/node-apis/), [Browser](/docs/browser-apis/), and [SSR APIs](/docs/ssr-apis/). Consider the following `gatsby-config` with a plugin called `gatsby-plugin-console-log`: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [ + { + resolve: `gatsby-plugin-console-log`, + options: { optionA: true, optionB: false, message: "Hello world" }, + }, + ], +} +``` + +With the `optionA`, `optionB`, and `message` options passed into the plugin, the code for `gatsby-plugin-console-log` is able to access the values `true`, `false`, and `Hello world` by their keys. + +For example, `gatsby-plugin-console-log` can access the `message` in order to log its value to the console inside of the `onPreInit` API: + +```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js +exports.onPreInit = (_, pluginOptions) => { + console.log( + `logging: "${pluginOptions.message || `default message`}" to the console` // highlight-line + ) +} +``` + +The code above is called when `gatsby develop` or `gatsby build` is run. It takes the `message` from the `options` object in the config and logs it from `pluginOptions.message` when the `onPreInit` method is called. + +The second argument passed into the function is where the options are held. + +_Like arguments in any JavaScript function, you can use a different (more specific) name like `themeOptions` if you are building a plugin that will be used as a theme._ + +## What can be passed in as options + +Any JavaScript data type can be passed in as an option. + +The following table lists possible options values and an example plugin that makes use of them. + +| Data Type | Sample Value | Example Plugin | +| --------- | -------------------------------- | ----------------------------------------------------------------- | +| Boolean | `true` | [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) | +| String | `/src/data/` | [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) | +| Array | `["/about-us/", "/projects/*"]` | [`gatsby-plugin-offline`](/packages/gatsby-plugin-offline/) | +| Object | `{ default: "./src/layout.js" }` | [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/) | + +**Note**: Themes (which are a type of plugin) are able to receive options from a site's `gatsby-config` to be used in its `gatsby-config` in order to allow themes to be composed together. This is done by exporting the `gatsby-config` as a function instead of an object. You can see an example of this in the [`gatsby-theme-blog`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality. + +## Additional resources + +- [Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options) From b22784b16b5c94a8a7118dc5ddf8896ac6a1f43f Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 27 Feb 2020 12:31:16 +0000 Subject: [PATCH 018/127] sync with monorepo gatsbyjs/gatsby@fc652459b3221455f35246a4431a666edd457cd3 - fix(docs): 404 on static site generator (#21784) --- docs/docs/glossary/static-site-generator.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/glossary/static-site-generator.md b/docs/docs/glossary/static-site-generator.md index a9ec3813a..5f1a3c28a 100644 --- a/docs/docs/glossary/static-site-generator.md +++ b/docs/docs/glossary/static-site-generator.md @@ -13,9 +13,9 @@ Static site generators are an alternative to database-driven content management Static site generators, on the other hand, generate HTML pages during a [build](/docs/glossary/#build) process. Gatsby, for example, loads JSON from [GraphQL](/docs/glossary/graphql), and merges that data with components to create HTML pages. These generated pages are then deployed to a web server. When the server receives a request, it responds with rendered HTML. Static pages eliminate the latency that databases introduce. -> Note: It's also possible to use Gatsby [without GraphQL](/using-gatsby-without-graphql/), using the `createPages` API. +> Note: It's also possible to use Gatsby [without GraphQL](/docs/using-gatsby-without-graphql/), using the `createPages` API. -You can also use static site generators to create [JAMStack](/docs/glossary/jamstack.md) sites. JAMStack is a modern web site architecture that uses JavaScript, content APIs, and markup. Gatsby, for example, can use the [WordPress REST API](/sourcing-from-wordpress/) as a data source. +You can also use static site generators to create [JAMStack](/docs/glossary/#jamstack) sites. JAMStack is a modern web site architecture that uses JavaScript, content APIs, and markup. Gatsby, for example, can use the [WordPress REST API](/docs/sourcing-from-wordpress/) as a data source. ### Advantages of static site generators @@ -26,10 +26,10 @@ Static site generators **reduce site complexity**. That, in turn, improves speed - You can use version control software to manage and track changes to your content. - Because your site is static, you can even forgo web servers and load balancers altogether. Instead, you can host your site with a content delivery network that scales with your site's traffic. -There are dozens of static site generators available, created with a range of programming languages. Gatsby is [JavaScript](/glossary#javascript) at its core, and is built with [React](/glossary/react), GraphQL, and [Node.js](/glossary/node/). See how Gatsby [compares to WordPress and Drupal](/features/cms/gatsby-vs-wordpress-vs-drupal) or to popular [static site generators](/features/jamstack/). +There are dozens of static site generators available, created with a range of programming languages. Gatsby is [JavaScript](/docs/glossary/#javascript) at its core, and is built with [React](/docs/glossary/#react), GraphQL, and [Node.js](/docs/glossary/#nodejs). See how Gatsby [compares to WordPress and Drupal](/features/cms/gatsby-vs-wordpress-vs-drupal) or to popular [static site generators](/features/jamstack/). ### Learn more -- [JAMStack](/docs/glossary/jamstack.md) architecture from the Gatsby docs -- [Sourcing Content and Data](/content-and-data/) for Gatsby +- [JAMStack](/docs/glossary/#jamstack) architecture from the Gatsby docs +- [Sourcing Content and Data](/docs/content-and-data/) for Gatsby - [Adding Markdown Pages](/docs/adding-markdown-pages/) from the Gatsby docs From 2d8ea8c5e70ad27f64868eefa26ece1ddd3e0d82 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 27 Feb 2020 16:58:38 +0000 Subject: [PATCH 019/127] sync with monorepo gatsbyjs/gatsby@a3cf501e9b75558909c06f7259830251dea1a5d3 - chore(doc): Add Using-mdx example to example sites (#21735) * initialise using mdx example * Setup querys for MDX and create a post.md * Update MDX to redender from page directory * Update the chart-info with more graph examples * Update README.md with section on react chart * fix typo in README * update doc with review and delete unneeded files * Link MDX example to mdx/importing-and-using-components for discoverability --- docs/docs/mdx/importing-and-using-components.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index aa39db9c3..b70a3f9d3 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -62,3 +62,7 @@ The Chart is also available since it was passed into the MDXProvider: ``` Because the `` and `` components were passed into the provider, they are available for use in all MDX documents. + +### Additional resources + +- Follow this detailed [example on using MDX](/examples/using-MDX) to import and render components. From 7c35b91148c09057680f4032e5eb298f417fda4d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 12:14:44 +0000 Subject: [PATCH 020/127] sync with monorepo gatsbyjs/gatsby@fba5899de8600f1e9e461d150e302f0b20995987 - chore(doc):add or fix syntax highlight language (#21810) --- docs/docs/creating-a-local-plugin.md | 2 +- docs/docs/gatsby-project-structure.md | 2 +- docs/docs/graphql-concepts.md | 2 +- docs/docs/loading-plugins-from-your-local-plugins-folder.md | 2 +- docs/docs/recipes/pages-layouts.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/creating-a-local-plugin.md b/docs/docs/creating-a-local-plugin.md index 1b2adffcf..c5f87da64 100644 --- a/docs/docs/creating-a-local-plugin.md +++ b/docs/docs/creating-a-local-plugin.md @@ -8,7 +8,7 @@ If a plugin is only relevant to your specific use-case, or if you’re developin Place the code in the `plugins` folder in the root of your project like this: -``` +```text /my-gatsby-site └── gatsby-config.js └── /src diff --git a/docs/docs/gatsby-project-structure.md b/docs/docs/gatsby-project-structure.md index 3d32c0583..695115600 100644 --- a/docs/docs/gatsby-project-structure.md +++ b/docs/docs/gatsby-project-structure.md @@ -4,7 +4,7 @@ title: Gatsby Project Structure Inside a Gatsby project, you may see some or all of the following folders and files: -``` +```text / |-- /.cache |-- /plugins diff --git a/docs/docs/graphql-concepts.md b/docs/docs/graphql-concepts.md index 0da0f774e..f5798f278 100644 --- a/docs/docs/graphql-concepts.md +++ b/docs/docs/graphql-concepts.md @@ -152,7 +152,7 @@ If you give Gatsby data that looks like this: Gatsby will create a schema that looks something like this: -``` +```text title: String ``` 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 ac2b3966e..2768dc950 100644 --- a/docs/docs/loading-plugins-from-your-local-plugins-folder.md +++ b/docs/docs/loading-plugins-from-your-local-plugins-folder.md @@ -6,7 +6,7 @@ Gatsby can load plugins from your website's local plugins folder, which is a fol Consider this example project structure which includes a local plugin called `gatsby-local-plugin`: -``` +```text /my-gatsby-site └── /src └── /pages diff --git a/docs/docs/recipes/pages-layouts.md b/docs/docs/recipes/pages-layouts.md index 3bb7b7256..cf49f42ae 100644 --- a/docs/docs/recipes/pages-layouts.md +++ b/docs/docs/recipes/pages-layouts.md @@ -9,7 +9,7 @@ Add pages to your Gatsby site, and use layouts to manage common page elements. Inside a Gatsby project, you may see some or all of the following folders and files: -``` +```text |-- /.cache |-- /plugins |-- /public From 654329015a9279347aeb65e5d37512f613567600 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 14:34:14 +0000 Subject: [PATCH 021/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@2435fb861e8651cf696593b7b4a8980f00a9c430=20-=20chore(docs):?= =?UTF-8?q?=20Use=20parser=3Dmdx=20for=20formatting=20docs=20using=20prett?= =?UTF-8?q?i=E2=80=A6=20(#21671)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs-and-website-components.md | 16 +- docs/docs/caching.md | 2 + docs/docs/cheat-sheet.md | 722 +++++++++++------- docs/docs/gatsby-image.md | 18 +- docs/docs/glossary.md | 4 +- docs/docs/graphql-reference.md | 183 ++++- docs/tutorial/part-five/index.md | 2 +- docs/tutorial/part-one/index.md | 4 +- 8 files changed, 636 insertions(+), 315 deletions(-) diff --git a/docs/contributing/docs-and-website-components.md b/docs/contributing/docs-and-website-components.md index 93c295345..f59ba9191 100644 --- a/docs/contributing/docs-and-website-components.md +++ b/docs/contributing/docs-and-website-components.md @@ -188,14 +188,14 @@ The glossary defines key vocabulary... Rendered, it looks like this: --- diff --git a/docs/docs/caching.md b/docs/docs/caching.md index 6e49e14b3..36d3e9be8 100644 --- a/docs/docs/caching.md +++ b/docs/docs/caching.md @@ -51,7 +51,9 @@ When deploying with Now, follow the instructions in the [Now documentation](http --- + 1 You can use 'no-cache' instead of 'max-age=0, must-revalidate'. Despite what the name might imply, 'no-cache' permits a cache to serve cached content as long as it validates the cache freshness first. [2][3] In either case, clients have to make a round trip to the origin server on each request. However, if you are correctly utilizing ETags or Last-Modified validation you will avoid downloading assets when the cached copy is still valid (e.g. the file hasn't changed on the origin server since it was cached). + [2]: https://tools.ietf.org/html/rfc7234#section-5.2.2.1 [3]: https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#no-cache_and_no-store diff --git a/docs/docs/cheat-sheet.md b/docs/docs/cheat-sheet.md index 91dad8bd9..edf2c654a 100644 --- a/docs/docs/cheat-sheet.md +++ b/docs/docs/cheat-sheet.md @@ -7,277 +7,457 @@ The Gatsby team has created a resource that you might find useful when building Get the PDF: gatsby-cheat-sheet.pdf
-

Page 1

- - Cheat Sheet - page 1 +

Page 1

+ + Cheat Sheet - page 1 + +

Page 2

+ + Cheat Sheet - page 2 + +
+
+

Gatsby Cheat Sheet contents

+

+ v1.0 for Gatsby 2.x + + Latest version -

Page 2

- - Cheat Sheet - page 2 +

+

Top Docs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

Gatsby Docs

+ 		+

+ gatsby.dev/docs +

+
+

Gatsby on GitHub

+ 		+

+ + github.com/gatsbyjs/gatsby + +

+
+

Gatsby Tutorial

+ 		+

+ gatsby.dev/tutorial +

+
+

+ Quick Start +
+ (for intermediate and advanced developers) +

+ 		+

+ gatsby.dev/quick-start +

+
+

Gatsby Starters

+ 		+

+ gatsby.dev/starters +

+
+

Quick Reference Guide

+ 		+

+ gatsby.dev/recipes +

+
+

Adding Images

+ 		+

+ gatsby.dev/image +

+
+

Gatsby Node APIs

+ 		+

+ gatsby.dev/api +

+
+

Querying with GraphQL

+ 		+

+ gatsby.dev/graphql +

+
+

Deploying and Hosting

+ 		+

+ gatsby.dev/deploy +

+
+

Using Gatsby Link

+ 		+

+ gatsby.dev/link +

+
+

Static Query

+ 		+

+ + gatsby.dev/static-query + +

+
+

How to Contribute

+ 		+

+ gatsby.dev/contribute +

+
+

+ gatsbyjs.org +

+

+ twitter.com/gatsbyjs +

+

Gatsby CLI Commands

+

+ First, install the global executable: +
+ npm install -g gatsby-cli +

+

+ Run gatsby --help for a list of commands and options. +

+

+ + gatsby new my-site-name + +

+

+ Create a new local Gatsby site using the default starter (see “Quick Start + Commands” in this cheat sheet on how to use other starters). +

+

+ gatsby develop +

+

Start the Gatsby development server.

+ + + + + + + + + + + + + + + + + + + +
+

+ -H, --host +

+ 		+

+ Set host. Defaults to localhost +

+
+

+ -p, --port +

+ 		+

+ Set port. Defaults to env.PORT or 8000 +

+
+

+ -o, --open +

+ 		+

Open the site in your (default) browser for you

+
+

+ -S, --https +

+ 		+

Use HTTPS

+
+

+ gatsby build +

+

+ Compile your application and make it ready for deployment. +
+

+ + + + + + + + + + + + + + + +
+

+ --prefix-paths +

+ 		+

+ Build site with link paths prefixed +
+ (set pathPrefix in your config) +

+
+

+ --no-uglify +

+ 		+

+ Build site without uglifying JS bundles +
+ (for debugging) +

+
+

+ --open-tracing-config-file +

+ 		+

+ Tracer configuration file (OpenTracing compatible). See{" "} + gatsby.dev/tracing +

+
+

+ gatsby serve +

+

Serve the production build for testing.

+ + + + + + + + + + + + + + + + + + + +
+

+ -H, --host +

+ 		+

+ Set host. Defaults to localhost +

+
+

+ -p, --port +

+ 		+

+ Set port. Defaults to 9000 +

+
+

+ -o, --open +

+ 		+

Open the site in your (default) browser for you

+
+

+ --prefix-paths +

+ 		+

+ Serve site with link paths prefixed (if built with{" "} + pathPrefix in your gatsby-config.js) +

+
+

+ gatsby info +

+

+ Get helpful environment information which will be required when reporting a + bug at{" "} + + github.com/gatsbyjs/gatsby/issues - - -

-

Gatsby Cheat Sheet contents

-

v1.0 for Gatsby 2.x - Latest version -

-

Top Docs

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Gatsby Docs

- 		-

gatsby.dev/docs

-
-

Gatsby on GitHub

- 		-

github.com/gatsbyjs/gatsby

-
-

Gatsby Tutorial

- 		-

gatsby.dev/tutorial

-
-

Quick Start
(for intermediate and advanced developers)

- 		-

gatsby.dev/quick-start

-
-

Gatsby Starters

- 		-

gatsby.dev/starters

-
-

Quick Reference Guide

- 		-

gatsby.dev/recipes

-
-

Adding Images

- 		-

gatsby.dev/image

-
-

Gatsby Node APIs

- 		-

gatsby.dev/api

-
-

Querying with GraphQL

- 		-

gatsby.dev/graphql

-
-

Deploying and Hosting

- 		-

gatsby.dev/deploy

-
-

Using Gatsby Link

- 		-

gatsby.dev/link

-
-

Static Query

- 		-

gatsby.dev/static-query

-
-

How to Contribute

- 		-

gatsby.dev/contribute

-
-

gatsbyjs.org

-

twitter.com/gatsbyjs

-

Gatsby CLI Commands

-

First, install the global executable: -
- npm install -g gatsby-cli

-

Run gatsby --help for a list of commands and options.

-

gatsby new my-site-name

-

Create a new local Gatsby site using the default starter (see “Quick Start Commands” in this cheat sheet on how to use other starters).

-

gatsby develop

-

Start the Gatsby development server.

- - - - - - - - - - - - - - - - - - - -
-

-H, --host

- 		-

Set host. Defaults to localhost

-
-

-p, --port

- 		-

Set port. Defaults to env.PORT or 8000

-
-

-o, --open

- 		-

Open the site in your (default) browser for you

-
-

-S, --https

- 		-

Use HTTPS

-
-

gatsby build

-

Compile your application and make it ready for deployment.

- - - - - - - - - - - - - - - -
-

--prefix-paths

- 		-

Build site with link paths prefixed
(set pathPrefix in your config)

-
-

--no-uglify

- 		-

Build site without uglifying JS bundles
(for debugging)

-
-

--open-tracing-config-file

- 		-

Tracer configuration file (OpenTracing compatible). See gatsby.dev/tracing

-
-

gatsby serve

-

Serve the production build for testing.

- - - - - - - - - - - - - - - - - - - -
-

-H, --host

- 		-

Set host. Defaults to localhost

-
-

-p, --port

- 		-

Set port. Defaults to 9000

-
-

-o, --open

- 		-

Open the site in your (default) browser for you

-
-

--prefix-paths

- 		-

Serve site with link paths prefixed (if built with pathPrefix in your gatsby-config.js)

-
-

gatsby info

-

Get helpful environment information which will be required when reporting a bug at github.com/gatsbyjs/gatsby/issues.

- - - - - - - -
-

-C, --clipboard

- 		-

Automagically copy environment information to clipboard

-
-

gatsby clean

-

Wipe out Gatsby’s .cache and public directories.

-

T-Shirts, Hats, Hoodies, and more!

-

Sign up for the Gatsby Newsletter and get 30% off your Gatsby Store purchase! (gatsby.dev/store)

-

Sign up at gatsby.dev/discount

-

Quick Start Commands

-

Create a new Gatsby site using the “Blog” starter:
- gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

-

Navigate into your new site’s directory and start it up:
- cd my-blog-starter/
- gatsby develop

-

Your site is now running at http://localhost:8000!

-

You’ll also see a second link: http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about it at gatsby.dev/tutorial

-

For more Gatsby starters, visit gatsby.dev/starters.

-

Helpful File Definitions

-

Each of these files should live at the root of your Gatsby project folder. See gatsby.dev/projects

-

gatsby-config.js — configure options for a Gatsby site, with metadata for project title, description, plugins, etc.

-

gatsby-node.js — implement Gatsby’s Node.js APIs to customize and extend default settings affecting the build process

-

gatsby-browser.js — customize and extend default settings affecting the browser, using Gatsby’s browser APIs

-

gatsby-ssr.js — use Gatsby’s server-side rendering APIs to customize default settings affecting server-side rendering

+ . +

+ + + + + + + +
+

+ -C, --clipboard +

+ 		+

Automagically copy environment information to clipboard

+
+

gatsby clean

+

+ Wipe out Gatsby’s .cache and public directories. +

+

T-Shirts, Hats, Hoodies, and more!

+

+ Sign up for the Gatsby Newsletter and get 30% off your + Gatsby Store purchase! ( + gatsby.dev/store) +

+

+ Sign up at gatsby.dev/discount +

+

Quick Start Commands

+

+ Create a new Gatsby site using the “Blog” starter: +
+ + gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog + +

+

+ Navigate into your new site’s directory and start it up: +
+ + cd my-blog-starter/ +
+ gatsby develop + +

+

+ Your site is now running at http://localhost:8000! +

+

+ {/* prettier-ignore */} + You’ll also see a second link: http://localhost:8000/___graphql. + This is a tool you can use to experiment with querying your data. Learn more + about it at gatsby.dev/tutorial +

+

+ For more Gatsby starters, visit{" "} + gatsby.dev/starters. +

+

Helpful File Definitions

+

+ Each of these files should live at the root of your Gatsby project folder. + See gatsby.dev/projects +

+

+ gatsby-config.js — configure options for a Gatsby site, with + metadata for project title, description, plugins, etc. +

+

+ gatsby-node.js — implement Gatsby’s Node.js APIs to customize + and extend default settings affecting the build process +

+

+ gatsby-browser.js — customize and extend default settings + affecting the browser, using Gatsby’s browser APIs +

+

+ gatsby-ssr.js — use Gatsby’s server-side rendering APIs to + customize default settings affecting server-side rendering +

diff --git a/docs/docs/gatsby-image.md b/docs/docs/gatsby-image.md index bcbaf43c6..98a91b9c0 100644 --- a/docs/docs/gatsby-image.md +++ b/docs/docs/gatsby-image.md @@ -263,10 +263,11 @@ fixed( ```
- Jay Gatsby holding wine class in normal color and duotone. -
- Duotone | Before - After -
+ Jay Gatsby holding wine class in normal color and duotone. +
Duotone | Before - After
And an example of using the `grayscale` option with a fixed image: @@ -278,10 +279,11 @@ fixed( ```
- Jay Gatsby holding wine class in normal color and duotone. -
- Grayscale | Before - After -
+ Jay Gatsby holding wine class in normal color and duotone. +
Grayscale | Before - After
Read more in the [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp) README. diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index f1f34aaf0..3e5241275 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -6,8 +6,8 @@ disableTableOfContents: true 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. ## A diff --git a/docs/docs/graphql-reference.md b/docs/docs/graphql-reference.md index d2811e817..1e686d41c 100644 --- a/docs/docs/graphql-reference.md +++ b/docs/docs/graphql-reference.md @@ -14,7 +14,13 @@ For more information, read about [why Gatsby uses GraphQL](/docs/why-gatsby-uses Start with the basics, pulling up the site `title` from your `gatsby-config.js`'s `siteMetadata`. Here the query is on the left and the results are on the right. - + 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,31 +28,60 @@ 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. If you're using Gatsby version `2.2.0` or later, you can remove `edges` and `node` from your query and replace it with `nodes`. The query will still work and the returned object will reflect the `nodes` structure. - + ## Limit 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. @@ -58,11 +93,23 @@ 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 @@ -80,7 +127,13 @@ _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. @@ -88,17 +141,35 @@ 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 @@ -106,31 +177,61 @@ 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 @@ -140,7 +241,13 @@ 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 @@ -148,7 +255,13 @@ 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 @@ -156,13 +269,25 @@ 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`. @@ -172,13 +297,25 @@ 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? diff --git a/docs/tutorial/part-five/index.md b/docs/tutorial/part-five/index.md index fad8ced4a..b09690e34 100644 --- a/docs/tutorial/part-five/index.md +++ b/docs/tutorial/part-five/index.md @@ -18,7 +18,7 @@ You can access it when your site's development server is running—normally at `http://localhost:8000/___graphql`. diff --git a/docs/tutorial/part-one/index.md b/docs/tutorial/part-one/index.md index 6f57915c1..96a065bde 100644 --- a/docs/tutorial/part-one/index.md +++ b/docs/tutorial/part-one/index.md @@ -45,7 +45,7 @@ Open the file at `src/pages/index.js`. The code in this file creates a component 1. Change the “Hello World!” text to “Hello Gatsby!” and save the file. If your windows are side-by-side, you can see that your code and content changes are reflected almost instantly in the browser after you save the file. @@ -327,7 +327,7 @@ export default () => ( After you save the file, you should see the contact page and be able to follow the link to the homepage. From a8c20bc41d40128cc0a64ee7dff5a0c0c99ff9c2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 15:48:31 +0000 Subject: [PATCH 022/127] sync with monorepo gatsbyjs/gatsby@16ba1b93329a0b073f3a45badb0024008c1804e6 - docs/glossary: Adds MDX entry. (#21770) * docs/glossary: Adds MDX entry. Also updates glossary.md, doc-links.yaml with links to MDX article. * Capitalize MDX * Prefer you as the pronoun Co-authored-by: Aisha Blake --- docs/docs/glossary.md | 2 +- docs/docs/glossary/mdx.md | 71 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 docs/docs/glossary/mdx.md diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 3e5241275..7881591b4 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -206,7 +206,7 @@ Linting is the process of running a program that will analyze code for potential ## M -### MDX +### [MDX](/docs/glossary/mdx/) Extends [Markdown](#markdown) to support [React](#react) [components](#component) within your content. diff --git a/docs/docs/glossary/mdx.md b/docs/docs/glossary/mdx.md new file mode 100644 index 000000000..e436b1ac8 --- /dev/null +++ b/docs/docs/glossary/mdx.md @@ -0,0 +1,71 @@ +--- +title: MDX +disableTableOfContents: true +--- + +Learn what MDX is, and how you can use it when creating content for your Gatsby site. + +## What is MDX? + +[MDX](/docs/glossary/#mdx) is an extension to [Markdown](/docs/glossary/markdown/) that lets you include [JSX](/docs/glossary/#jsx) in Markdown documents. MDX makes it possible to include React components in your Gatsby blog posts and pages. + +Markdown defines a plain text syntax for HTML elements such as `h1`, `strong`, and `a`, but still supports inline HTML. An example Markdown document follows. + +```markdown +# Hello world! + +You can use Markdown to create documents for [Gatsby](https://www.gatsbyjs.org/). + +
+ +
MDX adoption has increased 120% since last year.
+
+``` + +MDX takes this one step further, and makes it possible to use JSX in your Markdown documents. Try making the `figure` element into a `Figure` component. + +```jsx +export const Figure = props => { + return ( +
+ +
{props.caption}
+
+ ) +} +``` + +Now you can import this component into your Markdown document. + +```markdown +import { Figure } from './components/Figure'; + +# Hello world! + +You can use Markdown to create documents for [Gatsby](https://www.gatsbyjs.org/). + +
+``` + +If you're creating a Gatsby site from scratch, the [gatsby-starter-mdx-basic](https://github.com/ChristopherBiscardi/gatsby-starter-mdx-basic) is the fastest way to add MDX support. Use the Gatsby [CLI](/docs/glossary/#cli) to create a new project with this starter as a base. + +```shell +gatsby new my-mdx-starter https://github.com/ChristopherBiscardi/gatsby-starter-mdx-basic +``` + +To use MDX with an existing Gatsby site, add the [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/?=gatsby-plugin-mdx) plugin. As with Gatsby itself, you can install it using [npm](/docs/glossary/#npm). You'll also need to install MDX itself, and the React implementation of MDX. + +```shell +npm install --save gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react +``` + +Then add `gatsby-plugin-mdx` to your plugins list in `gatsby-config.js`, and set the [configuration options](/packages/gatsby-plugin-mdx/?=gatsby-plugin-mdx#configuration) you prefer. + +MDX enhances Markdown's capabilities so that you can use React components anywhere in your Gatsby-powered site. + +### Learn more about MDX + +- [MDX](https://mdxjs.com/) official site +- [What is MDX](https://www.youtube.com/watch?v=d2sQiI5NFAM) (video) +- [Adding Components to Markdown with MDX](/docs/mdx/) from the Gatsby docs +- [Introducing JSX](https://reactjs.org/docs/introducing-jsx.html) from the React documentation From 57caae162defc04167c22c8dab025e9ee9722691 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 17:40:45 +0000 Subject: [PATCH 023/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@98db81d6e2219df7fd212fe225e9228d046f2641=20-=20fix(www):=20re?= =?UTF-8?q?move=20prettier=20ignore=20comment=20causing=20MDX=20parsing=20?= =?UTF-8?q?e=E2=80=A6=20(#21832)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/caching.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docs/caching.md b/docs/docs/caching.md index 36d3e9be8..7f2d7b4cb 100644 --- a/docs/docs/caching.md +++ b/docs/docs/caching.md @@ -51,9 +51,12 @@ When deploying with Now, follow the instructions in the [Now documentation](http --- - -1 You can use 'no-cache' instead of 'max-age=0, must-revalidate'. Despite what the name might imply, 'no-cache' permits a cache to serve cached content as long as it validates the cache freshness first. [2][3] In either case, clients have to make a round trip to the origin server on each request. However, if you are correctly utilizing ETags or Last-Modified validation you will avoid downloading assets when the cached copy is still valid (e.g. the file hasn't changed on the origin server since it was cached). - + + 1 + You can use 'no-cache' instead of 'max-age=0, must-revalidate'. Despite what the name might imply, 'no-cache' permits a cache to serve cached content as long as it validates the cache freshness first. + + [2][3]{" "} + In either case, clients have to make a round trip to the origin server on each request. However, if you are correctly utilizing ETags or Last-Modified validation you will avoid downloading assets when the cached copy is still valid (e.g. the file hasn't changed on the origin server since it was cached). [2]: https://tools.ietf.org/html/rfc7234#section-5.2.2.1 [3]: https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching#no-cache_and_no-store From 1ff0759de4659fb63756c68b976013d0dcc7b602 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 18:33:07 +0000 Subject: [PATCH 024/127] sync with monorepo gatsbyjs/gatsby@12324a84b3555ea370d1e92ee9fadf4237c1e962 - chore(www) reorganize contributing section (#21806) * reorganize contributing section * docs and blog components * Update www/redirects.yaml Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: GatsbyJS Bot --- ...contributions.md => blog-contributions.md} | 33 +++---------------- docs/contributing/code-contributions.md | 2 +- ...ponents.md => docs-and-blog-components.md} | 24 +++----------- docs/contributing/docs-contributions.md | 2 +- .../how-to-open-a-pull-request.md | 2 +- docs/contributing/managing-pull-requests.md | 2 +- .../setting-up-your-local-dev-environment.md | 2 +- docs/contributing/website-contributions.md | 31 +++++++++++++++++ 8 files changed, 44 insertions(+), 54 deletions(-) rename docs/contributing/{blog-and-website-contributions.md => blog-contributions.md} (70%) rename docs/contributing/{docs-and-website-components.md => docs-and-blog-components.md} (84%) create mode 100644 docs/contributing/website-contributions.md diff --git a/docs/contributing/blog-and-website-contributions.md b/docs/contributing/blog-contributions.md similarity index 70% rename from docs/contributing/blog-and-website-contributions.md rename to docs/contributing/blog-contributions.md index 74c43aabf..030b8c379 100644 --- a/docs/contributing/blog-and-website-contributions.md +++ b/docs/contributing/blog-contributions.md @@ -1,21 +1,10 @@ --- -title: Blog & Website Contributions +title: Blog Contributions --- -We wholeheartedly welcome contributions to the Gatsby blog and website! +If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF) -Here are some things to keep in mind when deciding where to contribute to Gatsby: - -- [Blog posts](#contributing-to-the-blog) work best for case studies and time-sensitive storytelling (see the [blog post format](#blog-post-format)). -- [Docs](/contributing/docs-contributions/) are continually relevant and discoverable learning materials that go beyond any one case study or situation. -- [Website changes](#making-changes-to-the-website) that improve either of these are always welcome! - -## Contributing to the blog - -If you'd like to contribute a post to the Gatsby blog, please review the process and guidelines outlined below and submit your -idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF) - -### Blog proposal submission process +## Blog proposal submission process 1. Complete and submit the [Gatsby blog proposal form](https://airtable.com/shr3449954866i3iF). 2. A Gatsby team member will review your proposal and let you know if the proposal has been accepted within the next week or so. @@ -24,7 +13,7 @@ idea for the post to our [Gatsby blog proposal form](https://airtable.com/shr344 If you have any questions about the process or your submission, please email [marketing@gatsbyjs.com](mailto:marketing@gatsbyjs.com). -### Content guidelines for submitting a blog post proposal +## Content guidelines for submitting a blog post proposal As a Gatsby community member, you have unique insight into the ins and outs of learning Gatsby, building with Gatsby, and contributing to Gatsby’s open source community. Contributing to the Gatsby blog is a great way to share your experiences and insights. Here are some guidelines for what kind of content is and isn’t a good fit for the Gatsby blog. @@ -47,17 +36,3 @@ Things we’d like to avoid on the Gatsby blog: - **Content that doesn’t seem to have a clear benefit for Gatsby users and/or the Gatsby community.** For example, if you’re writing about a use-case or integration that’s extremely niche or unique to specific conditions that are really uncommon outside of your organization, the Gatsby blog might not be the best place for your content. Likewise, if your blog post doesn’t seem to have any direct relationship with Gatsby (or an interesting indirect relationship with Gatsby), then it may be more appropriate for a personal blog or another community blog. **Please note** that these are guidelines, not rules. If you think your blog post belongs on the Gatsby blog, we absolutely encourage you to submit it. While we reserve the right to decide what is and isn’t appropriate for the Gatsby blog, we also value and encourage your creativity and your contributions. - -## Making changes to the website - -If you want to make changes, improvements, or add new functionality to the website, you don't have to set up the full Gatsby repo to contribute. You can spin up your own instance of the Gatsby website with these steps: - -- Clone [the Gatsby repo](https://github.com/gatsbyjs/gatsby/) and navigate to `/www` -- Run `yarn` to install all of the website's dependencies. -- Run `npm run develop` to preview the site at `http://localhost:8000/`. - -> Note: If you are experiencing issues on a Linux machine, run `sudo apt install libvips-dev`, to install a native dependency. You can also reference [Gatsby guide on Linux](/docs/gatsby-on-linux/) for other Linux-specific requirements. - -Now you can make and preview your changes before raising a pull request! - -For full repo setup instructions, visit the [code contributions](/contributing/code-contributions/) page. diff --git a/docs/contributing/code-contributions.md b/docs/contributing/code-contributions.md index 952cb2de2..2507da2c6 100644 --- a/docs/contributing/code-contributions.md +++ b/docs/contributing/code-contributions.md @@ -21,7 +21,7 @@ To start setting up the Gatsby repo on your machine using git, Yarn and Gatsby-C Alternatively, you can skip the local setup and [use an online dev environment](/contributing/using-an-online-dev-environment/). -To contribute to the blog or Gatsbyjs.org website, check out the setup steps on the [blog and website contributions](/contributing/blog-and-website-contributions/) page. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/). +To contribute to the blog, check out the setup steps on the [blog contributions](/contributing/blog-contributions/) page. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/). To contribute to the website, see the [website contributions](/contributing/website-contributions/) page. ## Creating your own plugins and loaders diff --git a/docs/contributing/docs-and-website-components.md b/docs/contributing/docs-and-blog-components.md similarity index 84% rename from docs/contributing/docs-and-website-components.md rename to docs/contributing/docs-and-blog-components.md index f59ba9191..39e4a501e 100644 --- a/docs/contributing/docs-and-website-components.md +++ b/docs/contributing/docs-and-blog-components.md @@ -1,13 +1,13 @@ --- -title: Docs and Website Components +title: Docs & Blog Components tableOfContentsDepth: 2 --- The Gatsbyjs.org site has a handful of components that have been developed to facilitate writing new content for the blog and the docs. There are also components that help organize and lay out content in various pages across the website. -This guide documents what components are available and explains how to use them. You can also refer to the [code for this page on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/docs-and-website-components.md) to see to how each component can be used, because they are all embedded here! +This guide documents what components are available and explains how to use them. You can also refer to the [code for this page on GitHub](https://github.com/gatsbyjs/gatsby/blob/master/docs/contributing/docs-and-blog-components.md) to see to how each component can be used, because they are all embedded here! -Information about authoring in Markdown and styling components on the site is also listed. +Information about authoring in Markdown on the site is also listed. ## Globally available components @@ -163,7 +163,7 @@ The Horizontal Nav List component takes two props: - `slug` - which is provided in the props of the page by default - `items` - an array of strings for items to render and wrap with a `` to subheadings -The docs on Gatsbyjs.org use the [gatsby-remark-autolink-headers](/packages/gatsby-remark-autolink-headers/) plugin to automatically apply hover links to heading tags across docs pages. Because it automatically creates links to subheadings on pages like the glossary, the Horizontal Nav List can supply matching links (like `"guide-list"` which would align with the automatically created link at `/docs/docs-and-website-components#guide-list`). +The docs on Gatsbyjs.org use the [gatsby-remark-autolink-headers](/packages/gatsby-remark-autolink-headers/) plugin to automatically apply hover links to heading tags across docs pages. Because it automatically creates links to subheadings on pages like the glossary, the Horizontal Nav List can supply matching links (like `"guide-list"` which would align with the automatically created link at `/docs/docs-and-blog-components#guide-list`). ```markdown @@ -271,19 +271,3 @@ plugins: [ ``` Line numbers and line highlighting can be added to code blocks as well, and is explained in detail in the [`gatsby-remark-prismjs` README](/packages/gatsby-remark-prismjs/?=remark#optional-add-line-highlighting-styles). - -## Styling components on Gatsbyjs.org with Theme-UI - -Styles on the site are applied using [Theme-UI](https://theme-ui.com/), which allows for theming across the site based on design tokens (also called variables). - -### Design tokens - -Design tokens are used to consolidate the number of colors and style attributes that are applied to components throughout the site. By limiting the styles that can be applied, the site stays consistent with the guidelines for color, typography, spacing, etc. - -Tables listing design tokens that are used on the site can be found in the [design guidelines](/guidelines/design-tokens/). - -### The `sx` prop - -The [`sx` prop](https://theme-ui.com/sx-prop) from Theme-UI allows you to access theme values to style elements and components, it should be used wherever possible. The prop is "enabled" by adding `theme-ui`'s [JSX pragma](https://theme-ui.com/jsx-pragma) at the top of a `js` file. - -It is still okay to directly import tokens, e.g. `mediaQueries` or `colors` directly from [`www/src/gatsby-plugin-theme-ui`](https://github.com/gatsbyjs/gatsby/blob/master/www/src/gatsby-plugin-theme-ui/index.js) if it helps your specific use case — for example when global CSS is required, when passing theme values to other libraries or plugins, when authoring complex responsive styles, etc. diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md index 6de981945..e80712a27 100644 --- a/docs/contributing/docs-contributions.md +++ b/docs/contributing/docs-contributions.md @@ -4,7 +4,7 @@ title: Docs Contributions Gatsby, unsurprisingly, uses Gatsby for its documentation website. Thank you in advance and cheers for contributing to Gatsby documentation! As of February 2019, over 800 people have contributed. It's people like you that make this community great! -> _When deciding where to contribute to Gatsby (docs or [blog](/contributing/blog-and-website-contributions/)?), check out the [docs templates](/contributing/docs-templates/) page._ +> _When deciding where to contribute to Gatsby (docs or [blog](/contributing/blog-contributions/)?), check out the [docs templates](/contributing/docs-templates/) page._ ## Top priorities diff --git a/docs/contributing/how-to-open-a-pull-request.md b/docs/contributing/how-to-open-a-pull-request.md index 8d3ff7649..a4f4a2443 100644 --- a/docs/contributing/how-to-open-a-pull-request.md +++ b/docs/contributing/how-to-open-a-pull-request.md @@ -89,7 +89,7 @@ There are specific pages about contributing to various parts of the Gatsby ecosy ### Blog posts -For the Gatsby blog, it's necessary to run your content idea by the Gatsby team before submitting it. For more information, refer to the page on [blog and website contributions](/contributing/blog-and-website-contributions/), including how to propose an idea and setting up the blog to run locally. +For the Gatsby blog, it's necessary to run your content idea by the Gatsby team before submitting it. For more information, refer to the page on [blog contributions](/contributing/blog-contributions/), including how to propose an idea and setting up the blog to run locally. ## Follow up with reviews and suggestions diff --git a/docs/contributing/managing-pull-requests.md b/docs/contributing/managing-pull-requests.md index c44b00f9e..035daa4ea 100644 --- a/docs/contributing/managing-pull-requests.md +++ b/docs/contributing/managing-pull-requests.md @@ -65,7 +65,7 @@ For PRs that add a site or a starter to the showcase, we ought to check: For PRs that add a blog post, we ought to check: -- Approval – has the [blog post been approved](/contributing/blog-and-website-contributions/) by marketing or another Gatsby internal team? +- Approval – has the [blog post been approved](/contributing/blog-contributions/) by marketing or another Gatsby internal team? - Correctness — whether the added documentation is technically correct - Style — whether the written language follows our [style guide](/contributing/gatsby-style-guide/) - Subject matter — blog posts should not be purely promotional, spammy, or inappropriate. An author should check with a member of the Gatsby team that their post is appropriate for the blog before creating their PR. diff --git a/docs/contributing/setting-up-your-local-dev-environment.md b/docs/contributing/setting-up-your-local-dev-environment.md index d1ffb0df7..16ad6809a 100644 --- a/docs/contributing/setting-up-your-local-dev-environment.md +++ b/docs/contributing/setting-up-your-local-dev-environment.md @@ -2,7 +2,7 @@ title: Setting Up Your Local Dev Environment --- -This page outlines how to get set up to contribute to Gatsby core and its ecosystem. For instructions on working with docs, visit the [docs contributions](/contributing/docs-contributions/) page. For blog and website setup instructions, visit the [blog and website contributions](/contributing/blog-and-website-contributions/) page. +This page outlines how to get set up to contribute to Gatsby core and its ecosystem. For instructions on working with docs, visit the [docs contributions](/contributing/docs-contributions/) page. For website setup instructions, visit the [website contributions](/contributing/website-contributions/) page. > Gatsby uses a "monorepo" pattern to manage its many dependencies and relies on > [Lerna](https://lerna.js.org/) and [Yarn](https://yarnpkg.com/en/) to configure the repository for both active development and documentation infrastructure changes. diff --git a/docs/contributing/website-contributions.md b/docs/contributing/website-contributions.md new file mode 100644 index 000000000..21786e1d3 --- /dev/null +++ b/docs/contributing/website-contributions.md @@ -0,0 +1,31 @@ +--- +title: Website Contributions +--- + +If you want to make changes, improvements, or add new functionality to the website, you don't have to set up the full Gatsby repo to contribute. You can spin up your own instance of the Gatsby website with these steps: + +- Clone [the Gatsby repo](https://github.com/gatsbyjs/gatsby/) and navigate to `/www` +- Run `yarn` to install all of the website's dependencies. +- Run `npm run develop` to preview the site at `http://localhost:8000/`. + +> Note: If you are experiencing issues on a Linux machine, run `sudo apt install libvips-dev`, to install a native dependency. You can also reference [Gatsby guide on Linux](/docs/gatsby-on-linux/) for other Linux-specific requirements. + +Now you can make and preview your changes before raising a pull request! + +For full repo setup instructions, visit the [code contributions](/contributing/code-contributions/) page. + +## Styling components on Gatsbyjs.org with Theme-UI + +Styles on the site are applied using [Theme-UI](https://theme-ui.com/), which allows for theming across the site based on design tokens (also called variables). + +### Design tokens + +Design tokens are used to consolidate the number of colors and style attributes that are applied to components throughout the site. By limiting the styles that can be applied, the site stays consistent with the guidelines for color, typography, spacing, etc. + +Tables listing design tokens that are used on the site can be found in the [design guidelines](/guidelines/design-tokens/). + +### The `sx` prop + +The [`sx` prop](https://theme-ui.com/sx-prop) from Theme-UI allows you to access theme values to style elements and components, it should be used wherever possible. The prop is "enabled" by adding `theme-ui`'s [JSX pragma](https://theme-ui.com/jsx-pragma) at the top of a `js` file. + +It is still okay to directly import tokens, e.g. `mediaQueries` or `colors` directly from [`www/src/gatsby-plugin-theme-ui`](https://github.com/gatsbyjs/gatsby/blob/master/www/src/gatsby-plugin-theme-ui/index.js) if it helps your specific use case — for example when global CSS is required, when passing theme values to other libraries or plugins, when authoring complex responsive styles, etc. From 1c97ef16ce037bce233fdd19bc941de39b232853 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 18:33:26 +0000 Subject: [PATCH 025/127] sync with monorepo gatsbyjs/gatsby@068ef1b422cd775dcbd0ea502d5ff6cb8b48a991 - (docs) Remove jsdoc for graphql fragments in GraphQL API (#21811) * Remove jsdoc for graphql fragments * remove docstaticqueries * Update packages/gatsby-image/README.md Co-Authored-By: Kyle Gill Co-authored-by: Kyle Gill Co-authored-by: GatsbyJS Bot --- docs/docs/graphql-api.md | 37 ++----------------------------------- 1 file changed, 2 insertions(+), 35 deletions(-) diff --git a/docs/docs/graphql-api.md b/docs/docs/graphql-api.md index d64f64ec9..6b8f64fbf 100644 --- a/docs/docs/graphql-api.md +++ b/docs/docs/graphql-api.md @@ -3,9 +3,6 @@ title: GraphQL API tableOfContentsDepth: 2 --- -import { GraphqlApiQuery } from "../../www/src/components/api-reference/doc-static-queries" -import APIReference from "../../www/src/components/api-reference" - A great advantage of Gatsby is a built-in data layer that combines all data sources you configure. Data is collected at [build time](/docs/glossary#build) and automatically assembled into a [schema](/docs/glossary#schema) that defines how data can be queried throughout your site. This doc serves as a reference for GraphQL features built into Gatsby, including methods for querying and sourcing data, and customizing GraphQL for your site's needs. @@ -227,39 +224,9 @@ Fragments allow you to reuse parts of GraphQL queries. They also allow you to sp For more information, check out the docs guide on [using fragments in Gatsby](/docs/using-graphql-fragments/). -### List of Gatsby fragments - -Some fragments come included in Gatsby plugins, such as fragments for returning optimized image data in various formats with `gatsby-image` and `gatsby-transformer-sharp`, or data fragments with `gatsby-source-contentful`. - -#### Image sharp fragments - -The following fragments are available in any site with `gatsby-transformer-sharp` installed and included in your `gatsby-config.js`. - -Information on querying with these fragments is also listed in-depth in the [Gatsby image API docs](/docs/gatsby-image/), including options like resizing and recoloring. - - - {data => ( - - )} - - -#### Contentful fragments - -The following fragments are available in any site with `gatsby-source-contentful` installed and included in your `gatsby-config.js`. These fragments generally mirror the fragments outlined in the `gatsby-transformer-sharp` package. - - - {data => ( - - )} - +### Gatsby fragments -**Note**: the above fragments are from officially maintained Gatsby starters; other plugins like `gatsby-source-datocms` and `gatsby-source-sanity` ship with fragments of their own. A list of those fragments can be found in the [`gatsby-image` README](/packages/gatsby-image#fragments). +Some fragments come included in Gatsby plugins, such as fragments for returning optimized image data in various formats with `gatsby-image` and `gatsby-transformer-sharp`, or data fragments with `gatsby-source-contentful`. For more information on what plugins include fragments, see the [`gatsby-image` README](/packages/gatsby-image#fragments). ## Advanced customizations From 46520ea71379792b6e705dcffb329e4c84ec48f8 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 28 Feb 2020 20:09:57 +0000 Subject: [PATCH 026/127] sync with monorepo gatsbyjs/gatsby@cb3d68afafb91d45f17c274eb9b3a0e427d87e4e - add egghead embeds for new mdx screencasts (#21781) --- docs/docs/mdx/getting-started.md | 5 +++++ docs/docs/mdx/importing-and-using-components.md | 10 ++++++++++ 2 files changed, 15 insertions(+) diff --git a/docs/docs/mdx/getting-started.md b/docs/docs/mdx/getting-started.md index d3b524ac7..f5c7a3d6d 100644 --- a/docs/docs/mdx/getting-started.md +++ b/docs/docs/mdx/getting-started.md @@ -60,6 +60,11 @@ Alternatively, you may be looking to configure an existing blog site to use MDX. > `tableOfContents` and you haven't previously added a `gatsby-source-filesystem` > pointing at `src/pages` in your project, you'll want to add one now. + + ## What's next? Go check out the [writing MDX guide](/docs/mdx/writing-pages) to find out what else you can do diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index b70a3f9d3..30a9014e8 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -24,6 +24,11 @@ You can import your own components. **Note**: steps for importing custom components or MDX documents from a relative location in your project are also covered in the [Writing Pages in MDX guide](/docs/mdx/writing-pages/). + + ## Make components available globally as shortcodes To avoid having to import the same component inside of every MDX document you author, you can add components to an `MDXProvider` to make them globally available in MDX pages. This pattern is sometimes referred to as shortcodes. @@ -63,6 +68,11 @@ The Chart is also available since it was passed into the MDXProvider: Because the `` and `` components were passed into the provider, they are available for use in all MDX documents. + + ### Additional resources - Follow this detailed [example on using MDX](/examples/using-MDX) to import and render components. From 5c2d7dc4505639c95be4fe647dc716cb80097b14 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 2 Mar 2020 08:26:23 +0000 Subject: [PATCH 027/127] sync with monorepo gatsbyjs/gatsby@8da07a3deadb3d6581d0de2775b883df5a6e8cac - fix(docs): fix anchor links (#21888) * fix * fix * fix --- docs/docs/setting-up-gatsby-without-gatsby-new.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docs/setting-up-gatsby-without-gatsby-new.md b/docs/docs/setting-up-gatsby-without-gatsby-new.md index 7a794cacd..c0415fe2c 100644 --- a/docs/docs/setting-up-gatsby-without-gatsby-new.md +++ b/docs/docs/setting-up-gatsby-without-gatsby-new.md @@ -8,9 +8,8 @@ There are many Enterprise level companies that maintain an internal clone of the To get started with Gatsby, you’ll need to make sure you have the following software tools installed: -1. [Node.js](/tutorial/part-zero/#install-nodejs) -1. [npm CLI](/tutorial/part-zero/#familiarize-with-npm) -1. [Gatsby CLI](/tutorial/part-zero/#install-the-gatsby-cli) +1. [Node.js](/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system) +2. [Gatsby CLI](/tutorial/part-zero/#using-the-gatsby-cli) For step-by-step installation instructions and detailed explanations of the required software, head on over to the [Gatsby tutorial](/tutorial/part-zero/). From 19172156960d4db2e1e6fc3af732a0df3d170bc2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 2 Mar 2020 13:31:08 +0000 Subject: [PATCH 028/127] sync with monorepo gatsbyjs/gatsby@ce0efb4cde17805545509376f2ca8184510ad68a - Improve consistent usage of "CSS" (#21874) --- docs/tutorial/part-two/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorial/part-two/index.md b/docs/tutorial/part-two/index.md index 4f6bd0812..1234d4da2 100644 --- a/docs/tutorial/part-two/index.md +++ b/docs/tutorial/part-two/index.md @@ -48,7 +48,7 @@ You now have a new Gatsby site (based on the Gatsby "hello world" starter) with │   └── index.js ``` -#### ✋ Add styles to a css file +#### ✋ Add styles to a CSS file 1. Create a `.css` file in your new project: @@ -80,7 +80,7 @@ html { } ``` -> Note: The placement of the example css file in a `/src/styles/` folder is arbitrary. +> Note: The placement of the example CSS file in a `/src/styles/` folder is arbitrary. #### ✋ Include the stylesheet in `gatsby-browser.js` @@ -130,7 +130,7 @@ If you take a look at your project in the browser, you should see a lavender bac ## Using component-scoped CSS -So far, we've talked about the more traditional approach of using standard css stylesheets. Now, we'll talk about various methods of modularizing CSS to tackle styling in a component-oriented way. +So far, we've talked about the more traditional approach of using standard CSS stylesheets. Now, we'll talk about various methods of modularizing CSS to tackle styling in a component-oriented way. ### CSS Modules @@ -161,7 +161,7 @@ export default ({ children }) => ( ) ``` -You'll notice you imported a css module file named `container.module.css`. Let's create that file now. +You'll notice you imported a CSS module file named `container.module.css`. Let's create that file now. 2. In the same directory (`src/components`), create a `container.module.css` file and copy/paste the following: From 8fac05aa7460234d3806436209c16737689ecdd7 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 2 Mar 2020 14:41:57 +0000 Subject: [PATCH 029/127] sync with monorepo gatsbyjs/gatsby@097b235afd70eba920a7b6e5dd53ae0a51bba0ee - docs(api-proxy): update code exmaple with explicit require (#21830) * docs(api-proxy): update code exmaple with explicit require http-proxy-middleware v1.0.0 introduces breaking change. require/import of http-proxy-middleware is now explicit. * docs(api-proxy): update code exmaples with explicit require with comments that explains how to use the previous version * chore: format Co-authored-by: GatsbyJS Bot --- docs/docs/api-proxy.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/docs/api-proxy.md b/docs/docs/api-proxy.md index 3c9fcfeb7..51e7b9004 100644 --- a/docs/docs/api-proxy.md +++ b/docs/docs/api-proxy.md @@ -47,13 +47,16 @@ Keep in mind that `proxy` only has effect in development (with `gatsby develop`) 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") +const { createProxyMiddleware } = require("http-proxy-middleware") //v1.x.x +// Use implicit require for v0.x.x of 'http-proxy-middleware' +// const proxy = require('http-proxy-middleware') +// be sure to replace 'createProxyMiddleware' with 'proxy' where applicable module.exports = { developMiddleware: app => { app.use( "/.netlify/functions/", - proxy({ + createProxyMiddleware({ target: "http://localhost:9000", pathRewrite: { "/.netlify/functions/": "", @@ -71,12 +74,16 @@ Keep in mind that middleware only has effect in development (with `gatsby develo If you proxy to local APIs with self-signed certificates, set the option `secure` to `false`. ```javascript:title=gatsby-config.js -var proxy = require("http-proxy-middleware") +const { createProxyMiddleware } = require("http-proxy-middleware") //v1.x.x +// Use implicit require for v0.x.x of 'http-proxy-middleware' +// const proxy = require('http-proxy-middleware') +// be sure to replace 'createProxyMiddleware' with 'proxy' where applicable + module.exports = { developMiddleware: app => { app.use( "/.netlify/functions/", - proxy({ + createProxyMiddleware({ target: "http://localhost:9000", secure: false, // Do not reject self-signed certificates. pathRewrite: { From 2e057dd018c5646be713f69a32e53a30672267db Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 2 Mar 2020 15:26:07 +0000 Subject: [PATCH 030/127] sync with monorepo gatsbyjs/gatsby@ae30ba8f29b0b2880a8e90122037130dc7c20e15 - docs(deploying-to-firebase.md): add firebase.json cache configuration (#21897) * docs(deploying-to-firebase.md): add firebase.json cache configuration Adds how to update the `firebase.json` to configure the firebase cache correctly. * chore: format Co-authored-by: GatsbyJS Bot --- docs/docs/deploying-to-firebase.md | 58 ++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/docs/deploying-to-firebase.md b/docs/docs/deploying-to-firebase.md index 830d0efe0..2fb8a4407 100644 --- a/docs/docs/deploying-to-firebase.md +++ b/docs/docs/deploying-to-firebase.md @@ -45,6 +45,64 @@ In this guide, you will learn how to deploy your Gatsby site to Firebase Hosting When prompted to select your public directory, press enter. It will default to `public`, which is also Gatsby's default public directory. +1. Update the `firebase.json` with the following cache settings + +```json +{ + "hosting": { + "public": "public", + "ignore": ["firebase.json", "**/.*", "**/node_modules/**"], + "headers": [ + { + "source": "**/*", + "headers": [ + { + "key": "cache-control", + "value": "cache-control: public, max-age=0, must-revalidate" + } + ] + }, + { + "source": "static/**", + "headers": [ + { + "key": "cache-control", + "value": "public, max-age=31536000, immutable" + } + ] + }, + { + "source": "**/*.@(css|js)", + "headers": [ + { + "key": "cache-control", + "value": "public, max-age=31536000, immutable" + } + ] + }, + { + "source": "sw.js", + "headers": [ + { + "key": "cache-control", + "value": "cache-control: public, max-age=0, must-revalidate" + } + ] + }, + { + "source": "page-data/**", + "headers": [ + { + "key": "cache-control", + "value": "cache-control: public, max-age=0, must-revalidate" + } + ] + } + ] + } +} +``` + 1. Prepare your site for deployment by running `gatsby build`. This generates a publishable version of your site in the `public` folder. 1. Deploy your site by running the following command: From 5996343dba10eb44833edacdb75ec1e730f3a9ea Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 2 Mar 2020 22:02:20 +0000 Subject: [PATCH 031/127] sync with monorepo gatsbyjs/gatsby@b6de2b90f0f4fe4686aee2a712f461446eb6e8a2 - fix: hot fix for `gatsby develop` when HOME is not set (#21914) * fix: hot fix for `gatsby develop` when HOME is not set * use actual (temporary) directory --- docs/docs/using-client-side-only-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/using-client-side-only-packages.md b/docs/docs/using-client-side-only-packages.md index a856ea038..eabaf46ae 100644 --- a/docs/docs/using-client-side-only-packages.md +++ b/docs/docs/using-client-side-only-packages.md @@ -50,7 +50,7 @@ class MyComponent extends Component { } ``` -## Workaround 3: Load client-side dependent components with react-loadable +## Workaround 3: Load client-side dependent components with loadable-components Install [loadable-components](https://github.com/smooth-code/loadable-components) and use it as a wrapper for a component that wants to use a client-side only package. From 222a9f28ad0afa6c7646462555bf0e364970827a Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 3 Mar 2020 08:32:13 +0000 Subject: [PATCH 032/127] sync with monorepo gatsbyjs/gatsby@3e8f2c7579e9752df669cfef37452d8ad01b5388 - feat(gatsby): add react profiling option (#21863) * Add profiling option * Use ternary instead * Ammend resolve section to use stage instead of env * Add profile command to docs * Add docs * Further example * Reword * Undo change --- docs/docs/gatsby-cli.md | 13 ++-- ...ng-site-performance-with-react-profiler.md | 64 +++++++++++++++++++ 2 files changed, 71 insertions(+), 6 deletions(-) create mode 100644 docs/docs/profiling-site-performance-with-react-profiler.md diff --git a/docs/docs/gatsby-cli.md b/docs/docs/gatsby-cli.md index e56f110b9..c6b277397 100644 --- a/docs/docs/gatsby-cli.md +++ b/docs/docs/gatsby-cli.md @@ -113,12 +113,13 @@ At the root of a Gatsby site, compile your application and make it ready for dep #### Options -| Option | Description | -| :--------------------------: | --------------------------------------------------------------------------------------------------------- | -| `--prefix-paths` | Build site with link paths prefixed (set pathPrefix in your config) | -| `--no-uglify` | Build site without uglifying JS bundles (for debugging) | -| `--open-tracing-config-file` | Tracer configuration file (OpenTracing compatible). See [Performance Tracing](/docs/performance-tracing/) | -| `--no-color`, `--no-colors` | Disables colored terminal output | +| Option | Description | +| :--------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `--prefix-paths` | Build site with link paths prefixed (set pathPrefix in your config) | +| `--no-uglify` | Build site without uglifying JS bundles (for debugging) | +| `--profile` | Build site with react profiling. See [Profiling Site Performance with React Profiler](/docs/profiling-site-performance-with-react-profiler/) | +| `--open-tracing-config-file` | Tracer configuration file (OpenTracing compatible). See [Performance Tracing](/docs/performance-tracing/) | +| `--no-color`, `--no-colors` | Disables colored terminal output | In addition to these build options, there are some optional [build environment variables](/docs/environment-variables/#build-variables) for more advanced configurations that can adjust how a build runs. For example, setting `CI=true` as an environment variable will tailor output for [dumb terminals](https://en.wikipedia.org/wiki/Computer_terminal#Dumb_terminals). diff --git a/docs/docs/profiling-site-performance-with-react-profiler.md b/docs/docs/profiling-site-performance-with-react-profiler.md new file mode 100644 index 000000000..53cc73da4 --- /dev/null +++ b/docs/docs/profiling-site-performance-with-react-profiler.md @@ -0,0 +1,64 @@ +--- +title: Profiling Site Performance with React Profiler +--- + +React profiling captures timing information that can help identify performance issues within your gatsby site. + +## Requirements + +React's profiling API was introduced in **React 16.5**. Therefore you must be running React 16.5 or higher. + +## Using the profiler + +Profiling will be enabled automatically in Development. If you have React DevTools it will [show a “Profiler” tab](https://reactjs.org/blog/2018/09/10/introducing-the-react-profiler.html#profiling-an-application). Caution should be given to the validity of profiling within Development as this does not reflect the performance of the Production build and therefore the experience of your users. + +To enable profiling for a Production build an additional CLI option `--profile` must be provided when running the build command. See [gatsby build command](/docs/gatsby-cli/#options-1) for further information. + +## Performance impact + +Although Profiler is a light-weight component, it should be used only when necessary; each use adds some CPU and memory overhead to an application. + +A warning will be issued in a Gatsby Production build if the `--profile` option is provided. + +## Using the Profiler API + +If you just want to see some high level results, your [React DevTools will have a profiling tab](https://reactjs.org/blog/2018/09/10/introducing-the-react-profiler.html#profiling-an-application) which provides some helpful performance information. However if you want to be able to capture more information programmatically, then React exports a `profiler` component which allows your site to tap into the performance metrics. + +The react profiler component can be used anywhere in a react tree to measure the performance of that part of the tree. + +### Profiling a slow component + +```js +import * as React from "react" +import { Profiler } from "react" + +export const MyComponent = props => ( + // See https://reactjs.org/docs/profiler.html#onrender-callback for onRender parameters + + + +) +``` + +### Profiling Gatsby pages + +Capturing page performance can be achieved by using the [wrapPageElement API](/docs/browser-apis/#wrapPageElement) to profile each page. + +```js +//gatsby-browser.js + +import * as React from "react" +import { Profiler } from "react" + +export const wrapPageElement = ({ element, props }) => ( + // See https://reactjs.org/docs/profiler.html#onrender-callback for onRender parameters + + {element} + +) +``` + +### References: + +- [React Profiler](https://reactjs.org/docs/profiler.html) +- [React Profiler Introduction Blog](https://reactjs.org/blog/2018/09/10/introducing-the-react-profiler.html) From 357bae0ead68b847a6330bddd863716d326cd1a6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 3 Mar 2020 10:50:14 +0000 Subject: [PATCH 033/127] sync with monorepo gatsbyjs/gatsby@c49d7b44f304435a4a8504bb1dd16909dc4c04a8 - feat(gatsby): Page build optimisations for incremental data changes (#21523) * store page data between builds * Support removing of pages from public * build all pages if webpackCompilationHash has changed * Support deleting of data on processors that run once * Add expirement flag to page performance * Add expirement flag to page performance * Add comments and types to actions * Add missing page data reducer * Retain public between builds * Add docs to page build time enhancement * Update Page build optimisations docs * initial refactor from code review * Use hash instead of whole page context * Use hash instead of whole page context * Remove page data in dev action deleteComponentsDependencies * Pass cache page data to processQueries function * Remove added pageData check in component-data-dependencies.js * Remove pagedata if page removed in page-hot-reloader * Update snapshots * Revert "Update snapshots" This reverts commit a9b2b68ea138a043200097920dc9249366c56a04. * Update reducer context * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md Co-Authored-By: LB * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md Co-Authored-By: LB * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md Co-Authored-By: LB * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md Co-Authored-By: LB * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md Co-Authored-By: LB * Fix doc duplication error * Update docs * Update docs/docs/page-build-optimizations-for-incremental-data-changes.md Co-Authored-By: Michal Piechowiak * Update www/src/data/sidebars/doc-links.yaml Co-Authored-By: Michal Piechowiak * refector improvements * improve delete to use promise all * Block develop mode if experimental flag is used * Update docs with new flag name GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES * Improvements remove pages logic * Remove empty directory if no files * Refactor pagePath reassign in build * initial attempt at removing nested folders in the correct order * refactor delete public html and data function * use join in render-html.js * Renaming functions and refactoring * Add remove functions to page util * Remove whitespace from page-data * Move new build functions to build-utils.js * check html suffix function * update docs * handle .html paths when removing empty directories * Apply suggestions from code review Co-Authored-By: LB * fix formating issue on docs Co-authored-by: Stuart Rayson Co-authored-by: LB Co-authored-by: Michal Piechowiak --- .../overview-of-the-gatsby-build-process.md | 2 + ...imizations-for-incremental-data-changes.md | 63 +++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/docs/page-build-optimizations-for-incremental-data-changes.md diff --git a/docs/docs/overview-of-the-gatsby-build-process.md b/docs/docs/overview-of-the-gatsby-build-process.md index e0c8a9b77..1f94bed1c 100644 --- a/docs/docs/overview-of-the-gatsby-build-process.md +++ b/docs/docs/overview-of-the-gatsby-build-process.md @@ -301,6 +301,8 @@ Page queries that were queued up earlier from query extraction are run so the da With everything ready for the HTML pages in place, HTML is compiled and written out to files so it can be served up statically. Since HTML is being produced in a Node.js server context, [references to browser APIs like `window` can break the build](/docs/debugging-html-builds/) and must be conditionally applied. +By default, Gatsby rebuilds static HTML for all pages on each build. There is an experimental feature flag `GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES` which enables [Page Build Optimizations for Incremental Data Changes](/docs/page-build-optimizations-for-incremental-data-changes/). + ## What do you get from a successful build? When a Gatsby build is successfully completed, everything you need to deploy your site ends up in the `public` folder at the root of the site. The build includes minified files, transformed images, JSON files with information and data for each page, static HTML for each page, and more. diff --git a/docs/docs/page-build-optimizations-for-incremental-data-changes.md b/docs/docs/page-build-optimizations-for-incremental-data-changes.md new file mode 100644 index 000000000..1d93dc8c2 --- /dev/null +++ b/docs/docs/page-build-optimizations-for-incremental-data-changes.md @@ -0,0 +1,63 @@ +--- +title: Experimental Page Build Optimizations for Incremental Data Changes +--- + +Building sites with large amounts of content (10,000s nodes upwards) is relatively fast with Gatsby. However, some projects might start to experience issues when adopting CI/CD principles - continuously building and deploying. Gatsby rebuilds the complete app on each `gatsby build` which means the complete app also needs to be deployed. Doing this each time a small data change occurs unnecessarily increases demand on CPU, memory, and bandwidth. + +One solution to these problems might be to use [Gatsby Cloud's Build features](https://www.gatsbyjs.com/cloud/). + +For projects that require self-hosted environments, where Gatsby Cloud would not be an option, deploying only the content that has changed or is new (incremental data changes, you might say) can help reduce build times, deployment times and demand on resources. + +For more info on the standard build process please see [overview of the gatsby build process](/docs/overview-of-the-gatsby-build-process/) + +## How to use + +To enable this enhancement, use the environment variable `GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true` in your `gatsby build` command, for example: + +`GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true gatsby build --log-pages` + +This will run the Gatsby build process, but only build pages that have data changes since your last build. If there are any changes to code (JS, CSS) the bundling process returns a new webpack compilation hash which causes all pages to be rebuilt. + +### Reporting what has been built + +You may want to retrieve a list of the pages that were built. For example, if you want to perform a sync action in your CI/CD pipeline. + +To list the paths in the build assets (`public`) folder, you can use one (or both) of the following arguments in your `build` command. + +- `--log-pages` parameter will output all the file paths that were updated or deleted at the end of the build stage. + +```bash +success Building production JavaScript and CSS bundles - 82.198s +success run queries - 82.762s - 4/4 0.05/s +success Building static HTML for pages - 19.386s - 2/2 0.10/s ++ success Delete previous page data - 1.512s +info Done building in 152.084 sec ++ info Built pages: ++ Updated page: /about ++ Updated page: /accounts/example ++ info Deleted pages: ++ Deleted page: /test + +Done in 154.501 sec +``` + +- `--write-to-file` creates two files in the `.cache` folder, with lists of the changed paths in the build assets (`public`) folder. + + - `newPages.txt` will contain a list of new or changed paths + - `deletedPages.txt` will contain a list of deleted paths + +If there are no changed or deleted paths, then the relevant files will not be created in the `.cache` folder. + +## More information + +- This enhancement works by comparing the page data from the previous build to the new page data. This creates a list of page directories that are passed to the static build process. + +- To enable this build option you will need to set an environment variable, which requires access to do so in your build environment. + +- This feature is not available with `gatsby develop`. + +* At the end of each build, gatsby creates a `redux.state` file in `/.cache` that contains previous build data. You will need to persist the `.cache/redux.state` between builds, allowing for comparison. If there is no `redux.state` file located in the `/.cache` folder then a full build will be triggered. + +* Any code or static query changes (templates, components, source handling, new plugins etc) will prompt the creation of a new webpack compilation hash and trigger a full build. + +Note: When using the `GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES` flag it is important to do so consistently when building your project. Otherwise, the cache will be cleared and the necessary data for comparison will no longer be available, removing the ability to check for incremental data changes. From fc64ac6353bc08742c7d5bc978aa45101b84f768 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 3 Mar 2020 16:13:54 +0000 Subject: [PATCH 034/127] sync with monorepo gatsbyjs/gatsby@4ab3f194cf5d6dcafcb2a75d9604aac79d963554 - docs: flowchart and tables for differences between plugins, themes, and starters (#21659) * create tables to compare and a flowchart to evaluate differences in plugins, themes, starters * Apply suggestions from code review Co-Authored-By: LB * address PR feedback * adjust confusing sentence * updates to structure to reduce redundancy * Apply suggestions from code review Co-Authored-By: LB * Update docs/docs/plugins-themes-and-starters.md Co-Authored-By: LB * linting errors * Apply suggestions from code review Co-Authored-By: Aisha Blake Co-authored-by: LB Co-authored-by: Aisha Blake --- docs/docs/plugins-themes-and-starters.md | 80 ++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/docs/docs/plugins-themes-and-starters.md b/docs/docs/plugins-themes-and-starters.md index 35e9161c0..f2589beff 100644 --- a/docs/docs/plugins-themes-and-starters.md +++ b/docs/docs/plugins-themes-and-starters.md @@ -36,3 +36,83 @@ Gatsby offers [official starters](/docs/starters/#official-starters) for a defau - [Starter library](/starters/) - [Creating a starter](/docs/creating-a-starter/) - [Converting a starter to a theme](/docs/themes/converting-a-starter/) + +## Conventions for usage + +Themes are a type of plugin, making both themes and plugins capable of the same functionality. The difference between them is _intended usage_. Themes are intended to own a piece of the site (like an about us page), whereas a plugin is intended to modularize Gatsby APIs into smaller pieces. Themes tend to cover a broader scope of responsibility, packaging up multiple behaviors, where plugins are meant for more specific functionality. + +Starters are generally used as the starting point that plugins and themes are then installed into. However, they're based on one-time use and do not get updated over time as plugins and themes do. + +## Comparing differences + +Once you have a conceptual understanding of what a plugin, theme, and starter is, you may ask yourself what each is suited for in relation to each other. + +The following tables put plugins, themes, and starters side-by-side, showing what each is more appropriate for. + +**Legend** + +| Icon | Feature Capability | +| ---- | ---------------------------------------------------------------- | +| ● | Fully capable (possible and supported) | +| ◐ | Somewhat capable (support is minimal or it is not best practice) | +| ○ | Not capable | + +### Differences and considerations in maintenance + +When it comes to maintaining a Gatsby site, plugins and themes offer a distinct advantage to starters by being distributed as packages. This means making changes in multiple Gatsby sites is as easy as a new install of an updated package upstream. It's difficult to sync changes across multiple sites derived from the same starter. + +| Maintenance | Plugin | Theme | Starter | +| ------------------ | ------ | ----- | ------- | +| Versioning | ● | ● | ◐ | +| Install as Package | ● | ● | ○ | + +#### Versioning + +Starters can still be versioned inside of a repository so that you can track issues or bugs associated with specific updates, but they aren't formally released and published, so they aren't versioned like a plugin or theme is. + +#### Installing as a package + +Starters can't be installed into existing sites, this limitation was one of the motivating factors in developing the newer concept of themes. You can read more about the rationale for themes in the [What are Gatsby Themes guide](/docs/themes/what-are-gatsby-themes/#gatsby-starters). + +### Differences and considerations in configuration + +Plugins and themes can expose options to make them configurable for users. There are different possibilities for configuration like passing in options and shadowing files that make plugins and themes more powerful—but also more complicated—than starters. Because themes are also plugins, shadowing is possible in plugins as well. It may make sense for a plugin to take advantage of the shadowing API, but it is less common. + +| Configuration | Plugin | Theme | Starter | +| --------------------- | ------ | ----- | ------- | +| Pass in Options | ● | ● | ◐ | +| Shadowing | ◐ | ● | ○ | +| Uses Multiple Plugins | ◐ | ● | ● | +| Custom components | ◐ | ● | ● | + +#### Pass in Options + +Plugins and themes both allow options to be passed in when installed in the plugins array of a `gatsby-config`. Starters can be set up with documented options for customization, but there are no officially supported options for starters apart from what the author of the starter decides to write. + +#### Shadowing + +Theme [shadowing](/docs/themes/shadowing/) exists to allow users to override or otherwise extend individual components provided by a theme. For example, a plugin or theme can provide a specific path to `gatsby-config` so the plugin knows where to build pages from, but the user wouldn't be able adjust _how_ those pages are built, only from what path. Theme shadowing allows users to replace a file with their own version of it, allowing them to rewrite that logic to use the path in a different way. + +An example of a plugin that uses shadowing is [`gatsby-plugin-theme-ui`](/packages/gatsby-plugin-theme-ui/?=theme-ui#customizing-the-theme) which allows you to shadow a theme file to use in your own theme. + +Starters aren't capable of shadowing (and they don't need to be), because a user of a starter can adjust any file by editing it directly. + +#### Uses multiple plugins + +Themes are intended to abstract several plugins into one, by making a `gatsby-config` that a Gatsby site will run along with its own config. Starters can also be configured with multiple plugins so someone can get up and running without worrying about configuring too many loose ends. + +#### Custom components + +Custom components are most traditionally distributed as packages in the React ecosystem. Components don't need to hook into the Gatsby build system, so if shipped with a plugin they don't need to be included in a `gatsby-config`'s plugin array. This is the case with `gatsby-image` which is a React component. It doesn't need to be included in the plugins array because it is merely a component. + +Some plugins ship with components you can use in a Gatsby site. An example is the [`` component from `gatsby-plugin-google-analytics`](/packages/gatsby-plugin-google-analytics/?=#outboundlink-component). Other plugins, like [`gatsby-plugin-react-helmet`](/packages/gatsby-plugin-react-helmet), require you to install components from other libraries. + +Themes by convention are more suited to ship with components that could then be shadowed for customization. + +Starters will include components to render data, but they are tied to the starter. + +## Deciding which to use + +As an aid to help try and guide you to which of the 3 options is right for your use case, consider this flowchart: + +![Flowchart walking through options for plugins, starters, and themes](./images/plugin-starter-theme-flowchart.png) From c0bd4116f6a8c9e039a05bed38c7b1fb47d004c9 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 3 Mar 2020 20:15:57 +0000 Subject: [PATCH 035/127] sync with monorepo gatsbyjs/gatsby@ba0d393c0aa5e0aeec14bcf5c51b30f689708528 - (docs) Add a defintion of slug to Part 7 tutorial (#21939) * add a defintion of slug to part 7 tutorial * Update to include suggestion docs/tutorial/part-seven/index.md Co-Authored-By: LB * Update to include suggestion docs/tutorial/part-seven/index.md Co-Authored-By: LB Co-authored-by: LB --- docs/tutorial/part-seven/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/tutorial/part-seven/index.md b/docs/tutorial/part-seven/index.md index d51b596be..477164324 100644 --- a/docs/tutorial/part-seven/index.md +++ b/docs/tutorial/part-seven/index.md @@ -23,6 +23,11 @@ Let's get started. ## Creating slugs for pages +A ‘slug’ is the unique identifying part of a web address, +such as the `/tutorial/part-seven` part of the page `https://www.gatsbyjs.org/tutorial/part-seven/`. + +It is also referred to as the ‘path’ but this tutorial will use the term ‘slug’ for consistency. + Creating new pages has two steps: 1. Generate the "path" or "slug" for the page. From 4999691d3533ba761d4bec60ec14711ad7eb6eb4 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 4 Mar 2020 00:49:33 +0000 Subject: [PATCH 036/127] sync with monorepo gatsbyjs/gatsby@b2c0700ddddc77e78d4202db56be6da146f5c717 - feat(docs): Guide for syncing translation repos (#21753) * add the create script * description of env * add reference to comment. * edit README * more information in README * update create script * add pulling logic * add maintainers to organization * add comment * add discord link * add more discord references * Move script explanations to the README * WIP sync script * add stuff * WIP sync * WIP sync * WIP sync * WIP sync * WIP outline of sync script * WIP outline of sync script * get closer to my goal * get closer to my goal * try to do a line counting function * try to do a line counting function * more templates * resolve conflicts * resolve conflicts function * resolve conflicts function * more work on sync script * get the thing to work hopefully * get it to work * get it to work * update stuff on sync * get rid of parse-diff * rever codesandbox * add FIXMEs * fix new repo cloning issue * more stuff * fix issues with deleted file conflicts * add documentation on sync behavior * no github comments * Create another pull request with non-conflicts * add FIXME * fix number issue * almost done! * todo * remember to switch to master branch * all * fix headings on sync guide * add more guide info * extraneous comment * information on the second pull request * add guide * remove fixme * add logging * more silencing * remove script info * add more sync docs * more information on syncing * Update docs/contributing/translation/sync-guide.md Co-Authored-By: Aisha Blake * Update docs/contributing/translation/sync-guide.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/contributing/translation/sync-guide.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: Aisha Blake Co-authored-by: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: GatsbyJS Bot --- docs/contributing/translation/sync-guide.md | 160 +++++++++++++++++++- 1 file changed, 156 insertions(+), 4 deletions(-) diff --git a/docs/contributing/translation/sync-guide.md b/docs/contributing/translation/sync-guide.md index c2d87117d..ae48f2e25 100644 --- a/docs/contributing/translation/sync-guide.md +++ b/docs/contributing/translation/sync-guide.md @@ -1,13 +1,42 @@ --- title: Keeping Translations Up-to-date -issue: https://github.com/gatsbyjs/gatsby/issues/21250 --- -Periodically, gatsbybot will create pull requests to keep translations repos up-to-date with the original English source. Make sure to review these PRs to ensure that your translation remains accurate. +Periodically, gatsbybot will update your translation repo to be up-to-date with the current English repo. If there is an update to a page that is already translated, gatsbybot will create a pull request listing the conflicts between translation and the new English content. Resolving these conflicts and merging these pull requests is essential to keeping your translation repo up-to-date. -> Note: the bot doesn't work yet but will come soon. Until then, see the next section to learn how to manually sync your repo. +## Resolving sync pull requests -### Manually syncing translation repos +When it runs the sync script, gatsbybot will create up to two pull requests. One is named: + +```text +(sync) Sync with gatsby-i18n-source @ {hash} +``` + +This pull request contains updates to all files that do not have conflicts. This includes files that have not been translated yet, and files that have been added to Gatsby. In general, these files can be merged in as-is, but it may be worth looking over them to see if there are any new files that were added to the repo that need to be translated. + +> 🚨NOTE: Make sure you do **NOT** choose the ["Squash and merge"](https://help.github.com/en/github/administering-a-repository/about-merge-methods-on-github#squashing-your-merge-commits) option when merging this pull request. Squashing will result in Git losing information about the sync, and will lead to extra conflicts on your next sync. Always make sure that you use the "Merge pull request" option. + +The second pull request will be named: + +```text +(sync) Resolve conflicts with gatsby-i18n-source @ {hash} +``` + +This pull request will list files that have conflicts between translated content and English content. These updates will appear as Git conflicts: + +```diff ++ <<<<<<< HEAD +Ahora, el componente `Box` estará al pendiente del estado de la transición de la página que es hijo, y aparecerá de entrada/salida en consecuencia. ++ ======= ++ Now, the `Box` component will be aware of whether the page it's a child of is mounting or unmounting, and it will fade in/out accordingly. ++ >>>>>>> 90932a06db2e297cf416552b84e48b4b82e56fbc +``` + +Here, the top block is the original translated line and the bottom block is the updated source content. You should resolve these conflicts by updating the top block to reflect the content of the bottom block. + +You may use whatever tools you like to resolve these conflicts: the GitHub UI, the command line, or a code editor like VS Code. See the [Common types of merge issues](#common-types-of-merge-issues) section for how to resolve various conflicts. + +## Manually syncing translation repos If for whatever reason you'd like to manually sync your translation repo, you can do so by running these commands: @@ -17,3 +46,126 @@ git pull source master ``` Fix all [merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line) and create a pull request to finish the merge. + +## Common types of merge issues + +### Frontmatter changes + +This type of conflict reflects a change to the [frontmatter]() of a document. + +Removing a field: + +```diff ++ <<<<<<< +title: my stub article +issue: #12345 ++ ======= ++ title: My Stub Article ++ >>>>>>> +``` + +Adding a field: + +```diff ++ <<<<<<< +title: Documentacion ++ ======= ++ title: Docs ++ description: The one-stop shop for documentation in Gatsby! ++ >>>>>>> +``` + +Changing a field: + +```diff ++ <<<<<<< +title: My old title ++ ======= ++ title: My new title ++ >>>>>>> +``` + +### Typos fixes + +Sometimes there is a typo or grammatical error in the English source that gets fixed in an update. + +```diff +- Let's all use Gabsty! ++ Let's all use Gatsby! +``` + +```diff +- Gatsby is awesome framework! ++ Gatsby is an awesome framework! +``` + +Since these typos most likely don't exist in the translated version, you can most likely use the translated version as-is. + +### Formatting changes + +Sometimes the only difference is a change in formatting, such as adding back-ticks to annotate something as code, or changing the level of headings: + +```diff +- Sass files have the extension .scss. ++ Sass files have the extension `.scss`. +``` + +```diff +- #### Formatting changes ++ ### Formatting changes +``` + +The only necessary change is to ensure the translated content carries over these formatting updates. + +### Link updates + +These changes involve updating the URL of a link: + +```diff +- Please see our [plugins page](/packages). ++ Please see our [plugins page](/plugins). +``` + +```diff +- Check out our [GitHub](http://github.com/gatsbyjs/gatsby) ++ Check out our [GitHub](https://github.com/gatsbyjs/gatsby) +``` + +Resolve these changes by updating the link. + +### Content changes + +Sometimes, the content of the source page is actually updated and needs a translation. Make sure to read the change carefully and change the translation to match its meaning. + +### Conflicts in untranslated files + +Sometimes, you may find conflicts in files that haven't been translated yet: + +```diff ++ <<<<<<< +This is old English content. ++ ======= ++ This is new English content. ++ >>>>>>> +``` + +This is usually because of a previous improper merge (for example, using the "Squash and merge" option). In this case, it's usually alright to accept the new content. In VS Code, this is done using the "Accept Incoming Change" option: + +```diff +- This is old English content. ++ This is new English content. +``` + +## Creating a separate pull request + +If a page has significant changes, it may be worth splitting it into its own pull request: + +```shell +git checkout conflicts-9032a0 +git checkout -b sync-tutorial-0 +# Fix conflicts in /docs/tutorial/part-zero/index.md +git commit -am "Fix conflicts in tutorial part zero" +git push -u origin sync-tutorial-0 +``` + +Once the branch is pushed, create a pull request for branch `sync-tutorial-0` with `conflicts-9032a0` as the base branch. From b5585aab3771aea389c0b40120ba3843b7e10e16 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 4 Mar 2020 15:25:34 +0000 Subject: [PATCH 037/127] sync with monorepo gatsbyjs/gatsby@76daf4bb1a53beabc2ec450010c1b7e021ee5f1d - fix(docs): Fix Typos (#21960) --- docs/contributing/translation/sync-guide.md | 2 +- docs/docs/sourcing-from-woocommerce.md | 2 +- docs/docs/working-with-images-in-markdown.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/translation/sync-guide.md b/docs/contributing/translation/sync-guide.md index ae48f2e25..143e9aabd 100644 --- a/docs/contributing/translation/sync-guide.md +++ b/docs/contributing/translation/sync-guide.md @@ -68,7 +68,7 @@ Adding a field: ```diff + <<<<<<< -title: Documentacion +title: Documentation + ======= + title: Docs + description: The one-stop shop for documentation in Gatsby! diff --git a/docs/docs/sourcing-from-woocommerce.md b/docs/docs/sourcing-from-woocommerce.md index eed8160c8..226c9bf68 100644 --- a/docs/docs/sourcing-from-woocommerce.md +++ b/docs/docs/sourcing-from-woocommerce.md @@ -42,7 +42,7 @@ Configure its options: The `consumer_key` and `consumer_secret` come from WooCommerce. From your dashboard, go to WooCommerce > Settings > Advanced > REST API and then add a key. You can then copy and paste both the key and secret. Make sure to store any sensitive information in [environment variables](/docs/environment-variables/)! -It's worth noting that the offical WordPress source plugin is in active development. Knowing that this work is in-progress, if you're interested in working with a GraphQL endpoint directly in your WordPress installation, see the section below on [pending changes](#pending-changes) to get started with WPGraphQL and WooCommerce. +It's worth noting that the official WordPress source plugin is in active development. Knowing that this work is in-progress, if you're interested in working with a GraphQL endpoint directly in your WordPress installation, see the section below on [pending changes](#pending-changes) to get started with WPGraphQL and WooCommerce. ## Adding products diff --git a/docs/docs/working-with-images-in-markdown.md b/docs/docs/working-with-images-in-markdown.md index 0d726f467..5498a7a56 100644 --- a/docs/docs/working-with-images-in-markdown.md +++ b/docs/docs/working-with-images-in-markdown.md @@ -55,7 +55,7 @@ The next step will be to incorporate the data into a template with a GraphQL que ### Configuring for images and posts in different directories -There are also occassions when you may want to source images from a different directory than where your Markdown posts or pages are located, such as in an external `/images` folder. You can set this up by specifying two distinct sources, one for the pages and the other for images: +There are also occasions when you may want to source images from a different directory than where your Markdown posts or pages are located, such as in an external `/images` folder. You can set this up by specifying two distinct sources, one for the pages and the other for images: ```js:title=gatsby-config.js module.exports = { From 3b3a6889268248f31ba1efb4aaa94425d1bdf206 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 4 Mar 2020 17:52:32 +0000 Subject: [PATCH 038/127] sync with monorepo gatsbyjs/gatsby@00734a22e9157d4660496a12109c59270a0e9b64 - [docs][guides] update Performance doc per style guide (#21855) --- docs/docs/performance.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/performance.md b/docs/docs/performance.md index 469fd96c5..268293063 100644 --- a/docs/docs/performance.md +++ b/docs/docs/performance.md @@ -3,9 +3,9 @@ title: Performance 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. +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 out of the box 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://v8.dev/blog/cost-of-javascript-2019) by Addy Osmani on the Cost of JavaScript. +This section will 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 maximize site performance. If you would like a more in-depth explanation of why performance matters so much, check out this article by Addy Osmani on the [Cost of JavaScript]](https://v8.dev/blog/cost-of-javascript-2019). May your Lighthouse scores all be in the green. 😀 From 0d5b0de35a4ecd965db290aa2ab50bb132995c30 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 4 Mar 2020 20:11:56 +0000 Subject: [PATCH 039/127] sync with monorepo gatsbyjs/gatsby@fccab7254c37d708ce326f400576601895c0e99e - [docs] Add advanced tutorials for SEO and social sharing cards (#20964) * docs(blog): add seo and gatsby blog post * feat(blog): address feedback from Shannon, Andrew * fix(docs): featured -> cover * chore: tweak tags * Draft square guide * Docs(gatsby): Move blog post to advanced tutorials * docs(tutorial): Add tutorial link to other pages * Add Square guide * Tweak Square notes * Apply suggestions from code review Co-Authored-By: LB * clarify sentence on payment options * Fix typo Co-Authored-By: LB * Rework example code based on PR feedback * docs(tutorial): Apply grammar feedback * docs(tutorial): Add note about title and image restrictions * docs(tutorial): Fix typos by CI recommendation * chore: format * Small edits * Fix relative links * Update broken link * Small typos * Update code samples Co-authored-by: Dustin Schau Co-authored-by: Aisha Blake Co-authored-by: LB Co-authored-by: GatsbyJS Bot --- docs/docs/seo.md | 2 +- .../index.md | 641 ++++++++++++++++++ 2 files changed, 642 insertions(+), 1 deletion(-) create mode 100644 docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md diff --git a/docs/docs/seo.md b/docs/docs/seo.md index 7a8fa6e21..22b158447 100644 --- a/docs/docs/seo.md +++ b/docs/docs/seo.md @@ -72,4 +72,4 @@ After deployment, their [Rich result status reports](https://support.google.com/ ## Additional resources -You might also be interested in [blog posts about SEO in Gatsby](/blog/tags/seo/). +You might also be interested in [blog posts about SEO in Gatsby](/blog/tags/seo/) and [an advanced tutorial about SEO and social sharing cards](/tutorial/seo-and-social-sharing-cards-tutorial/). diff --git a/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md b/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md new file mode 100644 index 000000000..6d5c40c71 --- /dev/null +++ b/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md @@ -0,0 +1,641 @@ +--- +title: Search Engine Optimization (SEO) and Social Sharing Cards with Gatsby +--- + +Perhaps you've been approached by an SEO _expert_ who can maximize your revenue and page views just by following these **Three Simple Tricks**! Relatively few people make the concerted effort to implement SEO in their web app. This tutorial will share some of the ins and outs of SEO and how you can implement common SEO patterns in your Gatsby web app, today. By the end of this post you'll know how to do the following: + +- Implement SEO patterns with [react-helmet][react-helmet] +- Create an optimized social sharing card for Twitter, Facebook, and Slack +- Tweak the SEO component exposed in the default gatsby starter ([`gatsby-starter-default`][gatsby-starter-default]) + +## Implementation + +A core ingredient for SEO is a meaningful `title` tag. Make sure to include related keywords without falling into buzzword bingo. Some crawlers also respect `meta` tags, while Google seems to ignore these tags for ranking and indexing at all. + +You probably have seen something like the following: + +```html +My Wonderful App + + +``` + +The _bare minimum_ requirement is to include a `title` tag for basic SEO. However, the following describes a powerful combo of content rendered at _build time_ powered by Gatsby and GraphQL. + +## Gatsby + GraphQL + +GraphQL is a crucial feature enabled via Gatsby (note: you don't [_have_ to use GraphQL with Gatsby][unstructured-data]). Leveraging GraphQL to query your indexable content--wherever it lives (at build time!)--is one of the most powerful and flexible techniques enabled via Gatsby. The following sections are a brief look at the implementation of an extensible and flexible SEO component. + +### `StaticQuery` + +Gatsby distinguishes between page-level queries and component queries. The former can use page GraphQL queries while the latter can use [`StaticQuery`][gatsby-static-query]. A StaticQuery will be parsed, evaluated, and injected at _build time_ into the component that is requesting the data, allowing to fall back to sane defaults, while also providing an extensible, reusable component. + +### Creating the SEO component + +Using the power and flexibility of React, you can create a React component to power this functionality. + +> Note: `react-helmet` is enabled, by default, in gatsby-starter-default and gatsby-starter-blog. +> +> If you're not using those starters, [follow this guide for installation instructions][gatsby-plugin-react-helmet] + +```js:title=src/components/seo.js +import React from "react" +// highlight-start +import Helmet from "react-helmet" +import { useStaticQuery, graphql } from "gatsby" +// highlight-end + +function SEO({ description }) { + const { site } = useStaticQuery( + graphql` + query { + # highlight-start + site { + siteMetadata { + title + description + author + keywords + siteUrl + } + } + # highlight-end + } + ` + ) + + const metaDescription = description || site.siteMetadata.description + + return null +} + +export default SEO +``` + +This component doesn't _do_ anything yet, but it's the foundation for a useful, extensible component. It leverages the `useStaticQuery` functionality enabled via Gatsby to query siteMetadata (e.g. details in `gatsby-config.js`) with description and keywords. At this point, the `SEO` component returns `null` to render nothing. Next, you will _actually_ render something and build out the prototype for this SEO component. + +```js:title=src/components/seo.js +import React from "react" +import Helmet from "react-helmet" +import { useStaticQuery, graphql } from "gatsby" + +function SEO({ description, lang, meta }) { + const { site } = useStaticQuery( + graphql` + query { + site { + siteMetadata { + title + description + author + keywords + siteUrl + } + } + } + ` + ) + + const metaDescription = description || site.siteMetadata.description + + return ( + + ) +} + +// highlight-start +SEO.defaultProps = { + lang: `en`, + meta: [], + description: ``, +} +// highlight-end + +export default SEO +``` + +Whew, getting closer! This will now render the `meta` `description` tag, and will do so using content injected at build-time with the `useStaticQuery` hook. Additionally, it will add the `lang="en"` attribute to the root-level `html` tag to silence that pesky Lighthouse warning 😉. + +This is still the bare bones, rudimentary approach to SEO. An additional step is to enhance this functionality and get some useful functionality for sharing a page via social networks like Facebook, Twitter, and Slack. + +### Implementing social SEO + +In addition to SEO for actual _search_ engines you also want those pretty cards that social networks like Twitter and Slack enable. Specifically, the implementation should feature: + +- Description for embedded results +- Title for embedded results +- (Optionally) display an image and a card if an image is passed in to the component + +```js:title=src/components/seo.js +import React from "react" +import PropTypes from "prop-types" // highlight-line +import Helmet from "react-helmet" +import { useStaticQuery, graphql } from "gatsby" + +// highlight-next-line +function SEO({ description, lang, meta, image: metaImage, title }) { + const { site } = useStaticQuery( + graphql` + query { + site { + siteMetadata { + title + description + author + keywords + siteUrl + } + } + } + ` + ) + + const metaDescription = description || site.siteMetadata.description + // highlight-start + const image = + metaImage && metaImage.src + ? `${data.site.siteMetadata.siteUrl}${metaImage.src}` + : null + // highlight-end + + return ( + + ) +} + +SEO.defaultProps = { + lang: `en`, + meta: [], + description: ``, +} + +SEO.propTypes = { + description: PropTypes.string, + lang: PropTypes.string, + meta: PropTypes.arrayOf(PropTypes.object), + title: PropTypes.string.isRequired, + // highlight-start + image: PropTypes.shape({ + src: PropTypes.string.isRequired, + height: PropTypes.string.isRequired, + width: PropTypes.string.isRequired, + }), + // highlight-end +} + +export default SEO +``` + +Woo hoo! You enabled not only SEO for search engines like Google and Bing, but you also laid the groundwork for enhanced sharing capabilities on social networks. Finally, you will learn to add support for one of the more useful functionalities for SEO: a canonical link. + +## `link rel="canonical"` + +A canonical link is a hint to a search engine that this is the _source_ for this content. It helps resolve duplicate content issues. For instance, if you have several paths to the same content, you can use a canonical link as akin to a soft redirect which will **not** harm your search ranking if implemented correctly. + +To implement this functionality, you need to do the following: + +1. Enable passing a `pathname` prop to your SEO component +1. Prefix your `pathname` prop with your `siteUrl` (from `gatsby-config.js`) + - A canonical link should be _absolute_ (e.g. https://your-site.com/canonical-link), so you will need to prefix with this `siteUrl` +1. Tie into the `link` prop of `react-helmet` to create a `` tag + +```js:title=src/components/seo.js +import React from "react" +import PropTypes from "prop-types" +import Helmet from "react-helmet" +import { useStaticQuery, graphql } from "gatsby" + +// highlight-next-line +function SEO({ description, lang, meta, image: metaImage, title, pathname }) { + const { site } = useStaticQuery( + graphql` + query { + site { + siteMetadata { + title + description + author + keywords + siteUrl + } + } + } + ` + ) + + const metaDescription = description || site.siteMetadata.description + const image = + metaImage && metaImage.src + ? `${data.site.siteMetadata.siteUrl}${metaImage.src}` + : null + // highlight-start + const canonical = pathname + ? `${data.site.siteMetadata.siteUrl}${pathname}` + : null + // highlight-end + + return ( + + ) +} + +SEO.defaultProps = { + lang: `en`, + meta: [], + description: ``, +} + +SEO.propTypes = { + description: PropTypes.string, + lang: PropTypes.string, + meta: PropTypes.arrayOf(PropTypes.object), + title: PropTypes.string.isRequired, + image: PropTypes.shape({ + src: PropTypes.string.isRequired, + height: PropTypes.string.isRequired, + width: PropTypes.string.isRequired, + }), + // highlight-next-line + pathname: PropTypes.string, +} + +export default SEO +``` + +Woo hoo! Lots to digest here, but you've enabled adding an _absolute_ canonical link by passing in a `pathname` prop and prefixing with `siteUrl`. + +To bring it all home, it's time to begin actually _using_ this extensible SEO component to show all of these moving parts coming together to deliver a great SEO experience. + +## Using the SEO component + +You created an extensible SEO component. It takes a `title` prop and then (optionally) `description`, `meta`, `image`, and `pathname` props. + +### In a page component + +```js:title=src/pages/index.js +import React from "react" + +import Layout from "../components/layout" +import SEO from "../components/seo" // highlight-line + +function Index() { + return ( + + {/* highlight-line */} +

lol - pretend this is meaningful content

+ + ) +} + +export default Index +``` + +### In a template + +In many cases, you want to build a Markdown powered blog (see: [this tutorial][gatsby-markdown-blog] for more info). Of course, you want some nice SEO as well as a nifty image for sharing on Twitter, Facebook, and Slack. The following steps are needed: + +- Create a Markdown post +- Add an image, and add it to the Markdown posts frontmatter +- Query this image with GraphQL + +#### Creating the post + +```shell +mkdir -p content/blog/2019-01-04-hello-world-seo +touch content/blog/2019-01-04-hello-world-seo/index.md +``` + +```md:title=content/blog/2019-01-04-hello-world-seo/index.md +--- +date: 2019-01-04 +featured: images/featured.jpg +--- + +Hello World! +``` + +#### Adding the image + +Let's see how an attached image will look like. For this tutorial, you can use the following image: + +![Scribble stones forming SEO](./images/seo.jpg) + +The image will need to be located at `content/blog/2019-01-04-hello-world-seo/images/featured.jpg`. + +Make sure to use appropriately sized images for social sharing. Facebook and Twitter have restrictions beyond which they will simply ignore your image. + +#### Querying with GraphQL + +```js:title=src/templates/blog-post.js +import React from "react" +import { Link, graphql } from "gatsby" + +import Bio from "../components/bio" +import Layout from "../components/layout" +import SEO from "../components/seo" // highlight-line +import { rhythm, scale } from "../utils/typography" + +class BlogPostTemplate extends React.Component { + render() { + const post = this.props.data.markdownRemark + const siteTitle = this.props.data.site.siteMetadata.title + const { previous, next } = this.props.pageContext + const image = post.frontmatter.image + ? post.frontmatter.image.childImageSharp.resize + : null // highlight-line + + return ( + + {/* highlight-start */} + + {/* highlight-end */} +

{post.frontmatter.title}

+
+ + ) + } +} + +export default BlogPostTemplate + +export const pageQuery = graphql` + # highlight-start + query BlogPostBySlug($slug: String!) { + site { + siteMetadata { + title + author + } + } + markdownRemark(fields: { slug: { eq: $slug } }) { + id + excerpt(pruneLength: 160) + html + frontmatter { + title + description + image: featured { + childImageSharp { + resize(width: 1200) { + src + height + width + } + } + } + } + } + } + # highlight-end +` +``` + +There are a few aspects worth nothing here: + +- You're using `pruneLength: 160` for the excerpt; this is because [SEO meta descriptions should be between 150-170 characters][seo-description-length] + +- This is a slick feature of Gatsby's GraphQL capabilities, and will truncate (e.g. with a trailing `...`) appropriately. Perfect! + +- The image query is intentionally simplified, but a good base to build upon. There are specific size and aspect ratio requirements for [both Facebook][facebook-og-image] and [Twitter][twitter-image]. + +## The Payoff + +Using the techniques outlined in this post, you've made your Gatsby application SEO-friendly as well as sharable on common social networks. Check out the following examples of a sample blog post. + +### Google + +![Indexing Results by Google](./images/google.png) + +### Facebook + +![Social Sharing Card as on Facebook](./images/facebook.png) + +### Twitter + +![Social Sharing Card as on Twitter](./images/twitter.png) + +### Slack + +![Social Sharing Card as on Slack](./images/slack.png) + +To learn more about these validations, check out how to _validate_ SEO with the following tools from [Google][google-validation], [Twitter][twitter-validation], and [Facebook][facebook-validation]. + +The SEO resources outlined in this tutorial aren't _only_ a best practice, they're also a best practice enabled, by default. Available **today** in `gatsby-starter-default`, use: + +```shell +npm gatsby new my-new-gatsby-app +``` + +and you'll have the `SEO` component available to maximize your SEO and social sharing capabilities. Check it out! + +## Further Learning + +This tutorial is merely a shallow dive into the depths of SEO. Consider it a primer for further learning and a gentle introduction to some SEO concepts with a Gatsby twist. To truly master these concepts is outside the scope of this tutorial, but it truly is fascinating stuff that can directly lead to more eyes on your content! + +### References + +- Facebook uses the [Open Graph][og] tag format +- Twitter uses `twitter:` keywords. See [Twitter Cards][twitter-cards] for more info +- Slack reads tags in the following order ([source][slack-unfurl]) + 1. oEmbed server + 1. Twitter cards tags / Facebook Open Graph tags + 1. HTML meta tags +- Both [Google][google-json-ld] and [Apple][apple-json-ld] offer support for JSON-LD, which is _not covered_ in this guide + - If you'd like to learn more, check out [this excellent guide](https://nystudio107.com/blog/json-ld-structured-data-and-erotica) for more info on JSON-LD +- Check out the [`gatsby-seo-example`][gatsby-seo-example] for a ready-to-use starter for powering your Markdown-based blog. + +[gatsby-starter-default]: https://github.com/gatsbyjs/gatsby-starter-default +[gatsby-static-query]: /docs/static-query/ +[gatsby-markdown-blog]: /docs/adding-markdown-pages/ +[gatsby-plugin-react-helmet]: /packages/gatsby-plugin-react-helmet/ +[react-helmet]: https://github.com/nfl/react-helmet +[unstructured-data]: /docs/using-gatsby-without-graphql/ +[og]: https://developers.facebook.com/docs/sharing/webmasters/#markup +[twitter-cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards.html +[seo-description-length]: https://yoast.com/shorter-meta-descriptions/ +[facebook-og-image]: https://developers.facebook.com/docs/sharing/best-practices#images +[twitter-image]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/summary-card-with-large-image.html +[slack-unfurl]: https://medium.com/slack-developer-blog/everything-you-ever-wanted-to-know-about-unfurling-but-were-afraid-to-ask-or-how-to-make-your-e64b4bb9254 +[google-validation]: https://support.google.com/webmasters/answer/6066468?hl=en +[twitter-validation]: https://cards-dev.twitter.com/validator +[facebook-validation]: https://developers.facebook.com/tools/debug/sharing +[gatsby-seo-example]: https://github.com/DSchau/gatsby-seo-example +[google-json-ld]: https://developers.google.com/search/docs/guides/intro-structured-data +[apple-json-ld]: https://developer.apple.com/library/archive/releasenotes/General/WhatsNewIniOS/Articles/iOS10.html#//apple_ref/doc/uid/TP40017084-DontLinkElementID_2 From 8dfb05eb53b832956778b664b993cd4970bcbd02 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 5 Mar 2020 16:48:14 +0000 Subject: [PATCH 040/127] sync with monorepo gatsbyjs/gatsby@8eb238ec6a4ddff80bcfc2ee35a271c54960faf7 - [eCom Tutorial] Refactor to function components and use `loadStripe` helper. (#21675) * Refactor to function components and use loadStripe helper. * e-commerce capitalization and relative links * Review updates. * Add repor to examples directory. * Remove unecessary files from example * Remove unecessary files from example * chore: format * Replace blurry screenshot * Reduce PNG size Co-authored-by: Aisha Blake Co-authored-by: GatsbyJS Bot --- docs/tutorial/ecommerce-tutorial/index.md | 319 +++++++++------------- 1 file changed, 122 insertions(+), 197 deletions(-) diff --git a/docs/tutorial/ecommerce-tutorial/index.md b/docs/tutorial/ecommerce-tutorial/index.md index c87ee4891..05b5518fc 100644 --- a/docs/tutorial/ecommerce-tutorial/index.md +++ b/docs/tutorial/ecommerce-tutorial/index.md @@ -1,18 +1,20 @@ --- -title: "Gatsby e-commerce Tutorial" +title: "Gatsby E-commerce Tutorial" --- In this advanced tutorial, you’ll learn how to use Gatsby to build the UI for a basic e-commerce site that can accept payments, with [Stripe](https://stripe.com) as the backend for processing payments. +- Demo running [on Netlify](https://gatsby-ecommerce-stripe.netlify.com/) +- Code hosted [on GitHub](https://github.com/gatsbyjs/gatsby/tree/master/examples/ecommerce-tutorial-with-stripe) + ## Why use Gatsby for an e-commerce site? Benefits of using Gatsby for e-commerce sites include the following: -- Security inherent in static sites -- Blazing fast performance when your pages are converted from React into static files -- Easy to host - -You can see the working demo hosted here: https://gatsby-ecommerce-stripe.netlify.com/ +- Security inherent in static sites. +- Blazing fast performance when your pages are converted from React into static files. +- No server component required with Stripe's [client-only Checkout](https://stripe.com/docs/payments/checkout/client-only). +- Cost-efficient hosting of static sites. ## Prerequisites @@ -21,11 +23,9 @@ You can see the working demo hosted here: https://gatsby-ecommerce-stripe.netlif ### How does Gatsby work with Stripe? -Stripe is a payment processing service that allows you to securely collect and process payment information from your customers. To try out Stripe for yourself, go to [Stripe’s Quick Start Guide](https://stripe.com/docs/payments/checkout#tryout). - -There are alternatives to Stripe, like Square and Braintree, and their setup is very similar to Stripe. +Stripe is a payment processing service that allows you to securely collect and process payment information from your customers. To try out Stripe for yourself, go to [Stripe’s Quick Start Guide](https://stripe.com/docs/payments/checkout#try-now). -Stripe offers a [hosted checkout](https://stripe.com/docs/payments/checkout) that doesn't require any backend component. You can configure products, SKUs, and subscription plans in the [Stripe Dashboard](https://stripe.com/docs/payments/checkout#configure). If you're selling a single product or subscription (like an eBook) you can hardcode the product's SKU ID in your Gatsby site. If you're selling multiple products, you can use the [Stripe source plugin](https://www.gatsbyjs.org/packages/gatsby-source-stripe/) to retrieve all SKUs at build time. If you want your Gatsby site to automatically update, you can use the Stripe webhook event to [trigger a redeploy](https://www.netlify.com/docs/webhooks/) when a new product or SKU is added. +Stripe offers a [hosted checkout](https://stripe.com/docs/payments/checkout) that doesn't require any backend component. You can configure products, SKUs, and subscription plans in the [Stripe Dashboard](https://stripe.com/docs/payments/checkout#configure). If you're selling a single product or subscription (like an eBook) you can hardcode the product's SKU ID in your Gatsby site. If you're selling multiple products, you can use the [Stripe source plugin](/packages/gatsby-source-stripe/) to retrieve all SKUs at build time. If you want your Gatsby site to automatically update, you can use the Stripe webhook event to [trigger a redeploy](https://www.netlify.com/docs/webhooks/) when a new product or SKU is added. ## Setting up a Gatsby site @@ -36,68 +36,27 @@ gatsby new ecommerce-gatsby-tutorial cd ecommerce-gatsby-tutorial ``` -## Installing the StripeJS plugin - -You can extend the functionality of this default starter with plugins. One such plugin is `gatsby-plugin-stripe`, which you’ll install in this project: - -```shell -npm install gatsby-plugin-stripe -``` - -Open the root site directory in a text editor and navigate to `gatsby-config.js` and add the StripeJS plugin to `gatsby-config.js` in the plugins section. Your `gatsby-config.js` should look like the following code example: - -```js:title=gatsby-config.js -module.exports = { - siteMetadata: { - 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`, - { - 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`, - ], -} -``` - ### See your site hot reload in the browser! -Run `npm run develop` in the terminal, which starts a development server and reloads changes you make to your site so you can preview them in the browser. Open up your browser to `http://localhost:8000/` and you should see a default homepage. +Run `gatsby develop` in the terminal, which starts a development server and reloads changes you make to your site so you can preview them in the browser. Open up your browser to `http://localhost:8000/` and you should see a default homepage. -> **NOTE**: If you have already started your Gatsby development server using `npm run develop`, you will need to restart the server by pressing CTRL + C in the terminal where the command was run and running `npm run develop` again to see changes in your `gatsby-config.js` reflected on `http://localhost:8000/` +### Loading Stripe.js -### How does the StripeJS plugin work? +Stripe provides a JavaScript library that allows you to securely redirect your customer to the Stripe hosted checkout page. Due to [PCI compliance requirements](https://stripe.com/docs/security), the Stripe.js library has to be loaded from Stripe's servers. Stripe provides a [loading wrapper](https://github.com/stripe/stripe-js) that allows you to import Stripe.js like an ES module: -Stripe provides a JavaScript library the allows you to securely redirect your customer to the Stripe hosted checkout page. The Gatsby plugin, `gatsby-plugin-stripe`, will add this snippet: +```js +import { loadStripe } from "@stripe/stripe-js" -```html - +const stripe = await loadStripe("pk_test_TYooMQauvdEDq54NiTphI7jx") ``` -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). +Stripe.js is loaded as a side effect of the `import '@stripe/stripe-js';` statement. To best leverage Stripe’s advanced fraud functionality, ensure that Stripe.js is loaded on every page of your customer's checkout journey, not just your checkout page. This allows Stripe to detect anomalous behavior that may be indicative of fraud as customers browse your website. -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). +To make use of this, install the `stripe-js` module: + +```shell +npm install @stripe/stripe-js +``` ### Getting your Stripe test keys @@ -114,36 +73,35 @@ While testing, you must use the key(s) that include _test_. For production code, ### Enabling the "Checkout client-only integration" for your Stripe account -Through this tutorial you will be using the "Checkout client-only integration" from Stripe. To use this integration you need to activate it on the corresponding [Checkout settings](https://dashboard.stripe.com/account/checkout/settings) from your Stripe Dashboard. +In this tutorial you will be using Stripe Checkout in client-only mode. You need to enable client-only mode in the [Checkout settings](https://dashboard.stripe.com/account/checkout/settings). ![Stripe control to enable the Checkout client-side only integration highlighted](stripe-checkout-clientside-functionality.png) > 💡 This change will also modify the interface that Stripe provides to administer your products: keep this in mind in case you have previously used this tool. If you have never used the product administrator, you don't need to worry. -Additionally, you need to set a name for your Stripe account on your [Account settings](https://dashboard.stripe.com/account) to use this integration. - -To learn more about this integration you may use the [Stripe docs](https://stripe.com/docs/payments/checkout#configure). +Additionally, you need to set a name for your Stripe account in your [Account settings](https://dashboard.stripe.com/account). You can find more configuration details in the [Stripe docs](https://stripe.com/docs/payments/checkout#configure). ## Examples -You can find an implementation of these examples [on GitHub](https://github.com/thorsten-stripe/ecommerce-gatsby-tutorial). +You can find an implementation of these examples [on GitHub](https://github.com/gatsbyjs/gatsby/tree/master/examples/ecommerce-tutorial-with-stripe). -### Easy: One Button +### Example 1: One Button -If you're selling a simple product, like an eBook for example, you can create a single button that will perform a redirect to the Stripe Checkout page: +If you're selling a single product, like an eBook for example, you can create a single button that will perform a redirect to the Stripe Checkout page: #### Create a product and SKU -To sell your products, first you need to create them on Stripe using the [Stripe Dashboard](https://dashboard.stripe.com/products) or the [Stripe API](https://stripe.com/docs/api/products/create). This is required for Stripe to validate that the request coming from the frontend is legitimate and to charge the right amount for the selected product/SKU. Stripe requires every SKU used with Stripe Checkout to have a name: be sure to add one to all of your SKUs. +To sell your products, you need to create them in your Stripe account using the [Stripe Dashboard](https://dashboard.stripe.com/products) or the [Stripe API](https://stripe.com/docs/api/products/create). This is required for Stripe to validate that the request coming from the frontend is legitimate and to charge the correct amount for the selected product/SKU. Stripe requires every SKU used with Stripe Checkout to have a name: be sure to add one to all of your SKUs. -You will need to create both test and live product SKUs in the Stripe Dashboard. Make sure you toggle to "Viewing test data" and then create your products for local development. +You will need to create both test and live product SKUs separately in the Stripe Dashboard. Make sure you toggle to "Viewing test data", then create your products for local development. -#### Create a checkout component that loads StripeJS and redirects to the checkout +#### Create a checkout component that loads Stripe.js and redirects to the checkout Create a new file at `src/components/checkout.js`. Your `checkout.js` file should look like this: ```jsx:title=src/components/checkout.js import React from "react" +import { loadStripe } from "@stripe/stripe-js" const buttonStyles = { fontSize: "13px", @@ -157,37 +115,28 @@ const buttonStyles = { letterSpacing: "1.5px", } -const Checkout = class extends React.Component { - // Initialise Stripe.js with your publishable key. - // You can find your key in the Dashboard: - // https://dashboard.stripe.com/account/apikeys - componentDidMount() { - this.stripe = window.Stripe("pk_test_jG9s3XMdSjZF9Kdm5g59zlYd") - } +const stripePromise = loadStripe("pk_test_jG9s3XMdSjZF9Kdm5g59zlYd") - async redirectToCheckout(event) { - event.preventDefault() - const { error } = await this.stripe.redirectToCheckout({ - items: [{ sku: "sku_DjQJN2HJ1kkvI3", quantity: 1 }], - successUrl: `http://localhost:8000/page-2/`, - cancelUrl: `http://localhost:8000/`, - }) +const redirectToCheckout = async event => { + event.preventDefault() + const stripe = await stripePromise + const { error } = await stripe.redirectToCheckout({ + items: [{ sku: "sku_DjQJN2HJ1kkvI3", quantity: 1 }], + successUrl: `http://localhost:8000/page-2/`, + cancelUrl: `http://localhost:8000/`, + }) - if (error) { - console.warn("Error:", error) - } + if (error) { + console.warn("Error:", error) } +} - render() { - return ( - - ) - } +const Checkout = () => { + return ( + + ) } export default Checkout @@ -195,48 +144,40 @@ 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 initialize the Stripe.js client. It looks like this: +You imported React, created a function component that returns a button with some styles, and added a `redirectToCheckout` handler that is executed when the button is clicked. The `loadStripe` function returns a Promise that resolves with a newly created Stripe object once Stripe.js has loaded. ```jsx:title=src/components/checkout.js - componentDidMount() { - this.stripe = window.Stripe("pk_test_jG9s3XMdSjZF9Kdm5g59zlYd") - } +const stripePromise = loadStripe("pk_test_jG9s3XMdSjZF9Kdm5g59zlYd") ``` This identifies you with the Stripe platform, validates the checkout request against your products and security settings, and processes the payment on your Stripe account. ```jsx:title=src/components/checkout.js - async redirectToCheckout(event) { - event.preventDefault() - const { error } = await this.stripe.redirectToCheckout({ - items: [{ sku: "sku_DjQJN2HJ1kkvI3", quantity: 1 }], - successUrl: `http://localhost:8000/page-2/`, - cancelUrl: `http://localhost:8000/`, - }) +const redirectToCheckout = async event => { + event.preventDefault() + const stripe = await stripePromise + const { error } = await stripe.redirectToCheckout({ + items: [{ sku: "sku_DjQJN2HJ1kkvI3", quantity: 1 }], + successUrl: `http://localhost:8000/page-2/`, + cancelUrl: `http://localhost:8000/`, + }) - if (error) { - console.warn("Error:", error) - } + if (error) { + console.warn("Error:", error) } +} ``` The `redirectToCheckout()` function validates your checkout request and either redirects to the Stripe hosted checkout page or resolves with an error object. Make sure to replace `successUrl` and `cancelUrl` with the appropriate URLs for your application. ```jsx:title=src/components/checkout.js - render() { - return ( - - ) - } +return ( + +) ``` -The `render()` function applies your styles to the button and binds the `redirectToCheckout()` function to the button's onclick event. - #### Importing the checkout component into the homepage Now go to your `src/pages/index.js` file. This is your homepage that shows at the root URL. Import your new checkout component in the file underneath the other imports and add your `` component within the `` element. Your `index.js` file should now look similar to this: @@ -268,15 +209,15 @@ const IndexPage = () => ( export default IndexPage ``` -If you go back to `http://localhost:8000/` in your browser and you have `npm run develop` running, you should now see a big, enticing "BUY MY BOOK" button. C'mon and give it a click! +If you go back to `http://localhost:8000/` in your browser and you have `gatsby develop` running, you should now see a big, enticing "BUY MY BOOK" button. C'mon and give it a click! -### Advanced: Import SKUs via source plugin +### Example 2: Import SKUs via source plugin -Instead of hardcoding the SKU IDs, you can use the [gatsby-source-stripe plugin](https://www.gatsbyjs.org/packages/gatsby-source-stripe/) to retrieve your SKUs at build time. +Instead of hardcoding the SKU IDs, you can use the [gatsby-source-stripe plugin](/packages/gatsby-source-stripe/) to retrieve your SKUs at build time. #### Add the Stripe source plugin -Add the [gatsby-source-stripe plugin](https://www.gatsbyjs.org/packages/gatsby-source-stripe/) which you can use to pull in the SKUs from your Stripe account. +Add the [gatsby-source-stripe plugin](/packages/gatsby-source-stripe/) which you can use to pull in the SKUs from your Stripe account. ```shell npm install gatsby-source-stripe @@ -291,13 +232,12 @@ module.exports = { }, plugins: [ `gatsby-plugin-react-helmet`, - "gatsby-plugin-stripe", { resolve: `gatsby-source-stripe`, options: { objects: ["Sku"], secretKey: process.env.STRIPE_SECRET_KEY, - downloadFiles: true, + downloadFiles: false, }, }, ], @@ -367,7 +307,7 @@ export default props => ( ) ``` -You can validate your query and see what data is being returned in GraphiQL, which is available at `http://localhost:8000/___graphql` when running `npm run develop`. +You can validate your query and see what data is being returned in GraphiQL, which is available at `http://localhost:8000/___graphql` when running `gatsby develop`. Once you're happy with your query, create a new page where you can import the newly created Sku component: @@ -433,13 +373,14 @@ const formatPrice = (amount, currency) => { return numberFormat.format(price) } -const SkuCard = class extends React.Component { - async redirectToCheckout(event, sku, quantity = 1) { +const SkuCard = ({ sku, stripePromise }) => { + const redirectToCheckout = async (event, sku, quantity = 1) => { event.preventDefault() - const { error } = await this.props.stripe.redirectToCheckout({ + const stripe = await stripePromise + const { error } = await stripe.redirectToCheckout({ items: [{ sku, quantity }], - successUrl: `http://localhost:8000/page-2/`, - cancelUrl: `http://localhost:8000/advanced`, + successUrl: `${window.location.origin}/page-2/`, + cancelUrl: `${window.location.origin}/advanced`, }) if (error) { @@ -447,34 +388,32 @@ const SkuCard = class extends React.Component { } } - render() { - const sku = this.props.sku - return ( -
-

{sku.attributes.name}

-

Price: {formatPrice(sku.price, sku.currency)}

- -
- ) - } + return ( +
+

{sku.attributes.name}

+

Price: {formatPrice(sku.price, sku.currency)}

+ +
+ ) } export default SkuCard ``` -This component renders a neat card for each individual SKU, with the SKU name, nicely formatted pricing, and a "BUY ME" button. The button triggers the `redirectToCheckout()` function with the corresponding SKU ID. +This component renders a neat card for each individual SKU, with the SKU name, nicely formatted pricing, and a "BUY ME" button. The button triggers the `redirectToCheckout` function with the corresponding SKU ID. -Lastly, you need to refactor your `Skus` component to initialize the Stripe.js client, and render `SkuCards` while handing down the Stripe.js client in the `props`: +Lastly, you need to refactor your `Skus` component to `loadStripe`, and render `SkuCards` while handing down the Stripe promise in the `props`: ```jsx:title=src/components/Products/Skus.js -import React, { Component } from "react" +import React from "react" import { graphql, StaticQuery } from "gatsby" -import SkuCard from "./SkuCard" // highlight-line +import SkuCard from "./SkuCard" +import { loadStripe } from "@stripe/stripe-js" const containerStyles = { display: "flex", @@ -484,50 +423,36 @@ const containerStyles = { padding: "1rem 0 1rem 0", } -class Skus extends Component { - // Initialise Stripe.js with your publishable key. - // You can find your key in the Dashboard: - // https://dashboard.stripe.com/account/apikeys - // highlight-start - state = { - stripe: null, - } - - componentDidMount() { - const stripe = window.Stripe(process.env.GATSBY_STRIPE_PUBLIC_KEY) - this.setState({ stripe }) - } - // highlight-end - - render() { - return ( - { + return ( + ( -
- {skus.edges.map(({ node: sku }) => ( - {/* highlight-line */} - ))} -
- )} - /> - ) - } + } + `} + render={({ skus }) => ( +
+ {skus.edges.map(({ node: sku }) => ( + + ))} +
+ )} + /> + ) } export default Skus From b4c3604154071badeb04afb024a893649b300f7b Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 6 Mar 2020 16:53:29 +0000 Subject: [PATCH 041/127] sync with monorepo gatsbyjs/gatsby@096c28d7a421d782f6759f42c7eafeeab4f16ea1 - feature(gatsby): Add gatsby feedback (#21841) * Create feedback command * progress with prompting heuristics * Finish heuristic * Finish hueristics and add tests * start hooking up feedback to cli commands * Finish implementation * Add an additional random selection heuristic * update message * add try/catch * Add documentation * Update docs/docs/feedback.md Co-Authored-By: LB * Update docs/docs/feedback.md Co-Authored-By: LB * fix feedback cli issues * rename files * fix lint * disable code to see if CI passes * try to run with more memory * pass tests Co-authored-by: LB --- docs/docs/cli-feedback.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/docs/cli-feedback.md diff --git a/docs/docs/cli-feedback.md b/docs/docs/cli-feedback.md new file mode 100644 index 000000000..48a0883a3 --- /dev/null +++ b/docs/docs/cli-feedback.md @@ -0,0 +1,9 @@ +--- +title: Gatsby CLI Feedback +--- + +Gatsby users will be prompted every 3 months (at the most) to give feedback to Gatsby on our products and services. This feedback is incredibly valuable and will help us shape Gatsby. + +## How to opt-out + +Users may always opt-out from the feedback prompts with `gatsby feedback --disable` or by setting the environment variable `GATSBY_TELEMETRY_DISABLED` to `1` From 807d74947e6b19c4defc56bf1f3c7ef84df6a4eb Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 6 Mar 2020 19:46:13 +0000 Subject: [PATCH 042/127] sync with monorepo gatsbyjs/gatsby@1a09edb98440bc2f951e2a9b287efc17e4a84c6f - docs(style guide): new section about internal links (#21871) * fix * Update docs/contributing/gatsby-style-guide.md Co-Authored-By: LB * Update docs/contributing/gatsby-style-guide.md Co-Authored-By: LB * full url Co-authored-by: LB Co-authored-by: gatsbybot --- docs/contributing/gatsby-style-guide.md | 30 +++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/contributing/gatsby-style-guide.md b/docs/contributing/gatsby-style-guide.md index 9f6ea52e7..be269524e 100644 --- a/docs/contributing/gatsby-style-guide.md +++ b/docs/contributing/gatsby-style-guide.md @@ -126,19 +126,45 @@ Hyperlinks should contain the clearest words to indicate where the link will lea ```markdown -[Gatsby's docs](https://www.gatsbyjs.org/docs/) +[Gatsby Cloud](https://www.gatsbyjs.com/cloud/) -[here](https://www.gatsbyjs.org/docs/ "Gatsby's docs") +[here](https://www.gatsbyjs.com/cloud/ "Gatsby Cloud") ``` 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. +### Use relative hyperlinks for local links + +When referencing another page within [gatsbyjs.org](https://www.gatsbyjs.org/) hyperlinks should use relative paths (not include the full domain). This guarantees that all links function when running locally or in preview. + +```markdown + + +[Gatsby's glossay](/docs/glossary) + + + +[Gatsby's glossay](https://www.gatsbyjs.org/docs/glossary) +``` + +Note: Links to Gatsby Cloud/Gatsby Inc. are located at [gatsbyjs.com](https://www.gatsbyjs.com/) and should be referenced using an absolute path (domain included). See also [Referencing Gatsby Cloud](#referencing-gatsby-cloud) + ### 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. +```markdown + + +open your site with `http://localhost:8000/` + + + +open your site with [http://localhost:8000/](http://localhost:8000/) +``` + ### 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." From 6742615401729ba6ed4a75546cfee11523545c7b Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 6 Mar 2020 21:18:29 +0000 Subject: [PATCH 043/127] sync with monorepo gatsbyjs/gatsby@5542a66e48e1eac7587f094cf255cafb336a5012 - fix (#22021) --- docs/docs/profiling-site-performance-with-react-profiler.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/profiling-site-performance-with-react-profiler.md b/docs/docs/profiling-site-performance-with-react-profiler.md index 53cc73da4..3ae4c640d 100644 --- a/docs/docs/profiling-site-performance-with-react-profiler.md +++ b/docs/docs/profiling-site-performance-with-react-profiler.md @@ -28,7 +28,7 @@ The react profiler component can be used anywhere in a react tree to measure the ### Profiling a slow component -```js +```jsx import * as React from "react" import { Profiler } from "react" @@ -44,7 +44,7 @@ export const MyComponent = props => ( Capturing page performance can be achieved by using the [wrapPageElement API](/docs/browser-apis/#wrapPageElement) to profile each page. -```js +```jsx //gatsby-browser.js import * as React from "react" From e47b38d7d14b41dc065f697ac4522e6424e724c0 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 9 Mar 2020 13:37:53 +0000 Subject: [PATCH 044/127] sync with monorepo gatsbyjs/gatsby@315ee1c5b86639eb2daf503f19253a9ed935d854 - chore(docs): reformat tutorial - part zero (#21988) * fix * reformat * Revert "fix" This reverts commit e07838ce * combine 2 sections into one Co-authored-by: gatsbybot --- docs/tutorial/part-zero/index.md | 177 +++++++++++++++++++++++-------- 1 file changed, 134 insertions(+), 43 deletions(-) diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md index f90f27b97..a4389a90a 100644 --- a/docs/tutorial/part-zero/index.md +++ b/docs/tutorial/part-zero/index.md @@ -12,7 +12,8 @@ The command line is a text-based interface used to run commands on your computer Take a moment to locate and open up the command line interface (CLI) for your computer. Depending on which operating system you are using, see [**instructions for Mac**](http://www.macworld.co.uk/feature/mac-software/how-use-terminal-on-mac-3608274/), [**instructions for Windows**](https://www.lifewire.com/how-to-open-command-prompt-2618089) or [**instructions for Linux**](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/). -_Note: If you’re new to the command line, "running" a command, means "writing a given set of instructions in your command prompt, and hitting the Enter key". Commands will be shown in a highlighted box, something like `node --version`, but not every highlighted box is a command! If something is a command it will be mentioned as something you have to run/execute._ +_**Note:** If you’re new to the command line, "running" a command, means "writing a given set of instructions in your command prompt, and hitting the Enter key". Commands will be shown in a highlighted box, someth +ing like `node --version`, but not every highlighted box is a command! If something is a command it will be mentioned as something you have to run/execute._ ## Install Node.js for your appropriate operating system @@ -25,22 +26,38 @@ To install Gatsby and Node.js on a Mac, it is recommended to use [Homebrew](http #### How to install or verify Homebrew on your computer: 1. Open your Terminal. -2. See if Homebrew is installed by running `brew -v`. You should see "Homebrew" and a version number. +2. See if Homebrew is installed. You should see "Homebrew" and a version number. + +```shell +brew -v +``` + 3. If not, download and install [Homebrew with the instructions](https://docs.brew.sh/Installation). 4. Once you've installed Homebrew, repeat step 2 to verify. #### Install Xcode Command Line Tools: 1. Open your Terminal. -2. Install Xcode Command line tools by running `xcode-select --install`. - - If that fails, download it [directly from Apple's site](https://developer.apple.com/download/more/), after signing-in with an Apple developer account +2. Install Xcode Command line tools by running: + +```shell +xcode-select --install +``` + +> 💡 If that fails, download it [directly from Apple's site](https://developer.apple.com/download/more/), after signing-in with an Apple developer account. + 3. After being prompted to start the installation, you'll be prompted again to accept a software license for the tools to download. #### Install Node 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. +2. Install node with Homebrew: + +```shell +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. ### Windows Instructions @@ -50,33 +67,88 @@ To install Gatsby and Node.js on a Mac, it is recommended to use [Homebrew](http Install nvm (Node Version Manager) and needed dependencies. nvm is used to manage Node.js and all its associated versions. -_💡 If when installing a package, it asks for confirmation, type `y` and press enter._ +> 💡 When installing a package, if it asks for confirmation, type `y` and press enter. + +Select your distro: + +- [Ubuntu, Debian, and other apt based distros](#ubuntu-debian-and-other-apt-based-distros) +- [Arch, Manjaro and other pacman based distros](#arch-manjaro-and-other-pacman-based-distros) +- [Fedora, RedHat, and other dnf based distros](#fedora-redhat-and-other-dnf-based-distros) + +> 💡 If the Linux distribution you are using is not listed here, please find instructions on the web. #### Ubuntu, Debian, and other `apt` based distros: -1. Run `sudo apt update` and then `sudo apt -y upgrade` to make sure your Linux distribution is ready to go. -2. Run `sudo apt-get install curl` to install curl which allows you to transfer data and download additional dependencies. -3. After it finishes installing, run `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash` to download the latest nvm version. -4. To confirm this has worked, use the following command. `nvm --version`. The output should be a version number. -5. [Set default Node.js version](#set-default-nodejs-version) +1. Make sure your Linux distribution is ready to go run an update and an upgrade: + +```shell +sudo apt update +sudo apt -y upgrade +``` + +2. Install curl which allows you to transfer data and download additional dependencies: + +```shell +sudo apt-get install curl +``` + +3. After it finishes installing, download the latest nvm version: + +```shell +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash +``` + +4. Confirm this has worked. The output should be a version number. + +```shell +nvm --version +``` + +5. Continue with the section: [Set default Node.js version](#set-default-nodejs-version) #### Arch, Manjaro and other `pacman` based distros: -1. Run `sudo pacman -Sy` to make sure your distribution is ready to go. -2. These distros come installed with curl, so you can use that to download nvm. - `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash` -3. Before using nvm, you need to install additional dependencies by running `sudo pacman -S grep awk tar`. -4. To confirm this has worked, use the following command. `nvm --version`. The output should be a version number. -5. [Set default Node.js version](#set-default-nodejs-version) +1. Make sure your distribution is ready to go: + +```shell +sudo pacman -Sy +``` + +2. These distros come installed with curl, so you can use that to download nvm: + +```shell +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash +``` + +3. Before using nvm, you need to install additional dependencies by running: + +```shell +sudo pacman -S grep awk tar +``` + +4. Confirm this has worked. The output should be a version number. + +```shell +nvm --version +``` + +5. Continue with the section: [Set default Node.js version](#set-default-nodejs-version) #### Fedora, RedHat, and other `dnf` based distros: -1. These distros come installed with curl, so you can use that to download nvm. - `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash` -2. To confirm this has worked, use the following command. `nvm --version`. The output should be a version number. -3. [Set default Node.js version](#set-default-nodejs-version) +1. These distros come installed with curl, so you can use that to download nvm: + +```shell +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash +``` + +2. Confirm this has worked. The output should be a version number. + +```shell +nvm --version +``` -If the Linux distribution you are using is not listed here, please find instructions on the web. +3. Continue with the section: [Set default Node.js version](#set-default-nodejs-version) #### Set default Node.js version @@ -87,7 +159,14 @@ nvm install 10 nvm use 10 ``` -To confirm that this worked, you can run `npm --version` and `node --version`. The output should look similar to the screenshot below, showing version numbers in response to the commands. +Confirm that this worked: + +```shell +npm --version +node --version +``` + +The output should look similar to the screenshot below, showing version numbers in response to the commands. ![Check node and npm versions in terminal](01-node-npm-versions.png) @@ -107,11 +186,19 @@ The steps to download and install Git depend on your operating system. Follow th The Gatsby CLI tool lets you quickly create new Gatsby-powered sites and run commands for developing Gatsby sites. It is a published npm package. -The Gatsby CLI is available via npm and should be installed globally by running `npm install -g gatsby-cli`. +The Gatsby CLI is available via npm and should be installed globally by running: + +```shell +npm install -g gatsby-cli +``` _**Note**: when you install Gatsby and run it for the first time, you'll see a short message notifying you about anonymous usage data that is being collected for Gatsby commands, you can read more about how that data is pulled out and used in the [telemetry doc](/docs/telemetry)._ -To see the commands available, run `gatsby --help`. +See the available commands: + +```shell +gatsby --help +``` ![Check gatsby commands in terminal](05-gatsby-help.png) @@ -122,36 +209,40 @@ To see the commands available, run `gatsby --help`. Now you are ready to use the Gatsby CLI tool to create your first Gatsby site. Using the tool, you can download “starters” (partially built sites with some default configuration) to help you get moving faster on creating a certain type of site. The “Hello World” starter you’ll be using here is a starter with the bare essentials needed for a Gatsby site. 1. Open up your terminal. -2. Run `gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world`. (_Note: Depending on your download speed, the amount of time this takes will vary. For brevity's sake, the gif below was paused during part of the install_). -3. Run `cd hello-world`. -4. Run `gatsby develop`. - - - -What just happened? +2. Create a new site from a starter: ```shell gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world ``` -- `new` is a gatsby command to create a new Gatsby project. -- Here, `hello-world` is an arbitrary title — you could pick anything. The CLI tool will place the code for your new site in a new folder called “hello-world”. -- Lastly, the GitHub URL specified points to a code repository that holds the starter code you want to use. +> 💡 What just happened? +> +> - `new` is a a gatsby command to create a new Gatsby project. +> - Here, `hello-world` is an arbitrary title — you could pick anything. The CLI tool will place the code for your new site in a new folder called “hello-world”. +> - Lastly, the GitHub URL specified points to a code repository that holds the starter code you want to use. + +> 💡 Depending on your download speed, the amount of time this takes will vary. For brevity's sake, the gif below was paused during part of the install + +3. Change into the working directory: ```shell cd hello-world ``` -- This says 'I want to change directories (`cd`) to the “hello-world” subfolder'. Whenever you want to run any commands for your site, you need to be in the context for that site (aka, your terminal needs to be pointed at the directory where your site code lives). +> 💡 This says _'I want to change directories (`cd`) to the “hello-world” subfolder'_. Whenever you want to run any commands for your site, you need to be in the context for that site (aka, your terminal needs to be pointed at the directory where your site code lives). + +4. Start the development mode: ```shell gatsby develop ``` -- This command starts a development server. You will be able to see and interact with your new site in a development environment — local (on your computer, not published to the internet). +> 💡 This command starts a development server. You will be able to see and interact with your new site in a development environment — local (on your computer, not published to the internet). + + ### View your site locally @@ -163,7 +254,7 @@ Congrats! This is the beginning of your very first Gatsby site! 🎉 You’ll be able to visit the site locally at `http://localhost:8000/` for as long as your development server is running. That’s the process you started by running the `gatsby develop` command. To stop running that process (or to “stop running the development server”), go back to your terminal window, hold down the “control” key, and then hit “c” (ctrl-c). To start it again, run `gatsby develop` again! -**Note:** If you are using VM setup like `vagrant` and/or would like to listen on your local IP address, run `gatsby develop --host=0.0.0.0`. Now, the development server listens on both `http://localhost` and your local IP. +_**Note:** If you are using VM setup like `vagrant` and/or would like to listen on your local IP address, run `gatsby develop --host=0.0.0.0`. Now, the development server listens on both `http://localhost` and your local IP._ ## Set up a code editor @@ -212,7 +303,7 @@ It’s not necessary to be an expert with these already — if you’re not, don ### What is a website? -For a comprehensive introduction to what a website is--including an intro to HTML and CSS--check out “[**Building your first web page**](https://learn.shayhowe.com/html-css/building-your-first-web-page/)”. It’s a great place to start learning about the web. For a more hands-on introduction to [**HTML**](https://www.codecademy.com/learn/learn-html), [**CSS**](https://www.codecademy.com/learn/learn-css), and [**JavaScript**](https://www.codecademy.com/learn/introduction-to-javascript), check out the tutorials from Codecademy. [**React**](https://reactjs.org/tutorial/tutorial.html) and [**GraphQL**](http://graphql.org/graphql-js/) also have their own introductory tutorials. +For a comprehensive introduction to what a website is -- including an intro to HTML and CSS -- check out “[**Building your first web page**](https://learn.shayhowe.com/html-css/building-your-first-web-page/)”. It’s a great place to start learning about the web. For a more hands-on introduction to [**HTML**](https://www.codecademy.com/learn/learn-html), [**CSS**](https://www.codecademy.com/learn/learn-css), and [**JavaScript**](https://www.codecademy.com/learn/introduction-to-javascript), check out the tutorials from Codecademy. [**React**](https://reactjs.org/tutorial/tutorial.html) and [**GraphQL**](http://graphql.org/graphql-js/) also have their own introductory tutorials. ### Learn more about the command line From 72d3edd04f02ca3e3f93af03a38cd091b99c10f4 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 9 Mar 2020 15:31:45 +0000 Subject: [PATCH 045/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@538fa798385b00ad29139671b6fbf5fcc44fb199=20-=20docs:=20Add=20?= =?UTF-8?q?MDN=20links=20to=20globals=20section=20of=20porting=20from=20CR?= =?UTF-8?q?A=20to=E2=80=A6=20(#22069)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: gatsbybot --- docs/docs/porting-from-create-react-app-to-gatsby.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/porting-from-create-react-app-to-gatsby.md b/docs/docs/porting-from-create-react-app-to-gatsby.md index 08483f980..d475fb87a 100644 --- a/docs/docs/porting-from-create-react-app-to-gatsby.md +++ b/docs/docs/porting-from-create-react-app-to-gatsby.md @@ -119,11 +119,11 @@ The `gatsby build` command also won't be able to use browser APIs, so some code Some common globals that would need to be protected are: -- `window` -- `localStorage` -- `sessionStorage` -- `navigator` -- `document` +- [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) +- [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) +- [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) +- [`navigator`](https://developer.mozilla.org/en-US/docs/Web/API/Window/navigator) +- [`document`](https://developer.mozilla.org/en-US/docs/Web/API/Document) Additionally, some packages that depend on globals existing (e.g. `react-router-dom`) may need to be [patched](/docs/debugging-html-builds/#fixing-third-party-modules) or migrated to other packages. From bac42ca4cfa68ee3d6bad55d1fa85b3d9435124e Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 9 Mar 2020 15:35:36 +0000 Subject: [PATCH 046/127] sync with monorepo gatsbyjs/gatsby@920fb1ba7fbffe49dcda164c3f8cb2ad15de2e70 - updates to Agility CMS info (#22000) * updates to Agility info * Update docs/docs/sourcing-from-agilitycms.md Accepted re-phrase suggestion Co-Authored-By: LB * ran yarn format as instructed Co-authored-by: LB --- docs/docs/sourcing-from-agilitycms.md | 14 ++++++++++---- docs/docs/troubleshooting-common-errors.md | 12 ++++++++++++ 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/docs/sourcing-from-agilitycms.md b/docs/docs/sourcing-from-agilitycms.md index 9267e636d..c1144353d 100644 --- a/docs/docs/sourcing-from-agilitycms.md +++ b/docs/docs/sourcing-from-agilitycms.md @@ -4,13 +4,19 @@ title: Sourcing from Agility CMS This guide takes you through the steps involved in setting up a Gatsby site that fetches content from [Agility CMS](https://agilitycms.com/). +Check our [docs](https://help.agilitycms.com/hc/en-us/articles/360039879872) for up-to-date documentation. + ## What is Agility CMS? What makes it different? -[Agility CMS](https://agilitycms.com/) is a headless Content Management System (CMS) that lets you define your custom content types and relationships. This is called Content Architecture, and you can reuse this content for your websites and apps. +[Agility CMS](https://agilitycms.com/) is a headless Content Management System (CMS) that lets you define your custom content types, relationships and pages. This is called Content Architecture, and you can reuse this content for your websites and apps. + +Agility believes that a successful website balances the **User Experience (UX)**, **Editor Experience (EX)**, and **Developer Experience (DX)**. + +While Gatsby tends to handle **UX** and **DX** quite well, editors are not always comfortable working directly in a codebase. They prefer to manage their sitemap and see what content is on which pages. Using Gatsby with a headless CMS allows for this. -In addition, Agility CMS provides a page routing API, which allows you to offload control of the sitemap to the content editors. +Agility aims to empower and improve the **Editor Experience** by providing built-in **Page Management**. This means developers can build UI Components and leave editors to compose their pages. -All content is available through the Agility CMS Fetch or Preview API. +[Learn more about Agility CMS and Gatsby](https://help.agilitycms.com/hc/en-us/articles/360039879872) ## Getting started @@ -60,7 +66,7 @@ If you use the `preview` key, you won't have to publish to see the changes you'v ## How it works -The Gatsby Source Plugin downloads all the Pages on the Agility CMS Sitemap, as well as any Shared Content that's referenced on the `sharedContent` property in the `gatsby-config.js` file. +The Gatsby Source Plugin will synchronize your sitemap, pages, and content for you and place it into **GraphQL**. All of those pages and content are then made available in GraphQL to the React Components you will write to render those pages. diff --git a/docs/docs/troubleshooting-common-errors.md b/docs/docs/troubleshooting-common-errors.md index 5b3d5258b..04af72386 100644 --- a/docs/docs/troubleshooting-common-errors.md +++ b/docs/docs/troubleshooting-common-errors.md @@ -224,3 +224,15 @@ The build is failing to find the file at `../..SomeFile.svg`. This can be frustr The most common culprit to prompt this issue is with filepaths having mixed capitalization. In the example above, check to make sure that the file is actually named `SomeFile.svg` and not something different like `Somefile.svg` or `somefile.svg`. Some operating systems will pick up on this discrepancy for you and find the image without any problems. Your deployment environment may not. Checking the capitalization of files output in your build logs and redeploying is the best next step. + +### Error: ENOSPC: System limit for number of file watchers reached + +You may have encountered a system limit on the number of files you can monitor. + +To fix it, increase your system's file watchers limit (which is the number of processes that check for changes to files in your site while it's running) with the following command: + +```shell +echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p +``` + +You may be able to find more information for your circumstances in [the GitHub issue corresponding to this error](https://github.com/gatsbyjs/gatsby/issues/11406). From 66559da6dbfb2d4ac44aa858290dcdb63dcac545 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 9 Mar 2020 16:36:40 +0000 Subject: [PATCH 047/127] sync with monorepo gatsbyjs/gatsby@f378060657ba8819d1cc6678c253e2ca3fd17ab7 - docs/glossary: WPGraphQL article (#21974) * docs/glossary: WPGraphQL article - Updated doc-links.yaml with link to new article. - Updated glossary.md with link to new article. * Add youtube link to demo * Remove extra words from WPGraphQL glossary * Fix typos and relative links Co-authored-by: Hashim Warren Co-authored-by: Aisha Blake Co-authored-by: gatsbybot --- docs/docs/glossary.md | 4 ++ docs/docs/glossary/wpgraphql.md | 77 +++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 docs/docs/glossary/wpgraphql.md diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index 7881591b4..a4f00d81d 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -348,6 +348,10 @@ A UI refers to a User Interface. In the field of human-computer interaction, a U A [JavaScript](#javascript) application that Gatsby uses to bundle your website's code up. This happens automatically on [build](#build). +### [WPGraphQL](/docs/glossary/wpgraphql) + +A WordPress plugin that adds [GraphQL](#graphql) capabilities to WordPress. It's another way that you can use WordPress as a content source for Gatsby. + ## X ## Y diff --git a/docs/docs/glossary/wpgraphql.md b/docs/docs/glossary/wpgraphql.md new file mode 100644 index 000000000..74d9bfdcc --- /dev/null +++ b/docs/docs/glossary/wpgraphql.md @@ -0,0 +1,77 @@ +--- +title: WPGraphQL +disableTableOfContents: true +--- + +Learn what WPGraphQL is and how to use it with Gatsby and WordPress. + +## What is WPGraphQL? + +[WPGraphQL](https://www.wpgraphql.com/) is a WordPress plugin that adds a [GraphQL](/docs/graphql/) API to your WordPress site. [GraphQL](/docs/glossary/graphql/) is a query language for requesting information from an [API](/docs/glossary#api) and a protocol for servers that support it. Gatsby [uses GraphQL](/docs/why-gatsby-uses-graphql/) to serve page data. Adding the WPGraphQL plugin to WordPress lets you use GraphQL to retrieve the specific pieces of content that you need to display on a Gatsby page. + +### Installing WPGraphQL + +You can install WPGraphQL using WordPress' _Add Plugins_ screen. You may also want to install the [WPGraphiQL](https://github.com/wp-graphql/wp-graphiql) plugin. WPGraphiQL turns the [GraphiQL IDE](/docs/running-queries-with-graphiql/) (or integrated development environment) into a WordPress plugin. You do not have to install WPGraphiQL, but it helps you explore data and create queries from WordPress' administration interface. + +1. Download [WPGraphQL](https://github.com/wp-graphql/wp-graphql) and [WPGraphiQL](https://github.com/wp-graphql/wp-graphiql) as ZIP archives from their respective GitHub repositories. +2. Upload `wp-graphql-develop.zip` and `wp-graphiql-master.zip`using the _Upload Plugin_ button on the _Add Plugins_ screen. You'll have to upload and install them one at a time. + +WPGraphQL and WPGraphiQL are also available from the [Packagist](https://packagist.org/) repository. You can install them using [Composer](https://getcomposer.org/), a package manager for PHP. + +```shell +composer require wp-graphql/wp-graphql wp-graphql/wp-graphiql +``` + +After installing WPGraphQL and WPGraphiQL, you'll need to activate them. If you've used the upload method, WordPress will display an _Activate Plugin_ button on the confirmation screen once the installation process completes. You can also activate (or deactivate) WPGraphQL and WPGraphiQL from the _Plugins_ screen. + +Once activated, you may need to update your permalink structure. WPGraphQL requires [pretty permalinks](https://wordpress.org/support/article/using-permalinks/#mod_rewrite-pretty-permalinks), and a custom permalink structure. + +Verify that WPGraphQL is working correctly by visiting the `/graphql` endpoint, relative to your WordPress home URL. If, for example, your WordPress home URL is `https://www.example.com/blog/`, the GraphQL endpoint will be `https://www.example.com/blog/graphql`. + +> **NOTE:** If you are using the `WP_SITEURL` and `WP_HOME` WordPress constants, WPGraphQL will use the value of `WP_HOME`. + +Then you can configure Gatsby to work with your new endpoint. + +### Using WPGraphQL with Gatsby + +You'll need to do two more things before you can use your WordPress-backed GraphQL server with Gatsby: + +1. install the [gatsby-source-graphql](/docs/third-party-graphql/) plugin; and +2. update `gatsby-config.js`. + +Use [npm](/docs/glossary#npm) to install [gatsby-source-graphql](/docs/third-party-graphql/). + +```shell +npm install --save gatsby-source-graphql +``` + +Then update `gatsby-config.js`. Add the plugin to your Gatsby instance. Specify the URL of the GraphQL endpoint and set other [configuration options](/packages/gatsby-source-graphql/). + +```javascript +module.exports = { + plugins: [ + { + resolve: "gatsby-source-graphql", + options: { + // Remote schema query type. This is an arbitrary name. + typeName: "WPGraphQL", + // Field name under which it will be available. Used in your Gatsby query. This is also an arbitrary name. + fieldName: "wpcontent", + // GraphQL endpoint, relative to your WordPress home URL. + url: "https://example.com/blog/graphql", + }, + }, + ], +} +``` + +Be sure to restart the development server after making these changes. Now you can use your WordPress [GraphQL API with Gatsby](/docs/graphql/) just as you would any other GraphQL source. + +WPGraphQL is one way to use Gatsby and WordPress together. It adds a flexible GraphQL API to the robust content management features of WordPress. + +### Learn more about WPGraphQL + +- [WPGraphQL](https://www.wpgraphql.com/) official site +- [Using Gatsby with WPGraphQL](https://www.youtube.com/watch?v=DH7I1xRrbxs) demo by the founder +- [What is GraphQL?](/docs/glossary/graphql/) from the Gatsby docs +- [Why Gatsby Uses GraphQL](/docs/why-gatsby-uses-graphql/) From a763432d7c5fcc3e5a2cff83ca3c17871398705b Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 9 Mar 2020 18:48:00 +0000 Subject: [PATCH 048/127] sync with monorepo gatsbyjs/gatsby@7b1a0cceb459c903dea9231848bdf7c5f1a012ce - [docs][recipes] Update to Linking Between Recipe with example + tests (#21854) * update create page recipe example * updates to Linking Between Pages recipe * add Linking Between Pages recipe example * update port to one specific to cypress tests Co-authored-by: gatsbybot --- docs/docs/recipes/pages-layouts.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/docs/recipes/pages-layouts.md b/docs/docs/recipes/pages-layouts.md index cf49f42ae..2e5427372 100644 --- a/docs/docs/recipes/pages-layouts.md +++ b/docs/docs/recipes/pages-layouts.md @@ -74,33 +74,39 @@ export default AboutPage ## Linking between pages -Routing in Gatsby relies on the `` component. +Routing for links internal to your Gatsby site relies on the `` component. ### Prerequisites - A Gatsby site with two page components: `index.js` and `contact.js` -- The Gatsby `` component - The [Gatsby CLI](/docs/gatsby-cli/) to run `gatsby develop` ### Directions -1. Open the index page component (`src/pages/index.js`), import the `` component from Gatsby, add a `` component above the header, and give it a `to` property with the value of `"/contact/"` for the pathname: +1. Open the index page component (`src/pages/index.js`) and import the `` component from Gatsby. Add a `` component to the JSX code and give it a `to` property with the pathname value of `"/contact/"` to output an HTML link with Gatsby powers: ```jsx:title=src/pages/index.js import React from "react" -import { Link } from "gatsby" +import { Link } from "gatsby" // highlight-line export default () => ( -
- Contact -

What a world.

-
+
+

What a world.

+

+ Contact // highlight-line +

+
) ``` 2. Run `gatsby develop` and navigate to the index page. You should have a link that takes you to the contact page when clicked! -> **Note**: Gatsby's `` component is a wrapper around [`@reach/router`'s Link component](https://reach.tech/router/api/Link). For more information about Gatsby's `` component, consult the [API reference for ``](/docs/gatsby-link/). +> **Note**: Gatsby's `` component is a wrapper around [`@reach/router`'s Link component](https://reach.tech/router/api/Link). It outputs an HTML anchor when rendered in a browser, with built-in JavaScript functionality for performance. For more information, consult the [API reference for ``](/docs/gatsby-link/). + +### Additional resources + +- [Linking Between Pages guide](/docs/linking-between-pages) +- [Gatsby Link API](/docs/gatsby-link) ## Creating a layout component From 202b167cc3b4f19c89dc3bf9b6bff3963acb3c3f Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 9 Mar 2020 19:05:36 +0000 Subject: [PATCH 049/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@14ac8fbfb6ca17095abcde2dcd8bb35f32011ba7=20-=20Rename=20Theme?= =?UTF-8?q?=20tutorials=20to=20Plugin=20and=20Theme=20Tutorials=20and=20up?= =?UTF-8?q?date=20redir=E2=80=A6=20(#21908)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Rename Theme tutorials to Plugin and Theme Tutorials and update redirect links * replace .md with / on links so the to path will include links * fix indentation * Update PR by removing /doc when not needed * Update docs/tutorial/theme-tutorials.md Co-authored-by: gatsbybot Co-authored-by: LB --- docs/contributing/docs-contributions.md | 2 +- docs/docs/gatsby-vendor-partnership.md | 2 +- docs/docs/naming-a-plugin.md | 2 +- docs/docs/recipes/sourcing-data.md | 2 +- docs/docs/schema-gql-type.md | 2 +- docs/docs/sourcing-from-private-apis.md | 2 +- docs/docs/themes.md | 2 +- docs/tutorial/index.md | 2 +- docs/{docs => tutorial}/pixabay-source-plugin-tutorial.md | 0 docs/{docs => tutorial}/remark-plugin-tutorial.md | 0 docs/tutorial/theme-tutorials.md | 6 ++++-- 11 files changed, 12 insertions(+), 10 deletions(-) rename docs/{docs => tutorial}/pixabay-source-plugin-tutorial.md (100%) rename docs/{docs => tutorial}/remark-plugin-tutorial.md (100%) diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md index e80712a27..4c9f68c1b 100644 --- a/docs/contributing/docs-contributions.md +++ b/docs/contributing/docs-contributions.md @@ -190,7 +190,7 @@ Sometimes it makes sense to move or rename a file as part of docs restructuring ```yaml:title=www/redirects.yaml - fromPath: /docs/source-plugin-tutorial/ - toPath: /docs/pixabay-source-plugin-tutorial/ + toPath: /tutorial/pixabay-source-plugin-tutorial/ ``` ## Claim your swag diff --git a/docs/docs/gatsby-vendor-partnership.md b/docs/docs/gatsby-vendor-partnership.md index 77120e9e5..c500b2ab6 100644 --- a/docs/docs/gatsby-vendor-partnership.md +++ b/docs/docs/gatsby-vendor-partnership.md @@ -54,7 +54,7 @@ Current partners have reported development timelines of 2-3 days when the conten If you have a GraphQL-based API, you **may not need to build an integration at all** -- Gatsby supports integration with GraphQL APIs via so-called ["schema stitching"](/blog/2018-09-25-announcing-graphql-stitching-support/). -If you have questions while building your Gatsby integrations, try reading other supporting documentation such as the [general plugin authoring guide](/docs/creating-plugins/) and [source plugin tutorial](/docs/pixabay-source-plugin-tutorial/). +If you have questions while building your Gatsby integrations, try reading other supporting documentation such as the [general plugin authoring guide](/docs/creating-plugins/) and [source plugin tutorial](/tutorial/pixabay-source-plugin-tutorial/). If you still have questions, please [raise an issue on GitHub](https://github.com/gatsbyjs/gatsby/issues), ask a question in [Discord chat](https://gatsby.dev/discord), or reach out to our team at [developer-relations@gatsbyjs.com](mailto:developer-relations@gatsbyjs.com). diff --git a/docs/docs/naming-a-plugin.md b/docs/docs/naming-a-plugin.md index b92a62c96..5e2ca82c4 100644 --- a/docs/docs/naming-a-plugin.md +++ b/docs/docs/naming-a-plugin.md @@ -14,7 +14,7 @@ There are five 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) - - Docs: [creating a remark plugin](/docs/remark-plugin-tutorial/) + - Docs: [creating a remark plugin](/tutorial/remark-plugin-tutorial/) - **`gatsby-theme-*`** — this naming convention is used for [Gatsby themes](/docs/themes/), which are a type of plugin. This naming convention is used for plugins that own a section, a page, or part of a page on a site or expose files and components for [shadowing](/docs/themes/shadowing/). - Example: [`gatsby-theme-blog`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog) - Docs: [creating a theme](/tutorial/building-a-theme/) diff --git a/docs/docs/recipes/sourcing-data.md b/docs/docs/recipes/sourcing-data.md index 07fcd0f21..264c40b1f 100644 --- a/docs/docs/recipes/sourcing-data.md +++ b/docs/docs/recipes/sourcing-data.md @@ -59,7 +59,7 @@ query MyPokemonQuery { - Walk through an example using the `gatsby-source-filesystem` plugin in [tutorial part five](/tutorial/part-five/#source-plugins) - Search available source plugins in the [Gatsby library](/plugins/?=source) -- Understand source plugins by building one in the [Pixabay source plugin tutorial](/docs/pixabay-source-plugin-tutorial/) +- Understand source plugins by building one in the [Pixabay source plugin tutorial](/tutorial/pixabay-source-plugin-tutorial/) - The createNode function [documentation](/docs/actions/#createNode) ## Sourcing Markdown data for blog posts and pages with GraphQL diff --git a/docs/docs/schema-gql-type.md b/docs/docs/schema-gql-type.md index 53c56630b..6b58f9de9 100644 --- a/docs/docs/schema-gql-type.md +++ b/docs/docs/schema-gql-type.md @@ -106,7 +106,7 @@ Now we can create a GraphQL Field declaration whose type is `AuthorYaml` (which #### Foreign Key reference (`___NODE`) -If not a mapping field, it might instead end in `___NODE`, signifying that its value is an ID that is a foreign key reference to another node in redux. Check out the [Source Plugin Tutorial](/docs/pixabay-source-plugin-tutorial/) for how this works from a user point of view. Behind the scenes, the field inference is handled by [inferFromFieldName](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/schema/infer-graphql-type.js#L204). +If not a mapping field, it might instead end in `___NODE`, signifying that its value is an ID that is a foreign key reference to another node in redux. Check out the [Source Plugin Tutorial](/tutorial/pixabay-source-plugin-tutorial/) for how this works from a user point of view. Behind the scenes, the field inference is handled by [inferFromFieldName](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/schema/infer-graphql-type.js#L204). This is actually quite similar to the mapping case above. We remove the `___NODE` part of the field name. E.g. `author___NODE` would become `author`. Then, we find our `linkedNode`. I.e given the example value for `author` (which would be an ID), we find its actual node in redux. Then, we find its type in processed types by its `internal.type`. Note, that also like in mapping fields, we can define the `linkedField` too. This can be specified via `nodeFieldname___NODE___linkedFieldName`. E.g. for `author___NODE___name`, the linkedField would be `name` instead of `id`. diff --git a/docs/docs/sourcing-from-private-apis.md b/docs/docs/sourcing-from-private-apis.md index 1eca3f5d5..3c2e4de53 100644 --- a/docs/docs/sourcing-from-private-apis.md +++ b/docs/docs/sourcing-from-private-apis.md @@ -10,7 +10,7 @@ There are 3 approaches that you can use to source data from your private API: 1. If your private API is a GraphQL API, you can use [`gatsby-source-graphql`](/packages/gatsby-source-graphql/). 2. If your private API is not a GraphQL API and you are new to GraphQL, treat the data as unstructured data and fetch it during build time, as described by the guide "[Using Gatsby without GraphQL](/docs/using-gatsby-without-graphql/)". However, as highlighted in the guide, this approach comes with some tradeoffs. -3. Create a source plugin, as described in the tutorial "[Source plugin tutorial](/docs/pixabay-source-plugin-tutorial/)". +3. Create a source plugin, as described in the tutorial "[Source plugin tutorial](/tutorial/pixabay-source-plugin-tutorial/)". ## Other considerations diff --git a/docs/docs/themes.md b/docs/docs/themes.md index 455d40f82..331b9f587 100644 --- a/docs/docs/themes.md +++ b/docs/docs/themes.md @@ -17,6 +17,6 @@ This means that the configuration and functionality isn’t directly written int ## Other resources -- [Gatsby theme tutorials](/tutorial/theme-tutorials/) +- [Gatsby theme tutorials](/tutorial/plugin-and-theme-tutorials/) - [Gatsby blog posts on themes](/blog/tags/themes) - [Plugins, Themes, and Starters](/docs/plugins-themes-and-starters/) diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 093719905..1e6c692a8 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -30,7 +30,7 @@ Gatsby themes abstract all of your default configuration (shared functionality, This means that the configuration and functionality aren’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another. -Learn more about using and building themes with the [Gatsby theme tutorials](/tutorial/theme-tutorials/). +Learn more about using and building themes with the [Gatsby theme tutorials](/tutorial/plugin-and-theme-tutorials/). ## Additional tutorials diff --git a/docs/docs/pixabay-source-plugin-tutorial.md b/docs/tutorial/pixabay-source-plugin-tutorial.md similarity index 100% rename from docs/docs/pixabay-source-plugin-tutorial.md rename to docs/tutorial/pixabay-source-plugin-tutorial.md diff --git a/docs/docs/remark-plugin-tutorial.md b/docs/tutorial/remark-plugin-tutorial.md similarity index 100% rename from docs/docs/remark-plugin-tutorial.md rename to docs/tutorial/remark-plugin-tutorial.md diff --git a/docs/tutorial/theme-tutorials.md b/docs/tutorial/theme-tutorials.md index 06f1d66c6..6bb9680bf 100644 --- a/docs/tutorial/theme-tutorials.md +++ b/docs/tutorial/theme-tutorials.md @@ -1,8 +1,10 @@ --- -title: Theme Tutorials +title: Plugin & Theme Tutorials --- -Gatsby themes are a new way to encapsulate, re-use, and compose Gatsby functionality. +Gatsby plugins are Node.js packages that implement Gatsby APIs and are commonly installed through a registry like npm. Plugins are a way to encapsulate, re-use, and compose Gatsby functionality. A good example of this concept are Gatsby themes which is a type of plugin that includes a `gatsby-config.js` file and adds pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. + +> You can refer to the [conceptual guide on plugins,theme,and starters](/docs/plugins-themes-and-starters/) for more information. In this section, you'll find tutorials for: From 0c76caa642ef0184a37f06518b5f2319d099dad5 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 10 Mar 2020 11:53:05 +0000 Subject: [PATCH 050/127] sync with monorepo gatsbyjs/gatsby@8f661eb5f3623cdf302e19a6ea2a6d3ef09ac972 - refactor(www): Update react-icons from 2.2.7 to 3.x.x (latest) (#21860) * Upgrade to react-icons@3 * add source map explorer output plugin * remove no longer used file * all react icons should be vertically aligned by default * Revert "add source map explorer output plugin" This reverts commit 4e3811f36eefd4fc310f4df51ba063a749f22bec. Co-authored-by: Michal Piechowiak --- docs/docs/gatsby-image.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/docs/gatsby-image.md b/docs/docs/gatsby-image.md index 98a91b9c0..dc5e1e1a8 100644 --- a/docs/docs/gatsby-image.md +++ b/docs/docs/gatsby-image.md @@ -129,7 +129,7 @@ file(relativePath: { eq: "images/default.jpg" }) { } ``` -Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fixed) README. +Read more about fixed image queries in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/#fixed) README. ### Images that stretch across a _fluid_ container @@ -177,18 +177,17 @@ In a query, you can specify options for fluid images. - `maxHeight`(int) - `quality` (int, default: 50) - `srcSetBreakpoints` (array of int, default: []) -- `fit` (string, default: `[sharp.fit.cover][6]`) - `background` (string, default: `rgba(0,0,0,1)`) #### Returns - `base64` (string) -- `src` (string) -- `width` (int) -- `height` (int) - `aspectRatio` (float) - `src` (string) - `srcSet` (string) +- `srcSetType` (string) +- `sizes` (string) +- `originalImg` (string) This is where fragments like `GatsbyImageSharpFluid` come in handy, as they'll return all the above items in one line without having to type them all out: @@ -204,7 +203,7 @@ file(relativePath: { eq: "images/default.jpg" }) { } ``` -Read more in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/?=#fluid) README. +Read more about fluid image queries in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/#fluid) README. ### Resized images @@ -240,15 +239,19 @@ allImageSharp { } ``` +Read more about resized image queries in the [gatsby-plugin-sharp](/packages/gatsby-plugin-sharp/#resize) README. + ### Shared query parameters -In addition to `gatsby-plugin-sharp` settings in `gatsby-config.js`, there are additional query options that apply to both _fluid_ and _fixed_ images: +In addition to `gatsby-plugin-sharp` settings in `gatsby-config.js`, there are additional query options that apply to _fluid_, _fixed_, and _resized_ images: -- `grayscale` (bool, default: false) -- `duotone` (bool|obj, default: false) -- `toFormat` (string, default: \`\`) -- `cropFocus` (string, default: `[sharp.strategy.attention][6]`) -- `pngCompressionSpeed` (int, default: 4) +- [`grayscale`](/packages/gatsby-plugin-sharp/#grayscale) (bool, default: false) +- [`duotone`](/packages/gatsby-plugin-sharp/#duotone) (bool|obj, default: false) +- [`toFormat`](/packages/gatsby-plugin-sharp/#toformat) (string, default: \`\`) +- [`cropFocus`](/packages/gatsby-plugin-sharp/#cropfocus) (string, default: `ATTENTION`) +- [`fit`](/packages/gatsby-plugin-sharp/#fit) (string, default: `COVER`) +- [`pngCompressionSpeed`](/packages/gatsby-plugin-sharp/#pngcompressionspeed) (int, default: 4) +- [`rotate`](/packages/gatsby-plugin-sharp/#rotate) (int, default: 0) Here's an example of using the `duotone` option with a fixed image: @@ -286,13 +289,13 @@ fixed(
Grayscale | Before - After
-Read more in the [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp) README. +Read more about shared image query parameters in the [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/#shared-options) README. ## Image query fragments GraphQL includes a concept called "query fragments", which are a part of a query that can be reused. To ease building with `gatsby-image`, Gatsby image processing plugins which support `gatsby-image` ship with fragments which you can easily include in your queries. -> Note: using fragments in your queries depends on which data source(s) you have configured. Read more in the [gatsby-image](/packages/gatsby-image#fragments) README. +> Note: using fragments in your queries depends on which data source(s) you have configured. Read more about image query fragments in the [gatsby-image](/packages/gatsby-image/#fragments) README. ### Common fragments with `gatsby-transformer-sharp` From f5a97e1bc05fa806a9ff6c5e5cde61249768756c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 10 Mar 2020 13:41:58 +0000 Subject: [PATCH 051/127] sync with monorepo gatsbyjs/gatsby@e1079e2f97c84cfc9ff3224a794308cfad06f153 - Fix readme links (#22134) --- docs/contributing/docs-writing-process.md | 96 +++++++++++++++++++++++ docs/contributing/gatsby-style-guide.md | 5 +- 2 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 docs/contributing/docs-writing-process.md diff --git a/docs/contributing/docs-writing-process.md b/docs/contributing/docs-writing-process.md new file mode 100644 index 000000000..6eccbe98a --- /dev/null +++ b/docs/contributing/docs-writing-process.md @@ -0,0 +1,96 @@ +--- +title: Docs Writing Process +--- + +When a new feature or integration is released that Gatsby developers can take advantage of, documentation should be added to improve the learning experience. Gatsby also needs docs for topic areas that exist in other technologies but are under-documented or under-tooled in the Gatsby ecosystem. + +The knowledge of how to work with a technique, source plugin, or varied use case may be known internally to Gatsby team members, but it also may only exist on the web at large. This contributing doc is intended to provide a written process for producing docs without prior information, a critical function of the Gatsby Learning team and open source community. + +## Identifying a topic + +When identifying a topic, start by: + +1. Looking at GitHub issues. Good labels to seek out are [`help wanted`](https://github.com/gatsbyjs/gatsby/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+) and [`good first issue`](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). + + - This part may be covered if a docs issue is assigned to you, or if you’re signing up voluntarily to take on an issue. + +2. Look at the [stub list](/contributing/stub-list/) to find docs that need contributions. + +3. Look at the [learning workflow meta issue](https://github.com/gatsbyjs/gatsby/issues/13708) to find active areas looking for docs. + +4. Read through the existing Gatsby docs information and find gaps in topic coverage. Is there an area you feel is missing? [File an issue](/contributing/how-to-file-an-issue/) to discuss it. If the team determines it warrants documentation, implement in a PR. + +5. Observe common points of confusion or rough edges through user feedback and recommend solutions. + +> _Note: It’s required to open a GitHub issue before submitting a PR if one does not already exist._ + +## Selecting the correct format + +A GitHub issue for new learning material should indicate the format. Is it a Reference or Conceptual Guide? A Tutorial? A recipe? + +Does docs coverage exist anywhere on `gatsbyjs.org`? If so, would an alternative format help provide information for Gatsby learners of different skill and experience levels? For example, if a tutorial exists but there is no coverage in Reference Guides, adding more content in a different format would benefit users. + +### Tutorials vs. recipes vs. guides: + +- [**Tutorials**](/tutorial/) are step-by-step learning materials that show a user how to do something without skipping steps. Tutorials must consider a beginner experience, but can be useful for anyone. +- [**Recipes**](/docs/recipes/) are shorter, more concise tutorials that limit their scope to a single task or outcome by using prerequisites and limited steps. Additional resources at the end lead the user to a logical next step. Recipes are for developers of all skill levels. +- [**Guides**](/docs/guides/) are different than tutorials, and the two main sections are Reference Guides and Conceptual Guides. Instead of “steps 1-4”, guides use standalone headings and sections to explain how to accomplish the task. They are often aimed at a more advanced audience due to the subject matter but should be approachable to anyone. + +Given the difference in audiences of the three main learning material formats, increasing and overlapping coverage of topics can help support Gatsby learners of different skill and experience levels. + +Please follow the [Gatsby blog post guidelines](/contributing/blog-contributions/) and do not suggest blog posts when what is needed is user documentation. + +More on the format of documentation and learning materials can be found in the contributing docs: + +- [Docs Templates](/contributing/docs-templates/) +- [Gatsby Style Guide](/contributing/gatsby-style-guide/) + +## Gathering and validating supporting information + +Writing an effective doc that meets the needs of Gatsby users requires gathering information from various sources and applying those concepts to your original writing. You must digest and validate the details you uncover and understand them enough to describe them in a way that users of multiple skill levels can learn. + +Here are some tips for gathering information on a given topic within Gatsby: + +1. As you prepare a contribution that adds documentation information, carefully read the accompanying GitHub issue for tips and relevant materials, and ask questions there. + +2. Search the Gatsby GitHub repo for additional tips, examples, starters, plugins, READMEs, and other information that could help you provide a learning resource that guides users through a particular use case or concept. + +3. You can also search the web for additional examples outside of the Gatsby GitHub org or docs site. Be sure to check Gatsby versions and only reference the most current examples unless for a specific purpose. + +4. In the event there is no information available to write a greenfield doc after trying all the above steps, such as for a new integration, try interviewing Gatsby core team members to help to produce an outline and content tips. See [Pair Programming program](/contributing/pair-programming/). + +5. **For Gatsby inkteam members:** You can also search in the Gatsby Slack internally for related information. It’s possible other team members have discussed the issue, or even compiled trouble points into a doc. Look and ask around as part of your discovery work. + +After you’ve collected supporting information, you must produce original writing to be accepted in the Gatsby docs. Copying other blog posts, materials, or Gatsby team member interviews word-for-word without attribution is not acceptable or allowed. Furthermore, direct quotes from interviews are also _almost never_ effective for guides, recipes, or tutorials. + +Rather, the best way to write greenfield docs is with new text that explains the concepts and ideas you uncovered. With research and demos supporting your writing, you can speak more legitimately to use cases and common troubleshooting. Phrasing information in alternative ways for different skill levels is a bit like avoiding usage of the same word or phrase in its definition: if a reader didn’t understand it the first time, they may be more likely to understand it with an alternative explanation. + +## Producing learning materials + +Create demo sites and examples to provide more authoritative material that supports the developer experience. When relevant, **functioning source code is a requirement to writing docs** that truly educate users. Source code examples can also be linked from a doc as an additional resource. Include testing as part of your source code to ensure it is robust and stands the test of time. + +Follow the [docs templates](/contributing/docs-templates/) to ensure you’re producing content in the right format for its purpose. + +Use the [Markdown syntax doc](/docs/mdx/markdown-syntax/) to understand your options for formatting text with Markdown, and follow [accessibility recommendations](/docs/making-your-site-accessible/#how-to-improve-accessibility) for [heading levels](/contributing/docs-contributions/#headings) and image alt text. + +Run the docs site locally to check formatting and functionality. There are instructions in the [contributing docs](/contributing/docs-contributions/). + +Refer to the [Gatsby style guide](/contributing/gatsby-style-guide/) to ensure your PR will be accepted. + +## Submitting a pull request + +Submit a pull request that’s tied to a GitHub issue by following the [How to Open a Pull Request guide](/contributing/how-to-open-a-pull-request/). + +Apply feedback from pull request reviews in order for them to be accepted. Further instructions can be found in the How to Open a Pull Request guide. + +## Reference links + +- [Docs Contributions](/contributing/docs-contributions/) +- [Docs Templates](/contributing/docs-templates/) +- [How to File an Issue](/contributing/how-to-file-an-issue/) +- [Gatsby Style Guide](/contributing/gatsby-style-guide/) +- [Markdown Syntax Doc](/docs/mdx/markdown-syntax/) +- [Pair Programming](/contributing/pair-programming/) for interviewing the core team only +- [Blog Post Guidelines](/contributing/blog-contributions/) +- [Docs site setup instructions](/contributing/docs-contributions/#docs-site-setup-instructions) +- [How to Open a Pull Request](/contributing/how-to-open-a-pull-request/) diff --git a/docs/contributing/gatsby-style-guide.md b/docs/contributing/gatsby-style-guide.md index be269524e..386d80ab2 100644 --- a/docs/contributing/gatsby-style-guide.md +++ b/docs/contributing/gatsby-style-guide.md @@ -377,9 +377,12 @@ module.exports = { ### Capitalize proper nouns -Proper nouns should use correct capitalization when possible. Below is a list of words as they should appear in Guide articles. +Proper nouns should use correct capitalization when possible. Below is a list of words as they should appear in blog posts, docs, and other learning materials on this website. +- Gatsby +- GraphQL - JavaScript (capital letters in "J" and "S" and no abbreviations) +- Markdown - Node.js A full-stack developer (adjective form with a dash) works on the full stack From e2b6dce0634e9c398c269cfec1f7bd8a1345cdcb Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 10 Mar 2020 14:01:49 +0000 Subject: [PATCH 052/127] sync with monorepo gatsbyjs/gatsby@4149c523b848cd5e9519dae8f24fd9cdc110301e - tailwind.macro has depreciated (#22065) * tailwind.macro has depreciated added Twin docs for versions 1.0.0+ of Tailwind * Update docs/docs/tailwind-css.md Co-Authored-By: LB * Update docs/docs/tailwind-css.md Co-Authored-By: LB * Update docs/docs/tailwind-css.md Co-Authored-By: LB * Update docs/docs/tailwind-css.md Co-Authored-By: LB * Update docs/docs/tailwind-css.md Co-Authored-By: Jeremy Swanborough * chore: format Co-authored-by: LB Co-authored-by: gatsbybot --- docs/docs/tailwind-css.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/docs/tailwind-css.md b/docs/docs/tailwind-css.md index b3ace8490..8fcf8f76c 100644 --- a/docs/docs/tailwind-css.md +++ b/docs/docs/tailwind-css.md @@ -70,12 +70,28 @@ These steps assume you have a CSS-in-JS library already installed, and the examp 1. Install Tailwind Babel Macro -**Note**: `tailwind.macro` isn't currently compatible with Tailwind 1.0.0+. However, a compatible beta is available at `tailwind.macro@next`. Feel free to either use the beta or revert to Tailwind 0.7.4. +**Note**: `tailwind.macro` isn't currently compatible with Tailwind 1.0.0+. However, a new forked project can be found at `twin.macro` that supports Tailwindcss v1.2 classes. It's currently in pre-release so not all plugins are supported at the time of writing. Alternatively, you can revert to Tailwind 0.7.4. -**Option 1**: Install `tailwind.macro@next` and use Tailwind 1.0.0+ +**Option 1**: Install `twin.macro` and use Tailwind 1.2.0+ + +1. Install Twin and Emotion ```shell -npm install --save tailwind.macro@next +npm install -D twin.macro @emotion/core @emotion/styled gatsby-plugin-emotion +``` + +2. Import the Tailwind base styles + +```javascript:title=gatsby-browser.js +import "tailwindcss/dist/base.css" +``` + +3. Enable the Gatsby emotion plugin + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [`gatsby-plugin-emotion`], +} ``` **Option 2**: Install stable `tailwind.macro` and use Tailwind 0.7.4 From 0fc0c02c5c0100c306ff0c06273533d2a94fcdf2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 10 Mar 2020 14:55:47 +0000 Subject: [PATCH 053/127] sync with monorepo gatsbyjs/gatsby@3ef38db2d14f0ffc7032bc2de0231180599943d2 - fix (#22104) Co-authored-by: gatsbybot --- .../index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md b/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md index 6d5c40c71..a1fa381c3 100644 --- a/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md +++ b/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md @@ -44,7 +44,7 @@ Using the power and flexibility of React, you can create a React component to po > > If you're not using those starters, [follow this guide for installation instructions][gatsby-plugin-react-helmet] -```js:title=src/components/seo.js +```jsx:title=src/components/seo.js import React from "react" // highlight-start import Helmet from "react-helmet" @@ -80,7 +80,7 @@ export default SEO This component doesn't _do_ anything yet, but it's the foundation for a useful, extensible component. It leverages the `useStaticQuery` functionality enabled via Gatsby to query siteMetadata (e.g. details in `gatsby-config.js`) with description and keywords. At this point, the `SEO` component returns `null` to render nothing. Next, you will _actually_ render something and build out the prototype for this SEO component. -```js:title=src/components/seo.js +```jsx:title=src/components/seo.js import React from "react" import Helmet from "react-helmet" import { useStaticQuery, graphql } from "gatsby" @@ -148,7 +148,7 @@ In addition to SEO for actual _search_ engines you also want those pretty cards - Title for embedded results - (Optionally) display an image and a card if an image is passed in to the component -```js:title=src/components/seo.js +```jsx:title=src/components/seo.js import React from "react" import PropTypes from "prop-types" // highlight-line import Helmet from "react-helmet" @@ -288,10 +288,10 @@ To implement this functionality, you need to do the following: 1. Enable passing a `pathname` prop to your SEO component 1. Prefix your `pathname` prop with your `siteUrl` (from `gatsby-config.js`) - - A canonical link should be _absolute_ (e.g. https://your-site.com/canonical-link), so you will need to prefix with this `siteUrl` + - A canonical link should be _absolute_ (e.g. `https://your-site.com/canonical-link`), so you will need to prefix with this `siteUrl` 1. Tie into the `link` prop of `react-helmet` to create a `` tag -```js:title=src/components/seo.js +```jsx:title=src/components/seo.js import React from "react" import PropTypes from "prop-types" import Helmet from "react-helmet" @@ -444,7 +444,7 @@ You created an extensible SEO component. It takes a `title` prop and then (optio ### In a page component -```js:title=src/pages/index.js +```jsx:title=src/pages/index.js import React from "react" import Layout from "../components/layout" @@ -477,7 +477,7 @@ mkdir -p content/blog/2019-01-04-hello-world-seo touch content/blog/2019-01-04-hello-world-seo/index.md ``` -```md:title=content/blog/2019-01-04-hello-world-seo/index.md +```markdown:title=content/blog/2019-01-04-hello-world-seo/index.md --- date: 2019-01-04 featured: images/featured.jpg @@ -498,7 +498,7 @@ Make sure to use appropriately sized images for social sharing. Facebook and Twi #### Querying with GraphQL -```js:title=src/templates/blog-post.js +```jsx:title=src/templates/blog-post.js import React from "react" import { Link, graphql } from "gatsby" From 57cb02db8270caf38cd2641d99a413196b3371c0 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 10 Mar 2020 19:21:35 +0000 Subject: [PATCH 054/127] sync with monorepo gatsbyjs/gatsby@a7df59992da253b73f96ecbfdc62156bc58e8875 - Update Feedback/Env Var docs to follow style guide (#22146) * update docs to follow style guide * Apply suggestions from code review Co-Authored-By: LB Co-authored-by: LB --- docs/docs/cli-feedback.md | 4 +-- docs/docs/environment-variables.md | 49 +++++++++++++++--------------- 2 files changed, 27 insertions(+), 26 deletions(-) diff --git a/docs/docs/cli-feedback.md b/docs/docs/cli-feedback.md index 48a0883a3..7a142a463 100644 --- a/docs/docs/cli-feedback.md +++ b/docs/docs/cli-feedback.md @@ -2,8 +2,8 @@ title: Gatsby CLI Feedback --- -Gatsby users will be prompted every 3 months (at the most) to give feedback to Gatsby on our products and services. This feedback is incredibly valuable and will help us shape Gatsby. +Gatsby users will be prompted every 3 months (at the most) to give feedback on Gatsby's products and services. This feedback is incredibly valuable and will help the team shape Gatsby. ## How to opt-out -Users may always opt-out from the feedback prompts with `gatsby feedback --disable` or by setting the environment variable `GATSBY_TELEMETRY_DISABLED` to `1` +Users may always opt-out from the feedback prompts with `gatsby feedback --disable` or by setting the [environment variable](/docs/environment-variables/) `GATSBY_TELEMETRY_DISABLED` to `1`. diff --git a/docs/docs/environment-variables.md b/docs/docs/environment-variables.md index 351f0a9db..870bb799d 100644 --- a/docs/docs/environment-variables.md +++ b/docs/docs/environment-variables.md @@ -2,28 +2,28 @@ title: Environment Variables --- -## Environments and Environment Variables - -You can provide environment variables to your site to customise its behavior in different environments. +You can provide environment variables to your site to customize its behavior in different environments. Environment variables can be distinguished between different types. + There are environment variables that are defined in special places intended to be used in different deployment environments. You can call these “Project Env Vars”. + And there are true OS-level environment variables that might be used in command-line calls. You can call these “OS Env Vars”. In both cases you want to be able to access the relevant value of these variables for the environment you are in. -By default gatsby supports only 2 environments: +By default Gatsby supports 2 environments: -- If you run `gatsby develop`, then you will be in the 'development' environment. -- If you run `gatsby build` or `gatsby serve`, then you will be in the 'production' environment. +- **Development.** If you run `gatsby develop`, then you will be in the 'development' environment. +- **Production.** If you run `gatsby build` or `gatsby serve`, then you will be in the 'production' environment. -If you want to define other environments then you'll need to do a little more work. See ["Additional Environments" below](#additional-environments-staging-test-etc). You can also have a look at our [environment variables codesandbox](https://codesandbox.io/s/6w9jjrnnjn) while reading the examples below. +If you want to define other environments then you'll need to do a little more work. See ["Additional Environments" below](#additional-environments-staging-test-etc). You can also have a look at the [environment variables CodeSandbox](https://codesandbox.io/s/6w9jjrnnjn) while reading the examples. ## Accessing Environment Variables in JavaScript All of the Project and OS Env Vars are only directly available at build time, or -when Node.Js is running. They aren't immediately available at run time of the client code; they -need to be actively captured and embedded into our client-side JavaScript. +when Node.js is running. They aren't immediately available at run time of the client code; they +need to be actively captured and embedded into client-side JavaScript. This is achieved during the build using Webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/). Once the environment variables have been embedded into the client-side code, they are accessible from the @@ -39,8 +39,7 @@ or rebuild your site after changing them. For Project Env Vars that you want to access in client-side browser JavaScript, you can define an environment config file, `.env.development` and/or `.env.production`, in your root folder. -Depending on your active environment, the correct one will be found and its values embedded as environment variables in the -browser JavaScript. +Depending on your active environment, the correct one will be found and its values embedded as environment variables in the browser JavaScript. In addition to these Project Environment Variables defined in `.env.*` files, you could also define OS Env Vars. OS Env Vars which are prefixed with `GATSBY_` will become available in @@ -54,7 +53,7 @@ GATSBY_API_URL=https://dev.example.com/api Gatsby runs several Node.js scripts at build time, notably `gatsby-config.js` and `gatsby-node.js`. OS Env Vars will already be available when Node is running, so you can add environment variables the -normal ways e.g. by adding environment variables through your hosting/build tool, your OS, or when +typical ways, e.g. by adding environment variables through your hosting/build tool, your OS, or when calling Gatsby on the command line. In Linux terminals this can be done with: @@ -67,8 +66,8 @@ In Windows it's a little more complex. [Check out this Stack Overflow article fo Project environment variables that you defined in the `.env.*` files will _NOT_ be immediately available in your Node.js scripts. To use those variables, use NPM package [dotenv](https://www.npmjs.com/package/dotenv) to -examine the active `.env.*` file and attached those values, -It's already a dependency of Gatsby, so you can require it in your `gatsby-config.js` or `gatsby-node.js` like this: +examine the active `.env.*` file and attach those values. +`dotenv` is already a dependency of Gatsby, so you can require it in your `gatsby-config.js` or `gatsby-node.js` like this: ```javascript:title=gatsby-config.js require("dotenv").config({ @@ -78,9 +77,9 @@ require("dotenv").config({ Now the variables are available on `process.env` as usual. -## Example +## Example of using an environment variable -Please note that you shouldn't commit `.env.*` files to your source control and rather use options given by your CD provider (e.g. Netlify with its [build environment variables](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables)). +Please note that you shouldn't commit `.env.*` files to your source control and rather use options given by your Continuous Deployment (CD) provider. An example is Netlify with its [build environment variables](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables). ```text:title=.env.development GATSBY_API_URL=https://dev.example.com/api @@ -93,6 +92,7 @@ API_KEY=927349872349798 ``` Note: since Gatsby uses the [Webpack DefinePlugin](https://webpack.js.org/plugins/define-plugin/) to make the environment variables available at runtime, they cannot be destructured from `process.env`; instead, they have to be fully referenced. + `GATSBY_API_URL` will be available to your site (Client-side and server-side) as `process.env.GATSBY_API_URL`.: ```jsx @@ -106,7 +106,7 @@ render() { } ``` -In Node, your site has access to your `API_KEY` (Server-side) using the identifier `process.env.API_KEY`. To access it client-side, you can use a `.env.*` file containing `API_KEY`. However, we **strongly** advise against checking these files into source control as it's a security issue to expose the API key. As a more secure alternative, you can prefix your variable with `GATSBY_` (as shown above). With this prefix, Gatsby automatically embeds the variable as process.env.GATSBY\_\* in compiled JS making it available in the browser context without exposing it elsewhere. +In Node, your site has access to your `API_KEY` (Server-side) using the identifier `process.env.API_KEY`. To access it client-side, you can use a `.env.*` file containing `API_KEY`. However, you are **strongly** advised against checking these files into source control as it's a security issue to expose the API key. As a more secure alternative, you can prefix your variable with `GATSBY_` (as shown above). With this prefix, Gatsby automatically embeds the variable as `process.env.GATSBY\_\*` in compiled JS making it available in the browser context without exposing it elsewhere. ```js // In any server-side code, e.g. gatsby-config.js @@ -125,7 +125,7 @@ module.exports = { ## Reserved Environment Variables: > You can not override certain environment variables as some are used internally -> for optimizations during build +> for optimizations during build, such as: - `NODE_ENV` - `PUBLIC_DIR` @@ -136,7 +136,7 @@ Gatsby also allows you to specify another environment variable when running the If set to true, this will expose a `/__refresh` webhook that is able to receive `POST` requests to _refresh_ the sourced content. This exposed webhook can be triggered whenever remote data changes, which means you can update your data without re-launching the development server. -You can trigger this endpoint locally for example on Unix-based operating systems (like Ubuntu and MacOS) you can use `curl -X POST http://localhost:8000/__refresh`. +You can trigger this endpoint locally, for example, on Unix-based operating systems (like Ubuntu and MacOS) using `curl -X POST http://localhost:8000/__refresh`. ## Build Variables @@ -144,18 +144,19 @@ Gatsby uses additional environment variables in the build step to fine-tune the For example, you can set `CI=true` as an environment variable to allow Gatsby's build script to tailor the terminal output to an automated deployment environment. Some CI/CD tooling may already set this environment variable. This is useful for limiting the verbosity of the build output for [dumb terminals](https://en.wikipedia.org/wiki/Computer_terminal#Dumb_terminals), such as terminal in progress animations. -Gatsby detects an optimal level of parallelism for the render phase of `gatsby build` based on the reported number of physical CPUs. For builds that are run in virtual environments, you may need to adjust the number of worker parallelism with the `GATSBY_CPU_COUNT` environment variable. See [Multi-core builds](https://www.gatsbyjs.org/docs/multi-core-builds/). +Gatsby detects an optimal level of parallelism for the render phase of `gatsby build` based on the reported number of physical CPUs. For builds that are run in virtual environments, you may need to adjust the number of worker parallelism with the `GATSBY_CPU_COUNT` environment variable. See [Multi-core builds](/docs/multi-core-builds/). -## Additional Environments (Staging, Test, etc) +## Additional Environments (Staging, Test, etc.) As noted above `NODE_ENV` is a reserved environment variable in Gatsby as it is needed by the build system to make key optimizations when compiling React and other modules. For this reason it is necessary to make use of a secondary environment variable for additional environment support, and manually make the environment variables available to the client-side code. You can define your own OS Env Var to track the active environment, and then to locate the relevant Project Env Vars to load. Gatsby itself will not do anything with that OS Env Var, but you can use it in `gatsby-config.js`. -Specifically, you can use `dotenv` and your individual OS Env Var to locate the `.env.myCustomEnvironment` file, and then use module.exports to store those Project Env Vars somewhere that the client-side JavaScript can access the values (via GraphQL queries). -For instance: if you would like to add a `staging` environment with a custom Google Analytics Tracking ID, and a dedicated `apiUrl`. You can add `.env.staging` at the root of your project with the following modification to your `gatsby-config.js` +Specifically, you can use `dotenv` and your individual OS Env Var to locate the `.env.myCustomEnvironment` file, and then use `module.exports` to store those Project Env Vars somewhere that the client-side JavaScript can access the values (via GraphQL queries). + +### Google Analytics env var example -### Example +If you would like to add a `staging` environment with a custom Google Analytics Tracking ID, and a dedicated `apiUrl` you can add `.env.staging` at the root of your project. In order to do so, use the following modification to your `gatsby-config.js`: ```text:title=.env.staging GA_TRACKING_ID="UA-1234567890" From 001a4d7002572294ba160847f33dc14f16a809f2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 10 Mar 2020 19:53:52 +0000 Subject: [PATCH 055/127] sync with monorepo gatsbyjs/gatsby@70227212744815eab7c697644d4cb29481ca487e - [docs]: Guide on working with Etsy in Gatsby (#21580) * Update docs/docs/working-with-Etsy-in-Gatsby.md Co-Authored-By: LB * Update docs/docs/working-with-Etsy-in-Gatsby.md Co-Authored-By: LB * [docs]: Guide on working with Etsy in Gatsby * [docs]: Guide on working with Etsy in Gatsby * chore: format * Update www/src/data/sidebars/doc-links.yaml Co-Authored-By: LB * Update docs/docs/working-with-Etsy-in-Gatsby.md Co-Authored-By: Marcy Sutton * revisions * Update docs/docs/working-with-Etsy-in-Gatsby.md Co-Authored-By: Aisha Blake * Update www/src/data/sidebars/doc-links.yaml Co-Authored-By: Aisha Blake * Update docs/docs/working-with-Etsy-in-Gatsby.md Co-Authored-By: Aisha Blake * latest revisions * Rewrite Etsy guide * Add plugin link * Fix typo * Apply suggestions from code review Co-Authored-By: LB * Update based on feedback * Update docs/docs/sourcing-from-etsy.md Co-Authored-By: LB Co-authored-by: LB Co-authored-by: gatsbybot Co-authored-by: Marcy Sutton Co-authored-by: Aisha Blake Co-authored-by: Aisha Blake Co-authored-by: LB --- docs/docs/sourcing-from-etsy.md | 116 ++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/docs/sourcing-from-etsy.md diff --git a/docs/docs/sourcing-from-etsy.md b/docs/docs/sourcing-from-etsy.md new file mode 100644 index 000000000..f113ff76b --- /dev/null +++ b/docs/docs/sourcing-from-etsy.md @@ -0,0 +1,116 @@ +--- +title: Sourcing from Etsy +--- + +[Etsy](https://www.etsy.com/) is an online marketplace for buying and selling handmade, vintage, and custom items. It's long been a home for creative entrepreneurs and can be used as a data source for your Gatsby site. + +## Prerequisites + +This guide assumes you already have a functioning Gatsby site as well as an open Etsy shop. You can start a new Gatsby site in a few steps with the [Quick Start guide](/docs/quick-start) and then [start selling on Etsy](https://www.etsy.com/your/shop/create)! + +## Getting an API key + +You'll need to make sure you have two-factor authentication enabled for your Etsy account. If you don't already have it, you'll be prompted when you go to [register a new application](https://www.etsy.com/developers/register). Fill in the required information as completely as you can, read Etsy's terms and conditions, and create your app. + +Note that Etsy expects developers to test the API using real data. That means your shop and listings will be live even as you're working on this site. If you're already an active Etsy seller, this shouldn't change your usual workflow much. If you're starting a new shop, be mindful of [Etsy's testing policies](https://www.etsy.com/developers/documentation/getting_started/testing#section_etsy_api_testing_policies) as you test your work. + +## Using the Etsy source plugin + +You can use the [`gatsby-source-etsy`](/packages/gatsby-source-etsy/) plugin to pull featured listings and images from your Etsy shop into your Gatsby site. To install it, run: + +```bash +npm install gatsby-source-etsy +``` + +### Configuring the plugin + +You will then need to add the plugin, your API key, and your shop ID to your `gatsby-config.js` file. That said, finding your shop ID can be confusing. While your shop does have an ID _number_, you don't actually need this to make requests against the Etsy API. You can use your shop's _name_ as a unique identifier if you don't know your shop ID. + +```js:title=gatsby-config.js +plugins: [ + { + resolve: "gatsby-source-etsy", + options: { + // highlight-start + apiKey: "your api key here", + shopId: "your shop id or shop name here", + // highlight-end + language: "en", // optional + }, + }, +], +``` + +### Testing your queries + +Once you have everything set up, run `gatsby develop` to start your site locally. At that point, you should be able to query for data related to your featured listings in [GraphiQL](/docs/running-queries-with-graphiql/). As an example, the following query gets the total number of featured listings in the shop as well as the price, title, and description of each item. + +```graphql +allFeaturedEtsyListing { + totalCount + nodes { + price + title + description + } + } +``` + +Make sure you have _featured_ items! To edit your store, go to the Shop Manager and select your Etsy shop under "Sales Channels". You should see an option to edit or enable featured items. + +## Displaying Etsy listings + +You can pull your Etsy listing data into a page or component by composing a GraphQL query and specifying the data you would like to display. For example, consider the following query, which gets the title, price, URL, and an image of each featured listing. + +```graphql +allFeaturedEtsyListing { + nodes { + id + title + price + url + description + childEtsyListingImage { + childFile { + childImageSharp { + fixed(width: 400, height: 400) { + ...GatsbyImageSharpFixed + } + } + } + } + } +} +``` + +Using this query on a page or in a component will allow you to display your listings. The following example loops through the featured items and displays them within a component. + +```jsx +{ + data.allFeaturedEtsyListing.nodes.map(item => ( +
+ +

{item.title}

+ + +

${item.price}

+

{item.description}

+
+ )) +} +``` + +Note that, in this example, there is no alt text passed to the `Img` component because this image can be considered presentational. All images appear in association with their title and description. Therefore, including the same information as alt text would be repetitive for anyone using a screen reader. + +## Gatsby advantages + +If you are familiar with Etsy, you are aware of the restrictions around branding within the platform. Shops have an extremely similar look, which limits the creativity any individual shop owner can display. In addition, you have no control over Etsy's policies. + +However, there are great benefits to selling on Etsy. What you lose in individuality you gain in discoverability. Etsy's advertising budget is enormous compared to what a shop owner, operating alone, could afford. You benefit from the trust Etsy has built up over the years. Because people are familiar with Etsy, they'll often go straight there to purchase their handmade or vintage items. + +Building your own site with Gatsby allows you to have the best of both worlds. You can take control over your customers' experience and drive traffic to your own blazing fast website. You're also able to avoid links to others' listings competing for your customers' attention. At the same time, you maintain all the benefits of having your products listed on Etsy. + +## Other resources + +- [`gatsby-source-etsy`](/packages/gatsby-source-etsy/) +- Etsy's [API documentation](https://www.etsy.com/developers/documentation/) From 91e3f31796e0246b22a61817f855d990c25a5543 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 11 Mar 2020 17:10:02 +0000 Subject: [PATCH 056/127] sync with monorepo gatsbyjs/gatsby@d855f84cfbfb94fbc37fe57e353dc1d829d40b7f - [docs][guides] Running a Gatsby Preview Server (#22156) * first draft of a preview doc * clean up wording * add link to heroku deployment doc * Update docs/docs/running-a-gatsby-preview-server.md Co-Authored-By: LB Co-authored-by: LB --- docs/docs/running-a-gatsby-preview-server.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 docs/docs/running-a-gatsby-preview-server.md diff --git a/docs/docs/running-a-gatsby-preview-server.md b/docs/docs/running-a-gatsby-preview-server.md new file mode 100644 index 000000000..b703b075e --- /dev/null +++ b/docs/docs/running-a-gatsby-preview-server.md @@ -0,0 +1,18 @@ +--- +title: Running a Gatsby Preview Server +--- + +When editing content in a CMS, it's great to see a preview of changes before they go live. + +This can be accomplished by setting up a preview server with Gatsby, for which there are two options: + +## Rolling your own Preview + +Roughly, you can follow these steps to enable your own preview server: + +- Run `gatsby develop` on a Node.js host like [Heroku](/docs/deploying-to-heroku/) with the [ENABLE_GATSBY_REFRESH_ENDPOINT environment variable](/docs/environment-variables/#reserved-environment-variables) enabled. This will configure the develop server to re-source data when it receives a `POST` request to `/__refresh`. +- Then setup your CMS to ping this URL on the preview server whenever content is changed. + +## Using Gatsby Cloud Preview + +For a managed Preview server without having to create infrastructure yourself, try out [Gatsby Cloud](https://www.gatsbyjs.com/cloud). It's free for personal projects and single-purpose sites, with paid packages for a range of project and company needs. From 4f4cfaf0960d228ab9d215596896d209973c2b31 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 11 Mar 2020 17:57:41 +0000 Subject: [PATCH 057/127] sync with monorepo gatsbyjs/gatsby@dce6e11dd2d72f30f7049ce96af53d39931c4c8b - docs: add Cloudflare Workers documentation (#21658) * Add Cloudflare Workers documentation * fix link, reorder recipe Co-authored-by: Kyle Gill Co-authored-by: gatsbybot --- docs/docs/deploying-to-cloudflare-workers.md | 124 +++++++++++++++++++ docs/docs/preparing-for-deployment.md | 1 + docs/docs/recipes.md | 1 + docs/docs/recipes/deploying-your-site.md | 26 ++++ 4 files changed, 152 insertions(+) create mode 100644 docs/docs/deploying-to-cloudflare-workers.md diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md new file mode 100644 index 000000000..e504f5542 --- /dev/null +++ b/docs/docs/deploying-to-cloudflare-workers.md @@ -0,0 +1,124 @@ +--- +title: Deploying to Cloudflare Workers +--- + +[Cloudflare Workers](https://workers.cloudflare.com/) is a serverless platform for creating entirely new applications or augmenting existing ones without configuring or maintaining infrastructure. With [Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) you can deploy any static site including your Gatsby projects to a domain on Cloudflare or for free with on your [workers.dev](workers.dev) subdomain. + +To enable the KV store required to serve the Gatsby files, you'll need the [Workers Unlimited plan](https://developers.cloudflare.com/workers/about/pricing/) for \$5/month. + +This guide will get you started in a few steps: + +1. Installing wrangler CLI + +Workers Sites requires [wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/). The more straight forward way to install wrangler is with [npm](https://www.npmjs.com/), run the following command: + +```shell +npm i -g @cloudflare/wrangler +``` + +2. Initialize the Project + +To create the Worker code that will serve your Gatsby files, from the root of your Gatsby project run: + +``` +wrangler init --site +``` + +You'll notice your project structure should now look something like: + +```diff ++ ├── workers-site ++ └── wrangler.toml ++ │   ├── index.js ++ │   ├── package-lock.json ++ │   └── package.json + ├── src + │   ├── components + │   ├── images + │   └── pages + ├── gatsby-config.js + ├── package.json +``` + +3. Configure + +To authenticate into your Cloudflare account run: + +``` +wrangler config +``` + +Follow the [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure) for steps on gathering the correct account ID and API token to link wrangler to your Cloudflare account. + +If you don't already have a workers.dev domain run: + +``` +wrangler subdomain +``` + +Then, add your account ID to the `wrangler.toml` file, and set `bucket` to `"./public"`, which is where Gatsby's built files are output by default: + +``` +name = "gatsby-project" +type = "webpack" +account_id = "abcd..." +workers_dev = true + +[site] +bucket = "./public" +entry-point = "workers-site" +``` + +This deploys to your workers.dev subdomain. For a custom domain see [Quick Start](https://developers.cloudflare.com/workers/quickstart/#publish-to-your-domain). + +4. Deploy + +You can deploy your application by running the following command in the root of the project directory: + +```shell +wrangler publish +``` + +Now your site is available at gatsby-project.subdomain.workers.dev! + +5. CI with Github Actions + +Use wrangler's Github action [plugin](https://github.com/cloudflare/wrangler-action) to automatically deploy to Workers every time you push to master. + +Once Github Actions is enabled on your repo, add a file to your project's root called `.github/workflows/main.yml` with the contents: + +``` +name: Deploy production site + +on: + push: + branches: + - master + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: Navigate to repo + run: cd $GITHUB_WORKSPACE + - uses: actions/setup-node@v1 + with: + node-version: '10.x' + - name: Install deps + run: npm install + - name: Build docs + run: npm run build + - name: Publish + uses: cloudflare/wrangler-action@1.1.0 + with: + apiToken: ${{ secrets.CF_API_TOKEN }} + environment: "production" +``` + +Set up `CF_API_TOKEN` in Github secrets with appropriate values from [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure). + +## Additional resources + +- [Quickstart for Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) +- [Github Action wrangler plugin](https://github.com/cloudflare/wrangler-action) diff --git a/docs/docs/preparing-for-deployment.md b/docs/docs/preparing-for-deployment.md index cd83888e7..3319c4f4f 100644 --- a/docs/docs/preparing-for-deployment.md +++ b/docs/docs/preparing-for-deployment.md @@ -47,6 +47,7 @@ If you have a server from one of the following providers, you should read the in - [Aerobatic](/docs/deploying-to-aerobatic) - [Heroku](/docs/deploying-to-heroku) - [ZEIT Now](/docs/deploying-to-zeit-now) +- [Cloudflare Workers](/docs/deploying-to-cloudflare-workers) - [GitLab Pages](/docs/deploying-to-gitlab-pages) - [Netlify](/docs/deploying-to-netlify) - [Render](/docs/deploying-to-render) diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md index 7a7b48bf3..bbcb7eebb 100644 --- a/docs/docs/recipes.md +++ b/docs/docs/recipes.md @@ -117,3 +117,4 @@ Showtime. Once you are happy with your site, you are ready to go live with it! - [Preparing for deployment](/docs/recipes/deploying-your-site#preparing-for-deployment) - [Deploying to Netlify](/docs/recipes/deploying-your-site#deploying-to-netlify) - [Deploying to ZEIT Now](/docs/recipes/deploying-your-site#deploying-to-zeit-now) +- [Deploying to Cloudflare Workers](/docs/recipes/deploying-your-site#deploying-to-cloudflare-workers) diff --git a/docs/docs/recipes/deploying-your-site.md b/docs/docs/recipes/deploying-your-site.md index 25d669349..6b7e88aec 100644 --- a/docs/docs/recipes/deploying-your-site.md +++ b/docs/docs/recipes/deploying-your-site.md @@ -104,3 +104,29 @@ Use [Now CLI](https://zeit.co/download) to deploy your Gatsby application withou ### Additional resources - [Deploying to ZEIT Now](/docs/deploying-to-zeit-now/) + +## Deploying to Cloudflare Workers + +Use [`wrangler`](https://developers.cloudflare.com/workers/tooling/wrangler/) to deploy your Gatsby application globally without leaving the command-line interface. + +### Prerequisites + +- An account on [Cloudflare](https://dash.cloudflare.com/sign-up) +- A [Workers Unlimited plan](https://developers.cloudflare.com/workers/about/pricing/) for \$5/month to enable the KV store, which is required to serve the Gatsby files. +- A [Gatsby site](/docs/quick-start) set up with Gatsby's CLI +- [wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/install/) installed globally (`npm i -g @cloudflare/wrangler`) + +### Directions + +1. Build your Gatsby application using `gatsby build` +2. Run `wrangler config` where you'll be prompted for your [Cloudflare API token](https://developers.cloudflare.com/workers/quickstart/#api-token) +3. Run `wrangler init --site` +4. Configure `wrangler.toml`. First add [account ID](https://developers.cloudflare.com/workers/quickstart/#account-id-and-zone-id) field and then either + 1. A free workers.dev domain by setting `workers_dev = true` + 2. A custom domain on Cloudflare by setting `workers_dev = false`, `zone_id = "abdc..` and `route = customdomain.com/*` +5. In `wrangler.toml` set `bucket = "./public"` +6. Run `wrangler publish` and your site will be deployed in seconds! + +### Additional resources + +- [Hosting on Cloudflare](/docs/deploying-to-cloudflare-workers) From 1081bc1d41f7a795c7b050485cad589fe465ad80 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 11 Mar 2020 19:02:02 +0000 Subject: [PATCH 058/127] sync with monorepo gatsbyjs/gatsby@593f50c0d797219d2522e3d0ffcee41e47ba730c - [docs] fix plugin/theme tutorial links and copy (#22160) * rename plugin and theme tutorials page * cleaning up/improving copy and links * clean up plugin/theme tutorials landing page copy --- docs/docs/creating-a-source-plugin.md | 8 ++++++-- docs/docs/creating-a-transformer-plugin.md | 6 ++++++ docs/tutorial/index.md | 8 +++----- docs/tutorial/pixabay-source-plugin-tutorial.md | 4 +--- docs/tutorial/plugin-and-theme-tutorials.md | 13 +++++++++++++ docs/tutorial/remark-plugin-tutorial.md | 2 +- docs/tutorial/theme-tutorials.md | 16 ---------------- 7 files changed, 30 insertions(+), 27 deletions(-) create mode 100644 docs/tutorial/plugin-and-theme-tutorials.md delete mode 100644 docs/tutorial/theme-tutorials.md diff --git a/docs/docs/creating-a-source-plugin.md b/docs/docs/creating-a-source-plugin.md index 4572c90eb..4399287a9 100644 --- a/docs/docs/creating-a-source-plugin.md +++ b/docs/docs/creating-a-source-plugin.md @@ -6,7 +6,7 @@ Source plugins are essentially out of the box integrations between Gatsby and va These systems can be CMSs like Contentful or WordPress, other cloud services like Lever and Strava, or your local filesystem -- literally anything that has an API. Currently, Gatsby has [over 300 source plugins](/plugins/?=gatsby-source). -Once a source plugin brings data into Gatsby's system, it can be transformed further with **transformer plugins**. +Once a source plugin brings data into Gatsby's system, it can be transformed further with **transformer plugins**. For step-by-step examples of how to create source and transformer plugins, check out the Gatsby [tutorials section](/tutorial/plugin-and-theme-tutorials/). ## What do source plugins do? @@ -40,7 +40,7 @@ exports.sourceNodes = async ({ actions }) => { // Process data into nodes. data.forEach(datum => createNode(processDatum(datum))) - // We're done, return. + // You're done, return. return } ``` @@ -158,3 +158,7 @@ One tip to improve the development experience of using a plugin is to reduce the the last time you fetched data using [`setPluginStatus`](/docs/actions/#setPluginStatus) and then only sync down nodes that have been modified since that time. [gatsby-source-contentful](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful) is an example of a source plugin that does this. - **Proactively fetch updates**. One challenge when developing locally is that a developer might make modifications in a remote data source, like a CMS, and then want to see how it looks in the local environment. Typically they will have to restart the `gatsby develop` server to see changes. This can be avoided if your source plugin knows to proactively fetch updates from the remote server. For example,[gatsby-source-sanity](https://github.com/sanity-io/gatsby-source-sanity), listens to changes to Sanity content when `watchMode` is enabled and pulls them into the Gatsby develop server. + +## Additional resources + +- Tutorial: [Creating a Pixabay Image Source Plugin](/tutorial/pixabay-source-plugin-tutorial/) diff --git a/docs/docs/creating-a-transformer-plugin.md b/docs/docs/creating-a-transformer-plugin.md index f0d0206bd..5ec01d2a7 100644 --- a/docs/docs/creating-a-transformer-plugin.md +++ b/docs/docs/creating-a-transformer-plugin.md @@ -15,6 +15,8 @@ The purpose of this doc is to: 1. Define what a Gatsby transformer plugin is, and 2. Walk through a simplified reimplementation of an existing plugin, to demonstrate how to create a transformer plugin. +For a step-by-step process, check out the tutorial on [Creating a Remark Transformer Plugin](/tutorial/remark-plugin-tutorial/). + ## What do transformer plugins do? Transformer plugins "transform" data of one type into another type. You'll often use both source plugins and transformer plugins in your Gatsby sites. @@ -286,3 +288,7 @@ const cachedHTML = await cache.get(htmlCacheKey(markdownNode)) cache.set(htmlCacheKey(markdownNode), html) ``` + +## Additional resources + +- Tutorial: [Creating a Remark Transformer Plugin](/tutorial/remark-plugin-tutorial/) diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 1e6c692a8..1129de745 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -24,13 +24,11 @@ In these intermediate tutorials, you'll learn how to pull data from almost anywh 7. [Programmatically create pages from data](/tutorial/part-seven/): Learn how to programmatically create a set of pages for your blog posts. 8. [Preparing a site to go live](/tutorial/part-eight/): Learn how to audit your site for performance and best practices for accessibility, SEO, and more. -## Theme tutorials +## Plugin & Theme tutorials -Gatsby themes abstract all of your default configuration (shared functionality, data sourcing, design) out of your site and into an installable package. +Gatsby plugins are a way to encapsulate, re-use, and compose functionality, such as data sourcing. Gatsby themes are a type of plugin which abstracts your default configuration (shared functionality, data sourcing, design) out of your site and into an installable package. -This means that the configuration and functionality aren’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another. - -Learn more about using and building themes with the [Gatsby theme tutorials](/tutorial/plugin-and-theme-tutorials/). +Learn how to build and use plugins and themes step-by-step in the [Plugin and Theme Tutorials](/tutorial/plugin-and-theme-tutorials/). ## Additional tutorials diff --git a/docs/tutorial/pixabay-source-plugin-tutorial.md b/docs/tutorial/pixabay-source-plugin-tutorial.md index 56e8567d3..d751e83ee 100644 --- a/docs/tutorial/pixabay-source-plugin-tutorial.md +++ b/docs/tutorial/pixabay-source-plugin-tutorial.md @@ -1,9 +1,7 @@ --- -title: Pixabay Image Source Plugin Tutorial +title: "Creating an Image Source Plugin" --- -Creating your own source plugin. - ## What this tutorial covers In this tutorial you'll create your own source plugin. Your plugin will source data from [pixabay.com](https://pixabay.com) allowing you to add Pixabay images to any Gatsby site. diff --git a/docs/tutorial/plugin-and-theme-tutorials.md b/docs/tutorial/plugin-and-theme-tutorials.md new file mode 100644 index 000000000..4fb119dd5 --- /dev/null +++ b/docs/tutorial/plugin-and-theme-tutorials.md @@ -0,0 +1,13 @@ +--- +title: Plugin & Theme Tutorials +--- + +**Gatsby plugins** are Node.js packages that implement Gatsby APIs and are commonly installed through a registry like npm. Common use cases for Gatsby plugins include data sourcing and hooking into lifecycle methods. + +**Gatsby themes** are a type of plugin that includes a `gatsby-config.js` file and adds pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. Themes might pre-bundle plugins and configure them so users don't have to, providing a nice abstraction that can be installed and updated as a package. + +To learn more about plugins and themes in general, you may be interested to check out the docs guides on [plugins](/docs/plugins/) and [themes](/docs/themes/). + +For a deeper understanding of the differences between plugins, themes, and starters, you can also refer to the related [conceptual guide](/docs/plugins-themes-and-starters/). + + diff --git a/docs/tutorial/remark-plugin-tutorial.md b/docs/tutorial/remark-plugin-tutorial.md index 1639cf4a6..6c5655348 100644 --- a/docs/tutorial/remark-plugin-tutorial.md +++ b/docs/tutorial/remark-plugin-tutorial.md @@ -1,5 +1,5 @@ --- -title: Remark Plugin Tutorial +title: "Creating a Remark Transformer Plugin" --- [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark) empowers developers to translate Markdown into HTML to be consumed via Gatsby's GraphQL API. Blogs and other content based sites can highly benefit from functionality enabled with this plugin. With this plugin, authors of content for the site don't need to worry about how the site is written or structured but can rather focus on writing engaging posts and content! diff --git a/docs/tutorial/theme-tutorials.md b/docs/tutorial/theme-tutorials.md deleted file mode 100644 index 6bb9680bf..000000000 --- a/docs/tutorial/theme-tutorials.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Plugin & Theme Tutorials ---- - -Gatsby plugins are Node.js packages that implement Gatsby APIs and are commonly installed through a registry like npm. Plugins are a way to encapsulate, re-use, and compose Gatsby functionality. A good example of this concept are Gatsby themes which is a type of plugin that includes a `gatsby-config.js` file and adds pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. - -> You can refer to the [conceptual guide on plugins,theme,and starters](/docs/plugins-themes-and-starters/) for more information. - -In this section, you'll find tutorials for: - -1. Setting up a site using a single theme (the blog theme) -2. Setting up a site which composes multiple themes (the blog theme, and the notes theme) - -To learn more about themes in general, you may be interested to check out the [themes section of the docs](/docs/themes), as well. - - From ffb264ef1df7011afa9aaf11f522d65def358b02 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 13:14:01 +0000 Subject: [PATCH 059/127] sync with monorepo gatsbyjs/gatsby@2a7cb8c10dff4f847ca8e13db2486ad877c80dfb - Updated the ReactJS Home URL (#22195) * Updated ReactJS links in Blogs * DOC: Updated ReactJS links * Updated ReactJS links in packages README --- docs/docs/browser-support.md | 2 +- docs/docs/building-with-components.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/browser-support.md b/docs/docs/browser-support.md index eebaad9df..9b12f50bb 100644 --- a/docs/docs/browser-support.md +++ b/docs/docs/browser-support.md @@ -2,7 +2,7 @@ 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://reactjs.org/docs/react-dom.html#browser-support) which is currently IE9+ as well as the most recent versions of other popular browsers. ## Polyfills diff --git a/docs/docs/building-with-components.md b/docs/docs/building-with-components.md index d72ce3144..e72dfa1a1 100644 --- a/docs/docs/building-with-components.md +++ b/docs/docs/building-with-components.md @@ -19,7 +19,7 @@ The following model shows how data from a source can be queried by GraphQL for u -[Thinking in React](https://facebook.github.io/react/docs/thinking-in-react.html) +[Thinking in React](https://reactjs.org/docs/thinking-in-react.html) is a good resource for learning how to structure applications with React. ## How does Gatsby use React Components? From bdf74b6104609008c1f73e6a9047019cd6facc12 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 13:33:44 +0000 Subject: [PATCH 060/127] sync with monorepo gatsbyjs/gatsby@4e97b1542fc336dbd3fee6df11252882e986ddb7 - Update awesome-gatsby-resources.md (#21877) --- docs/docs/awesome-gatsby-resources.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/awesome-gatsby-resources.md b/docs/docs/awesome-gatsby-resources.md index c79d08080..ea92037f0 100644 --- a/docs/docs/awesome-gatsby-resources.md +++ b/docs/docs/awesome-gatsby-resources.md @@ -46,6 +46,7 @@ See the [unofficial list of themes](https://gatsbytemplates.io/) - [Jason Lengstorf's "Learn stuff with Jason" playlist](https://www.youtube.com/playlist?list=PLz8Iz-Fnk_eTpvd49Sa77NiF8Uqq5Iykx) - [Gatsby Days Bay Area December 2018 - Kyle Mathews & Guest Speakers](https://www.youtube.com/playlist?list=PLCU2qJekvcN1wzgVKymbjbGtZ3VgAWOdj) - [Static Site Generation with Gatsby.js v0 — Scott Nonnenberg](https://blog.scottnonnenberg.com/static-site-generation-with-gatsby-js/) +- [Build a JAMstack Saas App with Gatsby playlist](https://www.youtube.com/playlist?list=PL8KiuH6vpACWZ7989jU1Puil5P2_m2O8e) - [React.js Conf 2016 - Lightning Talks - Kyle Mathews](https://www.youtube.com/watch?v=RFkNRKL6ZoE) - [Developing with React and Gatsby.js — Kyle Mathews](https://www.youtube.com/watch?v=G4LVKJOOj7o) - [GraphQL Summit Open Source Lightning Talk on Gatsby — Kyle Mathews](https://youtu.be/y588qNiCZZo) @@ -54,6 +55,7 @@ See the [unofficial list of themes](https://gatsbytemplates.io/) ## Livestreams - [Learn with Jason](https://www.youtube.com/playlist?list=PLCU2qJekvcN0RuMHCnjMYAKlpSKQ_e1hO) +- [Build a Saas app with Gatsby and the JAMstack](https://www.youtube.com/playlist?list=PL8KiuH6vpACWZ7989jU1Puil5P2_m2O8e) ## Gatsby tutorials From 568db86acaa08d13264d113dd0e7ea4b5c6863bc Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 14:00:00 +0000 Subject: [PATCH 061/127] sync with monorepo gatsbyjs/gatsby@9645eebd6ace41a962ab6af04370616f6c2b3a7b - docs(gatsby): Fix broken links (#22202) --- docs/docs/write-pages.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/write-pages.md b/docs/docs/write-pages.md index 3ca0f4011..c4afde631 100644 --- a/docs/docs/write-pages.md +++ b/docs/docs/write-pages.md @@ -61,12 +61,12 @@ The dynamic files that are created are (all under the `.cache` directory). This is a collection of page objects, created from redux `pages` namespace. For each page it includes the -- [componentChunkName](/docs/behind-the-scenes-terminology/#componentchunkname) -- [jsonName](/docs/behind-the-scenes-terminology/#jsonname) -- [path](/docs/behind-the-scenes-terminology/#path) -- [matchPath](/docs/behind-the-scenes-terminology/#matchpath) +- [componentChunkName](/docs/gatsby-internals-terminology/#componentchunkname) +- [jsonName](/docs/gatsby-internals-terminology/#jsonname) +- [path](/docs/gatsby-internals-terminology/#path) +- [matchPath](/docs/gatsby-internals-terminology/#matchpath) -The pages are sorted such that those with `matchPath`s come before those without. This is to assist [find-page.js](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/cache-dir/find-page.js) in selecting pages via regex before trying explicit paths. See [matchPaths](/docs/behind-the-scenes-terminology/#matchpath) for more info. +The pages are sorted such that those with `matchPath`s come before those without. This is to assist [find-page.js](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/cache-dir/find-page.js) in selecting pages via regex before trying explicit paths. See [matchPaths](/docs/gatsby-internals-terminology/#matchpath) for more info. e.g @@ -85,7 +85,7 @@ e.g ## sync-requires.js -This is a dynamically generated JavaScript file that exports `components`. It is an object created by iterating over the `components` redux namespace. The keys are the [componentChunkName](/docs/behind-the-scenes-terminology/#componentchunkname) (e.g. `component---src-blog-2-js`), and the values are expressions that require the component. E.g. `/home/site/src/blog/2.js`. The file will look something like this: +This is a dynamically generated JavaScript file that exports `components`. It is an object created by iterating over the `components` redux namespace. The keys are the [componentChunkName](/docs/gatsby-internals-terminology/#componentchunkname) (e.g. `component---src-blog-2-js`), and the values are expressions that require the component. E.g. `/home/site/src/blog/2.js`. The file will look something like this: ```javascript exports.components = { From 87cda3e53686fc646bbe76f4ff55788edf91b324 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 14:21:21 +0000 Subject: [PATCH 062/127] sync with monorepo gatsbyjs/gatsby@a0ebe455225ba037ae046517423109791c56e81a - chore(docs): remove whitespace from Markdown link (#22204) --- docs/docs/maintaining-a-plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/maintaining-a-plugin.md b/docs/docs/maintaining-a-plugin.md index cbd279019..a71bbae3f 100644 --- a/docs/docs/maintaining-a-plugin.md +++ b/docs/docs/maintaining-a-plugin.md @@ -24,7 +24,7 @@ Version 1.0.0 should be released when the plugin's API is considered stable. Ver > Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version. -Read more about this concept [in this paper on semantic versioning ](https://semver.org/). +Read more about this concept [in this paper on semantic versioning](https://semver.org/). ## Update README and document use cases From 19a5cd288f2adbd7dd90636e6be95f7c50b397ee Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 17:47:49 +0000 Subject: [PATCH 063/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@a21f694c5b5322ed91623ff824dd48d9e537406a=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=A7=B9=20Fix=20case=20of=20GitHub=20and=20JavaScript?= =?UTF-8?q?=20(#22217)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/deploying-to-cloudflare-workers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md index e504f5542..1994d8bc2 100644 --- a/docs/docs/deploying-to-cloudflare-workers.md +++ b/docs/docs/deploying-to-cloudflare-workers.md @@ -81,11 +81,11 @@ wrangler publish Now your site is available at gatsby-project.subdomain.workers.dev! -5. CI with Github Actions +5. CI with GitHub Actions -Use wrangler's Github action [plugin](https://github.com/cloudflare/wrangler-action) to automatically deploy to Workers every time you push to master. +Use wrangler's GitHub action [plugin](https://github.com/cloudflare/wrangler-action) to automatically deploy to Workers every time you push to master. -Once Github Actions is enabled on your repo, add a file to your project's root called `.github/workflows/main.yml` with the contents: +Once GitHub Actions is enabled on your repo, add a file to your project's root called `.github/workflows/main.yml` with the contents: ``` name: Deploy production site @@ -116,7 +116,7 @@ jobs: environment: "production" ``` -Set up `CF_API_TOKEN` in Github secrets with appropriate values from [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure). +Set up `CF_API_TOKEN` in GitHub secrets with appropriate values from [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure). ## Additional resources From a522a043be67f95086b062ff14ab7d8204def75f Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 17:48:32 +0000 Subject: [PATCH 064/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@f1bbefa890615b7b5c62f354a8b21b5cdc301697=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=94=92=20Fix=20missing=20HTTPS=20on=20graphql.org=20li?= =?UTF-8?q?nks.=20(#22210)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/graphql-concepts.md | 8 ++++---- docs/docs/graphql.md | 2 +- docs/docs/migrating-from-v0-to-v1.md | 2 +- docs/tutorial/part-four/index.md | 2 +- docs/tutorial/part-zero/index.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/graphql-concepts.md b/docs/docs/graphql-concepts.md index f5798f278..b6c05bfcf 100644 --- a/docs/docs/graphql-concepts.md +++ b/docs/docs/graphql-concepts.md @@ -114,14 +114,14 @@ as we do and find it useful for all your projects. When starting out with GraphQL, we recommend the following two tutorials: - https://www.howtographql.com/ -- http://graphql.org/learn/ +- https://graphql.org/learn/ [The official Gatsby tutorial](/tutorial/part-four/) also includes an introduction to using GraphQL specifically with Gatsby. ## How do GraphQL and Gatsby work together? One of the great things about GraphQL is how flexible it is. People use GraphQL -with [many different programming languages](http://graphql.org/code/) and for web and native apps. +with [many different programming languages](https://graphql.org/code/) and for web and native apps. Most people run GraphQL on a server to respond live to requests for data from clients. You define a schema (a schema is a formal way of describing @@ -232,7 +232,7 @@ See also the following blog posts: ### Fragments -Notice that in the above example for [querying images](#images), we used `...GatsbyImageSharpFixed`, which is a GraphQL Fragment, a reusable set of fields for query composition. You can read more about them [here](http://graphql.org/learn/queries/#fragments). +Notice that in the above example for [querying images](#images), we used `...GatsbyImageSharpFixed`, which is a GraphQL Fragment, a reusable set of fields for query composition. You can read more about them [here](https://graphql.org/learn/queries/#fragments). If you wish to define your own fragments for use in your application, you can use named exports to export them in any JavaScript file, and they will be automatically processed by Gatsby for use in your GraphQL queries. @@ -367,7 +367,7 @@ export const query = graphql` ### Getting started with GraphQL -- http://graphql.org/learn/ +- https://graphql.org/learn/ - https://www.howtographql.com/ - https://reactjs.org/blog/2015/05/01/graphql-introduction.html - https://services.github.com/on-demand/graphql/ diff --git a/docs/docs/graphql.md b/docs/docs/graphql.md index 38c3b5b3b..1f43e7d89 100644 --- a/docs/docs/graphql.md +++ b/docs/docs/graphql.md @@ -3,7 +3,7 @@ title: GraphQL & Gatsby overview: true --- -When building with Gatsby, you access your data through a query language named [GraphQL](http://graphql.org/). GraphQL allows you to declaratively express your data needs. This is done with `queries`, queries are the representation of the data you need. A query looks like this: +When building with Gatsby, you access your data through a query language named [GraphQL](https://graphql.org/). GraphQL allows you to declaratively express your data needs. This is done with `queries`, queries are the representation of the data you need. A query looks like this: ```graphql { diff --git a/docs/docs/migrating-from-v0-to-v1.md b/docs/docs/migrating-from-v0-to-v1.md index 80322204c..f6fd397c5 100644 --- a/docs/docs/migrating-from-v0-to-v1.md +++ b/docs/docs/migrating-from-v0-to-v1.md @@ -291,7 +291,7 @@ control over what data they got. In v1, templates and pages can query for exactly the data they need. There will be a more in-depth tutorial and GraphQL-specific documentation soon -but in the meantime, check out http://graphql.org/ and play around on Gatsby's +but in the meantime, check out https://graphql.org/ and play around on Gatsby's built-in GraphQL IDE (Graph*i*QL) which can be reached when you start the development server. diff --git a/docs/tutorial/part-four/index.md b/docs/tutorial/part-four/index.md index 7ce1575c4..2bcf8b338 100644 --- a/docs/tutorial/part-four/index.md +++ b/docs/tutorial/part-four/index.md @@ -70,7 +70,7 @@ If you're building a small site, one efficient way to build it is to pull in uns There are many options for loading data into React components. One of the most popular and powerful of these is a technology called -[GraphQL](http://graphql.org/). +[GraphQL](https://graphql.org/). GraphQL was invented at Facebook to help product engineers _pull_ needed data into components. diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md index a4389a90a..9c3b92442 100644 --- a/docs/tutorial/part-zero/index.md +++ b/docs/tutorial/part-zero/index.md @@ -303,7 +303,7 @@ It’s not necessary to be an expert with these already — if you’re not, don ### What is a website? -For a comprehensive introduction to what a website is -- including an intro to HTML and CSS -- check out “[**Building your first web page**](https://learn.shayhowe.com/html-css/building-your-first-web-page/)”. It’s a great place to start learning about the web. For a more hands-on introduction to [**HTML**](https://www.codecademy.com/learn/learn-html), [**CSS**](https://www.codecademy.com/learn/learn-css), and [**JavaScript**](https://www.codecademy.com/learn/introduction-to-javascript), check out the tutorials from Codecademy. [**React**](https://reactjs.org/tutorial/tutorial.html) and [**GraphQL**](http://graphql.org/graphql-js/) also have their own introductory tutorials. +For a comprehensive introduction to what a website is -- including an intro to HTML and CSS -- check out “[**Building your first web page**](https://learn.shayhowe.com/html-css/building-your-first-web-page/)”. It’s a great place to start learning about the web. For a more hands-on introduction to [**HTML**](https://www.codecademy.com/learn/learn-html), [**CSS**](https://www.codecademy.com/learn/learn-css), and [**JavaScript**](https://www.codecademy.com/learn/introduction-to-javascript), check out the tutorials from Codecademy. [**React**](https://reactjs.org/tutorial/tutorial.html) and [**GraphQL**](https://graphql.org/graphql-js/) also have their own introductory tutorials. ### Learn more about the command line From e85170d15fc0b6fd37150d9ee04f4271266fb7b9 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 12 Mar 2020 18:11:08 +0000 Subject: [PATCH 065/127] sync with monorepo gatsbyjs/gatsby@64c4e5e8c7d47d2a05ed700a2a20573b35857f03 - feat(docs): Official theme development workflow (#22177) * feat(docs): Official theme development workflow Document the worlkflow for official theme development using the gatsby dev CLI. * Update docs/contributing/code-contributions.md Co-Authored-By: LB * Improve theme workflow docs by using monorepo starter * Update docs/contributing/code-contributions.md Co-Authored-By: LB * Update docs/contributing/code-contributions.md Co-Authored-By: LB Co-authored-by: LB Co-authored-by: gatsbybot --- docs/contributing/code-contributions.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/contributing/code-contributions.md b/docs/contributing/code-contributions.md index 2507da2c6..be47d12a1 100644 --- a/docs/contributing/code-contributions.md +++ b/docs/contributing/code-contributions.md @@ -12,6 +12,7 @@ On this page: - [Contributing example sites](#contributing-example-sites) - [Using Docker to set up test environments](#using-docker-to-set-up-test-environments) - [Development tools](#development-tools) +- [Official theme development](#official-theme-development) ## Repo setup @@ -119,6 +120,22 @@ Using Docker Compose, you can start and stop a WordPress instance and integrate Check [Debugging the build process](/docs/debugging-the-build-process/) page to learn how to debug Gatsby. +## Official theme development + +This section is for official theme development in Gatsby's monorepo. If you are looking +to build your own theme, see [building themes](/docs/themes/building-themes/). + +Before getting started, make sure that you have +[set up your local dev environment](/contributing/setting-up-your-local-dev-environment/) +and that you're on the latest version of `gatsby-dev-cli`. + +- In the Gatsby monorepo find the starter in the `/starters` directory that uses the theme you want to work on +- Navigate to that directory, e.g. `cd starters/gatsby-starter-blog-theme` +- Install dependencies: `yarn` +- Run Gatsby Dev CLI to sync theme files, referencing the appropriate theme: `gatsby-dev --packages gatsby-theme-blog` +- In another tab run the starter: `yarn develop` +- Edit the theme files, you'll see changes automatically copied over and update in your starter. + ## Feedback At any point during the contributing process the Gatsby team would love to help! For help with a specific problem you can [open an issue on GitHub](/contributing/how-to-file-an-issue/). Or drop in to [our Discord server](https://gatsby.dev/discord) for general community discussion and support. From b21236ccc9f221144baae6e271ae1ef7f31cee12 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 13 Mar 2020 09:19:55 +0000 Subject: [PATCH 066/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@b957d3ed6e2b0d07ea581ea426a38ed351e472ea=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=A7=B9=20Fix=20Markdown=20link=20(#22232)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docs/sourcing-from-sanity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/sourcing-from-sanity.md b/docs/docs/sourcing-from-sanity.md index 03efb1df9..b51425dc4 100644 --- a/docs/docs/sourcing-from-sanity.md +++ b/docs/docs/sourcing-from-sanity.md @@ -4,7 +4,7 @@ title: Sourcing from Sanity ## What is Sanity.io? -[Sanity](https:///www.sanity.io) is a hosted backend for structured content that comes with an open source editor built in React. It has powerful real-time APIs for both reading and writing data. +[Sanity](https://www.sanity.io) is a hosted backend for structured content that comes with an open source editor built in React. It has powerful real-time APIs for both reading and writing data. You can use Sanity as a headless CMS that lets your authors work in a user friendly environment, or as a pure data backend for your apps. We make it easier for you to reuse content across multiple websites, apps, print, voice assistants, and other channels. From 52a5853c819d49cb0cb33f6f08bd41504ea7ca59 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 13 Mar 2020 18:32:36 +0000 Subject: [PATCH 067/127] sync with monorepo gatsbyjs/gatsby@c5c27ff61dbd047fe4425657d041c35049bc309a - (docs) Guide for translating UI text with Lingui (#21805) * asljfaklsdjfksdjf * fill out the lingui tutorial * links * Edit per style guide Co-authored-by: Aisha Blake Co-authored-by: gatsbybot --- docs/contributing/translation/ui-messages.md | 120 +++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 docs/contributing/translation/ui-messages.md diff --git a/docs/contributing/translation/ui-messages.md b/docs/contributing/translation/ui-messages.md new file mode 100644 index 000000000..c92b43839 --- /dev/null +++ b/docs/contributing/translation/ui-messages.md @@ -0,0 +1,120 @@ +--- +title: Translating UI Messages +--- + +Most content that needs to be translated is in Markdown files in translation repos. However, Gatsbyjs.org also has several pieces of UI text that should be translated using a library called [Lingui](https://lingui.js.org/). + +## Message Translation Guide + +Unlike Markdown documents, UI messages are kept in the same monorepo as the gatsby source. + +1. Follow the instructions for [running the Gatsby website](/contributing/blog-and-website-contributions/#making-changes-to-the-website). +2. Go to `www/` and run `yarn lingui:add-locale [lang code]` to generate a file for your language at `src/data/locales/[lang-code]/messages.po`. +3. Translate all the strings in `[lang code]/messages.po` by editing the `msgstr` field of each message. + +```po +#: src/components/prev-and-next.js:51 +msgid: "Previous" +msgstr: "前" +``` + +## Translating rich content + +Some messages will have embedded numerical tags in them. These represent embedded components, formatting, or user-defined text and should be kept in the translated string. If you are unsure about the context of a tag, make sure to look at the source file of the message. + +The sections below list the different types of rich content you may encounter. + +### Self-closing tags + +This type of rich text consists of a single self-closing XML tag (e.g. `<0/>`): + +```po +#: src/components/markdown-page-footer.js:24 +msgid: "<0/> edit this page on GitHub" +msgstr: "" +``` + +These are usually icons embedded in the text: + +```jsx + + Edit this page on GitHub + +``` + +If you are translating a right-to-left language like Arabic, make sure the icons are in the proper position at the start or end of the text. + +### Opening and closing tags + +This type of rich text consists of matching XML tags (e.g. `<0>` and ``): + +```po +#: src/components/shared/egghead-embed.js:39 +msgid: "Video hosted on <0>egghead.io" +msgstr: "" +``` + +These can represent formatting, accessible text, or links: + +```jsx + + Video hosted on egghead.io + +``` + +Make sure that the tags are paired correctly and surround the corresponding text in the translation. + +### Interpolated text + +This rich text is represented by braces and a number (e.g. `{0}`): + +```po +#: src/components/sidebar/section-title.js:142 +msgid: "{0} collapse" +msgstr: "" +``` + +These represent text in interpolated strings: + +``` +t`${item.title} collapse` +``` + +## Plurals, formatting, and grammatical gender + +Right now, no text with complex formatting rules is available for translation. When it is, this guide will be updated. + +## Updating content + +Sometimes additional content is added to the UI, leading to untranslated text. When this occurs, please update your language's `messages.po` file with the new translations. + +### New messages + +New messages can be found by searching for `msgstr: ""`. These messages may be translated as usual. + +### Updated message text + +If a previously translated UI message has changed, Lingui will mark that message as outdated and create a new entry for the updated text: + +```po +#: src/components/prev-and-next.js:51 +#msgid: "Previous" +#msgstr: "前" + +#: src/components/prev-and-next.js:51 +msgid: "Previous Article" +msgstr: "" +``` + +Translate the updated entry and delete the old one: + +```diff +- #: src/components/prev-and-next.js:51 +- #msgid: "Previous" +- #msgstr: "前" + +#: src/components/prev-and-next.js:51 +msgid: "Previous Article" +- msgstr: "" ++ msgstr: "前の記事" +``` From 2dc48ee962be7c190a8354886fd28b673c4abbf8 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sat, 14 Mar 2020 21:32:34 +0000 Subject: [PATCH 068/127] sync with monorepo gatsbyjs/gatsby@54b4a718017f79af81ea014711d0a10ed9a7a131 - Remove typo --- docs/docs/what-you-dont-need-plugins-for.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/what-you-dont-need-plugins-for.md b/docs/docs/what-you-dont-need-plugins-for.md index 8c8cf701b..eef39f801 100644 --- a/docs/docs/what-you-dont-need-plugins-for.md +++ b/docs/docs/what-you-dont-need-plugins-for.md @@ -9,6 +9,6 @@ Some examples: - Importing JavaScript packages that provide general functionality, such as `lodash` or `axios` - Integrating visualization libraries, such as `Highcharts` or `d3`. -As a general rule, any npm package you might use while working on another JavaScript or React application can also be used ,with a Gatsby application. What plugins offer is a prepackaged integration into the core Gatsby APIs to save you time and energy, with minimal configuration. +As a general rule, any npm package you might use while working on another JavaScript or React application can also be used with a Gatsby application. What plugins offer is a prepackaged integration into the core Gatsby APIs to save you time and energy, with minimal configuration. A good use case would be using `Styled Components`, you could manually render the `Provider` component near the root of your application, or you could use [gatsby-plugin-styled-components](https://www.gatsbyjs.org/packages/gatsby-plugin-styled-components/) which takes care of this step for you in addition to any other difficulties when configuring Styled Components to work with server-side rendering. From 4d1e0b4cfdf903308121f7ae32c93b79e51aacc6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Sat, 14 Mar 2020 21:34:30 +0000 Subject: [PATCH 069/127] sync with monorepo gatsbyjs/gatsby@a2e8e718eb1e6146dca1c3a560cd281ba65d49b8 - Add missing space --- docs/docs/creating-a-source-plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/creating-a-source-plugin.md b/docs/docs/creating-a-source-plugin.md index 4399287a9..0af8ac02d 100644 --- a/docs/docs/creating-a-source-plugin.md +++ b/docs/docs/creating-a-source-plugin.md @@ -157,7 +157,7 @@ One tip to improve the development experience of using a plugin is to reduce the - **Add event-based sync**. Some data sources keep event logs and are able to return a list of objects modified since a given time. If you're building a source plugin, you can store the last time you fetched data using [`setPluginStatus`](/docs/actions/#setPluginStatus) and then only sync down nodes that have been modified since that time. [gatsby-source-contentful](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful) is an example of a source plugin that does this. -- **Proactively fetch updates**. One challenge when developing locally is that a developer might make modifications in a remote data source, like a CMS, and then want to see how it looks in the local environment. Typically they will have to restart the `gatsby develop` server to see changes. This can be avoided if your source plugin knows to proactively fetch updates from the remote server. For example,[gatsby-source-sanity](https://github.com/sanity-io/gatsby-source-sanity), listens to changes to Sanity content when `watchMode` is enabled and pulls them into the Gatsby develop server. +- **Proactively fetch updates**. One challenge when developing locally is that a developer might make modifications in a remote data source, like a CMS, and then want to see how it looks in the local environment. Typically they will have to restart the `gatsby develop` server to see changes. This can be avoided if your source plugin knows to proactively fetch updates from the remote server. For example, [gatsby-source-sanity](https://github.com/sanity-io/gatsby-source-sanity), listens to changes to Sanity content when `watchMode` is enabled and pulls them into the Gatsby develop server. ## Additional resources From 58bc1236b9ad789bf3c6d9bebe643d07becbbc1e Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 16 Mar 2020 13:18:30 +0000 Subject: [PATCH 070/127] sync with monorepo gatsbyjs/gatsby@af07ac0ea6a43bcb631721c8169099c94202cdfc - Add snippet explaining lazy-loading inside an MDX file. (#22186) * Add blurb * Rephrase / fix * Show consumption example * Implement feedback * Rename file title Co-authored-by: gatsbybot --- .../mdx/importing-and-using-components.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/docs/mdx/importing-and-using-components.md b/docs/docs/mdx/importing-and-using-components.md index 30a9014e8..25377fe55 100644 --- a/docs/docs/mdx/importing-and-using-components.md +++ b/docs/docs/mdx/importing-and-using-components.md @@ -73,6 +73,48 @@ Because the `` and `` components were passed into the provid lessonTitle="Make React components globally available as shortcodes in MDX" /> +## Lazy-loading components + +When you use components in your `.mdx` files, Gatsby will bundle them into the main application bundle. This can cause performance problems. + +In the future, [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx) will address this. In the meantime, it can be prudent to lazy-load very large dependencies. The following snippet provides an example for lazy-loading an imaginary `Thing` component: + +```jsx:title=src/components/LazyThing.js +import React from "react" + +const Placeholder = () => null + +const LazyThing = props => { + // While the component is loading, we'll render a fallback placeholder. + // (The Placeholder is a component that renders nothing). + const [Component, setComponent] = React.useState(() => Placeholder) + + // After the initial render, kick off a dynamic import to fetch + // the real component, and set it into our state. + React.useEffect(() => { + import("./Thing.js").then(Thing => setComponent(() => Thing.default)) + }, []) + + return +} + +export default LazyThing +``` + +Inside your MDX, swap out any references to `Thing` with `LazyThing`: + +```diff +-import Thing from "../components/Thing/Thing.js" ++import LazyThing from "../components/Thing/LazyThing.js" + +## Introducing Things + +Here is a demo: + +- ++ +``` + ### Additional resources - Follow this detailed [example on using MDX](/examples/using-MDX) to import and render components. From 692cd723da3fd76e9661957fa68fa2dc79162a9c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 16 Mar 2020 14:17:50 +0000 Subject: [PATCH 071/127] sync with monorepo gatsbyjs/gatsby@99c739cc83bb6d131f791ed325453b0ccfd8e363 - add link to GoatCounter analytics (#22301) --- docs/docs/adding-analytics.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/adding-analytics.md b/docs/docs/adding-analytics.md index 78f09e8bd..a9bbc3394 100644 --- a/docs/docs/adding-analytics.md +++ b/docs/docs/adding-analytics.md @@ -69,3 +69,4 @@ Once this is configured you can deploy your site to test! If you navigate to the - [Matomo (formerly Piwik)](/packages/gatsby-plugin-matomo/) - [Simple Analytics](/packages/gatsby-plugin-simple-analytics) - [Parse.ly Analytics](/packages/gatsby-plugin-parsely-analytics/) +- [GoatCounter](/packages/gatsby-plugin-goatcounter/) From 057a80c5255ce992ee74a20de835c95112662f4c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 17 Mar 2020 08:23:40 +0000 Subject: [PATCH 072/127] sync with monorepo gatsbyjs/gatsby@93acc0fd77a5c8b95b449c5fd6080a1fcc23f826 - fix(docs): add Cloudflare Workers documentation (#22344) * fix * Revert "fix" This reverts commit 12c41ff1 * fix --- docs/docs/deploying-to-cloudflare-workers.md | 40 ++++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md index 1994d8bc2..845a06df5 100644 --- a/docs/docs/deploying-to-cloudflare-workers.md +++ b/docs/docs/deploying-to-cloudflare-workers.md @@ -20,7 +20,7 @@ npm i -g @cloudflare/wrangler To create the Worker code that will serve your Gatsby files, from the root of your Gatsby project run: -``` +```shell wrangler init --site ``` @@ -44,7 +44,7 @@ You'll notice your project structure should now look something like: To authenticate into your Cloudflare account run: -``` +```shell wrangler config ``` @@ -52,13 +52,13 @@ Follow the [Quick Start](https://developers.cloudflare.com/workers/quickstart/#c If you don't already have a workers.dev domain run: -``` +```shell wrangler subdomain ``` Then, add your account ID to the `wrangler.toml` file, and set `bucket` to `"./public"`, which is where Gatsby's built files are output by default: -``` +```toml name = "gatsby-project" type = "webpack" account_id = "abcd..." @@ -87,7 +87,7 @@ Use wrangler's GitHub action [plugin](https://github.com/cloudflare/wrangler-act Once GitHub Actions is enabled on your repo, add a file to your project's root called `.github/workflows/main.yml` with the contents: -``` +```yaml name: Deploy production site on: @@ -99,21 +99,21 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: Navigate to repo - run: cd $GITHUB_WORKSPACE - - uses: actions/setup-node@v1 - with: - node-version: '10.x' - - name: Install deps - run: npm install - - name: Build docs - run: npm run build - - name: Publish - uses: cloudflare/wrangler-action@1.1.0 - with: - apiToken: ${{ secrets.CF_API_TOKEN }} - environment: "production" + - uses: actions/checkout@v1 + - name: Navigate to repo + run: cd $GITHUB_WORKSPACE + - uses: actions/setup-node@v1 + with: + node-version: "10.x" + - name: Install deps + run: npm install + - name: Build docs + run: npm run build + - name: Publish + uses: cloudflare/wrangler-action@1.1.0 + with: + apiToken: ${{ secrets.CF_API_TOKEN }} + environment: "production" ``` Set up `CF_API_TOKEN` in GitHub secrets with appropriate values from [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure). From 118396cff9f5fff8599f164f6f4f4aebe5dc47f9 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 12:56:28 +0000 Subject: [PATCH 073/127] sync with monorepo gatsbyjs/gatsby@900adca59de2e1f227392163b693c5eb21a3cc44 - changed Github to GitHub (#22364) --- docs/docs/deploying-to-cloudflare-workers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md index 845a06df5..bc88ffa1f 100644 --- a/docs/docs/deploying-to-cloudflare-workers.md +++ b/docs/docs/deploying-to-cloudflare-workers.md @@ -121,4 +121,4 @@ Set up `CF_API_TOKEN` in GitHub secrets with appropriate values from [Quick Star ## Additional resources - [Quickstart for Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) -- [Github Action wrangler plugin](https://github.com/cloudflare/wrangler-action) +- [GitHub Action wrangler plugin](https://github.com/cloudflare/wrangler-action) From 6949f8da5522a3a9b1e2205fee08e5914dd5ab26 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 13:54:14 +0000 Subject: [PATCH 074/127] sync with monorepo gatsbyjs/gatsby@00d4b3814cc2c9eeabe1b28ba8d06eecac266c42 - Add video tutorials to awesome-gatsby-resources.md (#22380) --- docs/docs/awesome-gatsby-resources.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/awesome-gatsby-resources.md b/docs/docs/awesome-gatsby-resources.md index ea92037f0..dde2c9fd8 100644 --- a/docs/docs/awesome-gatsby-resources.md +++ b/docs/docs/awesome-gatsby-resources.md @@ -93,6 +93,7 @@ See the [unofficial list of themes](https://gatsbytemplates.io/) - [Deploying Your First Gatsby Site to Netlify](https://scotch.io/tutorials/deploying-your-first-gatsby-site-to-netlify) - [Add a chat widget to your Gatsby blog](https://pusher.com/tutorials/chat-gatsby/) - [Headless WordPress: Why Gatsby Should Be Next on Your List of Things to Learn](https://deliciousbrains.com/gatsby-headless-wordpress/) +- [Gatsby Tutorials \[video series\] — Michael Uloth](https://www.youtube.com/watch?v=jAa1wh5ATm0&list=PLHBEcHVSROXQQhXpNhmiVKKcw72Cc0V-U) ### German From 29a500daf16bd5e29057f6db1d27bb8ea57e0081 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 14:42:45 +0000 Subject: [PATCH 075/127] sync with monorepo gatsbyjs/gatsby@d052ac4773c32e9a10003ebbb4f9780309a042dc - Put install in its own code block (#22359) * Put install in its own code block This makes it easier for people to copy the snippet. I believe this is also consistent with other doc pages. * Remove --save from typography install snippet Co-Authored-By: LB Co-authored-by: LB --- docs/docs/typography-js.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs/typography-js.md b/docs/docs/typography-js.md index 8e6d9f96a..a3350c25b 100644 --- a/docs/docs/typography-js.md +++ b/docs/docs/typography-js.md @@ -10,7 +10,11 @@ Typography.js is a JavaScript library that allows you to explore the typographic Gatsby has the plugin `gatsby-plugin-typography` to integrate Typography.js into your project. -You can install the plugin and its peer dependencies into your project by running the command `npm install gatsby-plugin-typography react-typography typography --save` +You can install the plugin and its peer dependencies into your project by running the following command: + +```shell +npm install gatsby-plugin-typography react-typography typography +``` After the installation of the plugin is complete, navigate to your `gatsby-config.js` file located in the root of your project's directory and add the plugin to the configuration: From 7883ab44a4556da1e81414a4f7010767cdf19349 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 14:57:47 +0000 Subject: [PATCH 076/127] sync with monorepo gatsbyjs/gatsby@89ca9f428b9cb99d7658959112eca6127d78fb67 - Add docs/glossary/build article (#22149) * Add Build article, update doc-links and glossary.md Added a link to Build article from the Continuous Deployment entry. * docs/glossary/build: Use relative links, remove a repetitive graf. * Update docs/docs/glossary/build.md * Update docs/docs/glossary/build.md * Update docs/docs/glossary/build.md Co-authored-by: Aisha Blake --- docs/docs/glossary.md | 2 +- docs/docs/glossary/build.md | 33 +++++++++++++++++++++ docs/docs/glossary/continuous-deployment.md | 2 +- 3 files changed, 35 insertions(+), 2 deletions(-) create mode 100644 docs/docs/glossary/build.md diff --git a/docs/docs/glossary.md b/docs/docs/glossary.md index a4f00d81d..c6862a944 100644 --- a/docs/docs/glossary.md +++ b/docs/docs/glossary.md @@ -34,7 +34,7 @@ A tool that lets you write the most modern [JavaScript](#javascript), and on [bu The behind the scenes that the [public](#public) does not see. This often refers to the control panel of your [CMS](#cms). These are often powered by server-side programming languages such as Node.js, PHP, Go, ASP.net, Ruby, or Java. -### Build +### [Build](/docs/glossary/build/) In Gatsby, this is the process of taking your code and content and packaging it into a website that can be hosted and accessed. Commonly referred to as _build time_. See also: [backend](#backend) and [server-side](#server-side). diff --git a/docs/docs/glossary/build.md b/docs/docs/glossary/build.md new file mode 100644 index 000000000..66ad97ab8 --- /dev/null +++ b/docs/docs/glossary/build.md @@ -0,0 +1,33 @@ +--- +title: Build +disableTableOfContents: true +--- + +Learn what _build_ means and how to set up a build process for your Gatsby project. + +## What is a build? + +_Build_ refers to the process of compiling your site. During a build, or at _build time_, your project gets transformed from component files to optimized HTML, CSS, and JavaScript files that you can [deploy](/docs/glossary#deploy) to your hosting provider. + +There are a few ways to create a build. You can build your site locally on your computer using the [Gatsby CLI](/docs/gatsby-cli/#build), and then deploy changes to your [host](/docs/glossary#hosting). If you use [Gatsby Cloud](https://www.gatsbyjs.com/), you can take advantage of [Gatsby Builds](/blog/2020-01-27-announcing-gatsby-builds-and-reports/), a feature available with every Gatsby Cloud account. You can also use a [continuous deployment](/docs/glossary/continuous-deployment/) service such as [AWS Amplify](/docs/deploying-to-aws-amplify/) or [Netlify](/docs/deploying-to-netlify/). + +For larger teams or larger projects, you may want to use a continuous deployment approach to create builds. Each CD/CI service works slightly differently. Almost all of them, however, use the contents of a Git repository to build your site. + +Gatsby Cloud, for example, integrates with [GitHub](https://github.com/), and a number of hosted [content management systems](/docs/glossary#cms). Gatsby Cloud creates a new build after every commit or content change, although you can also trigger a build manually. + +### Using Gatsby CLI + +For smaller teams and projects, use `gatsby build`. The `gatsby build` command is part of the Gatsby command line interface (or CLI). You'll need to install the CLI interface to create a site with Gatsby. Install it globally using [npm](/docs/glossary/#npm). + +```shell +npm install -g gatsby-cli +``` + +Installing `gatsby-cli` globally makes Gatsby commands available system-wide. You'll use `gatsby new` to [create a new site](/tutorial/part-zero/#create-a-gatsby-site), and `gatsby develop` to start a development server on your local machine. + +When you're ready to publish your project, run the `gatsby build` command to create a production-ready version of your site. Once built, you can use an SFTP client, the [rsync](https://en.wikipedia.org/wiki/Rsync) utility, or similar tool to transfer these files to your host. + +### Learn more about builds + +- [Deploying and Hosting](/docs/deploying-and-hosting/) from the Gatsby docs +- How to enable super fast [Distributed Builds](https://www.gatsbyjs.com/docs/distributed-builds/) for Gatsby Cloud diff --git a/docs/docs/glossary/continuous-deployment.md b/docs/docs/glossary/continuous-deployment.md index 763d19cde..80a26498e 100644 --- a/docs/docs/glossary/continuous-deployment.md +++ b/docs/docs/glossary/continuous-deployment.md @@ -5,7 +5,7 @@ disableTableOfContents: true ## What is continuous deployment? -Continuous deployment (CD) is the automation of code deployments. In a continuous deployment system, you don't push a Deploy button or run a `deploy` command. Instead, you build a _pipeline_ — a process that builds and releases code automatically, without human intervention. +Continuous deployment (CD) is the automation of code deployments. In a continuous deployment system, you don't push a Deploy button or run a `deploy` command. Instead, you build a _pipeline_ — a process that [builds](/docs/glossary/build/) and releases code automatically, without human intervention. You'll most likely use a service to create your continuous deployment pipeline. Services such as [Netlify](http://netlify.com/), [AWS Amplify](https://aws.amazon.com/amplify/), [Azure](https://azure.microsoft.com/en-us/), and [Zeit](https://zeit.co/) are popular with Gatsby users. Or you can use [Gatsby Builds](/blog/2020-01-27-announcing-gatsby-builds-and-reports/), a feature of the [Gatsby Cloud](https://www.gatsbyjs.com/) service. From cf46efceefb8518ff88607bacec709dd411c49cb Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 15:00:14 +0000 Subject: [PATCH 077/127] sync with monorepo gatsbyjs/gatsby@7095e418b30989e671899aee68fe25afca82a89c - Expand on stale handling for gatsby sites (#22230) * Expand on stale handling for gatsby sites * Update docs/docs/gatsby-link.md Co-Authored-By: LB * Update docs/docs/gatsby-link.md Co-Authored-By: LB * Update gatsby-link.md * Update docs/docs/gatsby-link.md Co-Authored-By: LB * chore: format Co-authored-by: LB Co-authored-by: gatsbybot --- docs/docs/gatsby-link.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md index 7ec5089fe..154e4c907 100644 --- a/docs/docs/gatsby-link.md +++ b/docs/docs/gatsby-link.md @@ -389,6 +389,16 @@ onClick = () => { } ``` +## Handling stale client-side pages + +Gatsby's `` component will only fetch each page's resources once. Updates to pages on the site are not reflected in the browser as they are effectively "locked in time". This can have the undesirable impact of different users having different views of the content. + +In order to prevent this staleness, Gatsby requests an additional resource on each new page load: `app-data.json`. This contains a hash generated when the site is built; if anything in the `src` directory changes, the hash will change. During page loads, if Gatsby sees a different hash in the `app-data.json` than the hash it initially retrieved when the site first loaded, the browser will navigate using `window.location`. The browser fetches the new page and starts over again, so any cached resources are lost. + +However, if the page has previously loaded, it will not re-request `app-data.json`. In that case, the hash comparison will not occur and the previously loaded content will be used. + +> **Note:** Any state will be lost during the `window.location` transition. This can have an impact if there is a reliance on state management, e.g. tracking state in [wrapPageElement](/docs/browser-apis/#wrapPageElement) or via a library like Redux. + ## Additional resources - [Authentication tutorial for client-only routes](/tutorial/authentication-tutorial/) From 43576a4feb8228cde11d6afc1585767c341e115b Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 22:41:06 +0000 Subject: [PATCH 078/127] sync with monorepo gatsbyjs/gatsby@e325a734cefc736209ca7d870df354fd04da76f1 - chore(docs): Update version numbers in tutorial (#22291) * chore(docs): Update version numbers The documentation in tutorial does not use the latest version number of nvm and node, but it says that it is the latest version. * Update index.md * Revert every change except on line 155 * Correct mistakes --- docs/tutorial/part-zero/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md index 9c3b92442..05b92a2e5 100644 --- a/docs/tutorial/part-zero/index.md +++ b/docs/tutorial/part-zero/index.md @@ -152,7 +152,7 @@ nvm --version #### Set default Node.js version -When nvm is installed, it does not default to a particular node version. You’ll need to install the version you want and give nvm instructions to use it. This example uses the latest release of version 10, but more recent version numbers can be used instead. +When nvm is installed, it does not default to a particular node version. You’ll need to install the version you want and give nvm instructions to use it. This example uses the version 10 release, but more recent version numbers can be used instead. ```shell nvm install 10 From 4e63f0ff6d4d8638686e43331a11cf858823a54c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 18 Mar 2020 22:41:46 +0000 Subject: [PATCH 079/127] sync with monorepo gatsbyjs/gatsby@5000de8c00d1a094ddb1337ee53f0cd7db99cf2e - chore(docs): remove whitespace before commas (#22286) --- docs/docs/recipes/working-with-themes.md | 2 +- docs/docs/sourcing-from-buttercms.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/recipes/working-with-themes.md b/docs/docs/recipes/working-with-themes.md index 117b811fa..c8866e11b 100644 --- a/docs/docs/recipes/working-with-themes.md +++ b/docs/docs/recipes/working-with-themes.md @@ -55,7 +55,7 @@ module.exports = { } ``` -4. Run `gatsby 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). diff --git a/docs/docs/sourcing-from-buttercms.md b/docs/docs/sourcing-from-buttercms.md index 24516aa18..d024d3426 100644 --- a/docs/docs/sourcing-from-buttercms.md +++ b/docs/docs/sourcing-from-buttercms.md @@ -45,7 +45,7 @@ Run this in your terminal: ### Adding configuration Here you'll specify the config that will be needed to pull down data from ButterCMS. -Make sure to add your **API_TOKEN** from your dashboard. In this guide you will be creating `faq_items`, `faq_headline`, `homepage` , `customer_case_study` as stated in the config below. Do well to change it if you named it something differently. +Make sure to add your **API_TOKEN** from your dashboard. In this guide you will be creating `faq_items`, `faq_headline`, `homepage`, `customer_case_study` as stated in the config below. Do well to change it if you named it something differently. ```javascript:title=gatsby-config.js module.exports = { From 59939395cf9f65d41da066cbbe8746950eb2ec22 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 19 Mar 2020 12:35:23 +0000 Subject: [PATCH 080/127] sync with monorepo gatsbyjs/gatsby@d9c64152bfd937eae2737fc15f36991dfc4963d0 - Fixed eslint url path (#22399) * Fixed eslint url path * Fixed one more eslint config url --- docs/docs/eslint.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/eslint.md b/docs/docs/eslint.md index 6460c03a4..daf64a3b0 100644 --- a/docs/docs/eslint.md +++ b/docs/docs/eslint.md @@ -10,7 +10,7 @@ JavaScript, being a dynamic and loosely-typed language, is especially prone to d Gatsby ships with a built-in [ESLint](https://eslint.org) setup. For _most_ users, our built-in ESlint setup is all you need. If you know however that you'd like to customize your ESlint config e.g. your company has their own custom ESlint setup, this shows how this can be done. -You'll replicate (mostly) the [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.js) so you can then add additional presets, plugins, and rules. +You'll replicate (mostly) the [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.ts) so you can then add additional presets, plugins, and rules. ```shell @@ -38,7 +38,7 @@ module.exports = { } ``` -Note: When there is no ESLint file Gatsby implicitly adds a barebones ESLint loader. This loader pipes ESLint feedback into the terminal window where you are running or building Gatsby and also to the console in your browser developer tools. This gives you consolidated, immediate feedback on newly-saved files. When you include a custom `.eslintrc` file, Gatsby gives you full control over the ESLint configuration. This means that it will override the built-in `eslint-loader` and you need to enable any and all rules yourself. One way to do this is to use the Community plugin [`gatsby-eslint-plugin`](/packages/gatsby-plugin-eslint/). This also means that the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.js) will be entirely overwritten. If you would still like to take advantage of those rules, you'll need to copy them to your local file. +Note: When there is no ESLint file Gatsby implicitly adds a barebones ESLint loader. This loader pipes ESLint feedback into the terminal window where you are running or building Gatsby and also to the console in your browser developer tools. This gives you consolidated, immediate feedback on newly-saved files. When you include a custom `.eslintrc` file, Gatsby gives you full control over the ESLint configuration. This means that it will override the built-in `eslint-loader` and you need to enable any and all rules yourself. One way to do this is to use the Community plugin [`gatsby-eslint-plugin`](/packages/gatsby-plugin-eslint/). This also means that the default [ESLint config Gatsby ships with](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/eslint-config.ts) will be entirely overwritten. If you would still like to take advantage of those rules, you'll need to copy them to your local file. ### Disabling ESLint From 064abdbe380985a42ed28f693d6fccc67421b2db Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 19 Mar 2020 16:59:01 +0000 Subject: [PATCH 081/127] sync with monorepo gatsbyjs/gatsby@39282ca97c2b74c2d50ef0f55c87bc8beb4c63af - fix(docs): 404 link to workers.dev (#22365) * fix 404 link to workers.dev * remove word with Co-authored-by: gatsbybot --- docs/docs/deploying-to-cloudflare-workers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md index bc88ffa1f..54ec3bbfe 100644 --- a/docs/docs/deploying-to-cloudflare-workers.md +++ b/docs/docs/deploying-to-cloudflare-workers.md @@ -2,7 +2,7 @@ title: Deploying to Cloudflare Workers --- -[Cloudflare Workers](https://workers.cloudflare.com/) is a serverless platform for creating entirely new applications or augmenting existing ones without configuring or maintaining infrastructure. With [Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) you can deploy any static site including your Gatsby projects to a domain on Cloudflare or for free with on your [workers.dev](workers.dev) subdomain. +[Cloudflare Workers](https://workers.cloudflare.com/) is a serverless platform for creating entirely new applications or augmenting existing ones without configuring or maintaining infrastructure. With [Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) you can deploy any static site including your Gatsby projects to a domain on Cloudflare or for free on your [workers.dev](https://workers.dev) subdomain. To enable the KV store required to serve the Gatsby files, you'll need the [Workers Unlimited plan](https://developers.cloudflare.com/workers/about/pricing/) for \$5/month. From 378848bb90914a2551f1a338a76cfca2fd618e35 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 19 Mar 2020 19:22:39 +0000 Subject: [PATCH 082/127] sync with monorepo gatsbyjs/gatsby@a55329bd61728ca88b049b77f6e3dd46aa7b026d - Fix the setup() function in the documentation (#22368) https://github.com/gatsbyjs/gatsby/issues/16018 --- docs/docs/adding-an-rss-feed.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index 053d9f500..8aa93c6e5 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -159,7 +159,8 @@ module.exports = { } `, /* highlight-start */ - setup: () => ({ + setup: options => ({ + ...options, custom_namespaces: { itunes: 'http://www.itunes.com/dtds/podcast-1.0.dtd', }, From acf2674c37173084d0fa25e0d1ff7d3b27d3547f Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 19 Mar 2020 22:12:23 +0000 Subject: [PATCH 083/127] sync with monorepo gatsbyjs/gatsby@e0933f8b43d2e783f1c1ea3afdd41b17a2708512 - fix missing link of frontmatter (#22366) --- docs/contributing/translation/sync-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/translation/sync-guide.md b/docs/contributing/translation/sync-guide.md index 143e9aabd..4e652cc81 100644 --- a/docs/contributing/translation/sync-guide.md +++ b/docs/contributing/translation/sync-guide.md @@ -51,7 +51,7 @@ Fix all [merge conflicts](https://help.github.com/en/github/collaborating-with-i ### Frontmatter changes -This type of conflict reflects a change to the [frontmatter]() of a document. +This type of conflict reflects a change to the [frontmatter](/docs/adding-markdown-pages/#frontmatter-for-metadata-in-markdown-files) of a document. Removing a field: From 96287d3d91b8e370fd4cd04da09932c9116c5563 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Thu, 19 Mar 2020 22:34:08 +0000 Subject: [PATCH 084/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@f34598541ff88d8ea5ace2132663d6f6eb9f7081=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=A7=B9=20remove=20trailing=20whitespace=20from=20Markd?= =?UTF-8?q?own.=20(#22369)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore(docs): 🧹 remove trailing whitespace from Markdown. Found 2 Markdown files with trailing whitespace. * Update CHANGELOG.md Co-authored-by: Kyle Mathews --- docs/docs/glossary/markdown.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/glossary/markdown.md b/docs/docs/glossary/markdown.md index ac63aa0f9..3b87126d8 100644 --- a/docs/docs/glossary/markdown.md +++ b/docs/docs/glossary/markdown.md @@ -26,7 +26,7 @@ You can use Markdown to create documents for [Gatsby](https://www.gatsbyjs.org/)
- Developers who love using Gatsby versus those who haven't tried it yet. + Developers who love using Gatsby versus those who haven't tried it yet.
``` From b54f816e0faffe2129ffbd0eec4a7413d233ef1a Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 20 Mar 2020 11:03:19 +0000 Subject: [PATCH 085/127] sync with monorepo gatsbyjs/gatsby@cfc6413b067643f402b3dca0b2af3aca9d2324a2 - Unused variable and wrong propTypes (#22426) * delete unused variable * change type string to number Co-authored-by: gatsbybot --- .../seo-and-social-sharing-cards-tutorial/index.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md b/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md index a1fa381c3..607f026a7 100644 --- a/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md +++ b/docs/tutorial/seo-and-social-sharing-cards-tutorial/index.md @@ -269,8 +269,8 @@ SEO.propTypes = { // highlight-start image: PropTypes.shape({ src: PropTypes.string.isRequired, - height: PropTypes.string.isRequired, - width: PropTypes.string.isRequired, + height: PropTypes.number.isRequired, + width: PropTypes.number.isRequired, }), // highlight-end } @@ -424,8 +424,8 @@ SEO.propTypes = { title: PropTypes.string.isRequired, image: PropTypes.shape({ src: PropTypes.string.isRequired, - height: PropTypes.string.isRequired, - width: PropTypes.string.isRequired, + height: PropTypes.number.isRequired, + width: PropTypes.number.isRequired, }), // highlight-next-line pathname: PropTypes.string, @@ -511,7 +511,6 @@ class BlogPostTemplate extends React.Component { render() { const post = this.props.data.markdownRemark const siteTitle = this.props.data.site.siteMetadata.title - const { previous, next } = this.props.pageContext const image = post.frontmatter.image ? post.frontmatter.image.childImageSharp.resize : null // highlight-line From e07004d5df28a9e34237bf7beb048325f969bbf1 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 20 Mar 2020 13:16:23 +0000 Subject: [PATCH 086/127] sync with monorepo gatsbyjs/gatsby@b789e64426135bb3ffce210ac274b137e429037c - Update schema-customization.md (#22424) Was looking into createSchemaCustomisation as was previously using `sourceNodes` API. Scrolled down and found this tiny typo. --- docs/docs/schema-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/schema-customization.md b/docs/docs/schema-customization.md index a4460f6c1..c9175ec57 100644 --- a/docs/docs/schema-customization.md +++ b/docs/docs/schema-customization.md @@ -174,7 +174,7 @@ provided, they will still be handled by Gatsby's type inference. > Actions to customize Gatsby's schema generation are made available in the > [`createSchemaCustomization`](/docs/node-apis/#createSchemaCustomization) > (available in Gatsby v2.12 and above), -> and [`sourcesNodes`](/docs/node-apis/#sourceNodes) APIs. +> and [`sourceNodes`](/docs/node-apis/#sourceNodes) APIs. #### Opting out of type inference From 109c8240d3b030d8eb7cdd17e53a2af83f23f504 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 20 Mar 2020 13:16:47 +0000 Subject: [PATCH 087/127] sync with monorepo gatsbyjs/gatsby@e8c3f6b5ca96314901e9e625be427efcced0a508 - docs(source-from-drupal): Remove opinion text and reference Drupal module (#22219) * docs(source-from-drupal): Remove opinion text and reference Drupal module * Update docs/docs/sourcing-from-drupal.md Co-Authored-By: LB Co-authored-by: LB Co-authored-by: gatsbybot --- docs/docs/sourcing-from-drupal.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/docs/sourcing-from-drupal.md b/docs/docs/sourcing-from-drupal.md index 6d38febaa..8812caddc 100644 --- a/docs/docs/sourcing-from-drupal.md +++ b/docs/docs/sourcing-from-drupal.md @@ -61,20 +61,11 @@ module.exports = { [“Decoupled Drupal”](https://www.acquia.com/drupal/decoupled-drupal) has become an increasingly popular approach to building enterprise-grade websites, and has the [full-throated support](https://dri.es/how-to-decouple-drupal-in-2018) of Drupal community leaders. Using Gatsby in a decoupled Drupal setup allows your team to access the powerful content modeling and access workflow capabilities of Drupal 8, as well as the powerful UI creation & performance toolset of Gatsby. -## When is Drupal a great choice? +## Configuring Gatsby Live Preview -Many development teams, content teams, and client decision-makers are familiar with Drupal. Here are some scenarios in which Drupal is a great choice (and a few scenarios for which it’s not-so-great): +The [Gatsby Drupal Module](https://www.drupal.org/project/gatsby) enhances the content editor experience when using Gatsby with Drupal as a data source. This module provides Gatsby live preview capabilities using your [Gatsby Cloud account](https://www.gatsbyjs.com/get-started) or on your [locally running Gatsby development server](/docs/running-a-gatsby-preview-server/). -### Drupal is great for: - -- Complex page layouts or content modeling with multiple sections per page -- Teams with multi-stage content creation and review processes -- Development teams who value using popular, open-source technologies - -### Drupal is not-so-great for: - -- Content teams who require a slick content editing experience as it gets complex because of the multiple sections present -- Teams requiring the use of Drupal UI Kit as this is constantly under development and sometimes doesn't work as expected +While not required in order to build a Gatsby site that uses Drupal data, this module is the place where additional features are added to improve the Gatsby and Drupal integration. ## Interested in learning more? @@ -86,3 +77,4 @@ Using Gatsby together with Drupal offers a powerful, full-featured, open-source, - Example site that demonstrates [how to build Gatsby sites that pull data from the Drupal CMS](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-drupal). - Take a [free course on building a Gatsby site with Drupal](https://gatsbyguides.com/). - Read [Gatsby blog posts on Gatsby + Drupal](/blog/tags/drupal/). +- Watch a [video series on getting started with Gatsby and Drupal](https://www.youtube.com/playlist?list=PL-Ve2ZZ1kZNT9BhQMMI9jUySfdnQ8-S3n). From bf11f69d6112d4ce9b6724ab6e3c9956e102cf48 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 20 Mar 2020 14:36:31 +0000 Subject: [PATCH 088/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@303c9c6c3f803c01f7f13b4458184e3476b3b720=20-=20chore(docs):?= =?UTF-8?q?=20=F0=9F=A7=B9=20Fix=20case=20of=20GitLab,=20TypeScript=20and?= =?UTF-8?q?=20WordPress=20(#22227)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kyle Mathews --- docs/docs/sourcing-from-woocommerce.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/sourcing-from-woocommerce.md b/docs/docs/sourcing-from-woocommerce.md index 226c9bf68..837a32772 100644 --- a/docs/docs/sourcing-from-woocommerce.md +++ b/docs/docs/sourcing-from-woocommerce.md @@ -26,7 +26,7 @@ Configure its options: { resolve: "@pasdo501/gatsby-source-woocommerce", options: { - // Base URL of Wordpress site + // Base URL of WordPress site api: 'wordpress.domain', // true if using https. false otherwise. https: false, From 09c2278ac1a0f5396b4c5aebf4e78ac4927158eb Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 20 Mar 2020 15:08:28 +0000 Subject: [PATCH 089/127] sync with monorepo gatsbyjs/gatsby@3b3d6eef1e5f57715573bf57c02b29f5ec791fe7 - chore(docs): add tiiny host tutorial (#22284) * [docs] Add link to tiiny.host deployment tutorial in docs guidelist * [docs] Add tiiny.host deployment tutorial Co-authored-by: gatsbybot --- docs/docs/deploying-to-tiiny-host.md | 33 ++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/docs/deploying-to-tiiny-host.md diff --git a/docs/docs/deploying-to-tiiny-host.md b/docs/docs/deploying-to-tiiny-host.md new file mode 100644 index 000000000..dd9b5ae89 --- /dev/null +++ b/docs/docs/deploying-to-tiiny-host.md @@ -0,0 +1,33 @@ +--- +title: Deploying to tiiny.host +--- + +In this guide, you will learn how to deploy your Gatsby site to [tiiny.host](https://tiiny.host). + +[tiiny.host](https://tiiny.host/) is a tool for quickly hosting static websites. + +The tool is perfect for prototyping and sharing your Gatsby site online in a few clicks. + +This guide will show you how to deploy in two steps: + +## Step 1: Prepare your build + +Build your site by running this command in your project's root directory: + +```shell +gatsby build +``` + +This will generate a publishable version of your site in the `./public` folder. + +## Step 2: Deploy + +Zip your `./public` folder and head over to [https://tiiny.host](https://tiiny.host). + +Here, enter a subdomain, upload your zip file and click `Launch`. + +And that's it, you're done! There is no need to register and your site will be live for 7 days or can be extended on the Pro plan. + +## References: + +- [tiiny.host FAQ](https://tiiny.host/help/) From cbef41e026b9ed5050f30dc8a177ee82e8e6c37d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Fri, 20 Mar 2020 22:04:50 +0000 Subject: [PATCH 090/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@6e3f96396122c581be9e215f564c8ef4cd15c217=20-=20Update=20build?= =?UTF-8?q?ing=20a=20theme=20docs=20to=20no=20longer=20use=20deprecated=20?= =?UTF-8?q?theme=E2=80=A6=20(#22300)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * update docs to no longer use deprecated theme-ui layout and instead use theme-ui components https://theme-ui.com/layout/ * remove obsolete empty Layout * remove references to unused imports Co-Authored-By: Kyle Gill Co-authored-by: Kyle Gill --- docs/tutorial/building-a-theme.md | 38 +++++++++++++++---------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/docs/tutorial/building-a-theme.md b/docs/tutorial/building-a-theme.md index 2e561db8b..b12ec21b7 100644 --- a/docs/tutorial/building-a-theme.md +++ b/docs/tutorial/building-a-theme.md @@ -1146,14 +1146,8 @@ export const theme = { default: "90vw", max: "540px", }, - styles: { - Layout: { - color: "gray.2", - fontFamily: "body", - fontSize: 1, - lineHeight: "body", - }, - Header: { + text: { + heading: { backgroundColor: "primary", color: "background", fontWeight: "bold", @@ -1165,14 +1159,20 @@ export const theme = { color: "inherit", }, }, - Main: { + }, + layout: { + container: { margin: "0 auto", maxWidth: "max", width: "default", - }, - Container: { padding: 3, + color: "gray.2", + fontFamily: "body", + fontSize: 1, + lineHeight: "body", }, + }, + styles: { h1: { color: "gray.3", fontSize: 5, @@ -1220,12 +1220,12 @@ export default theme Now, refactor the `layout.js` component in `gatsby-theme-events` to actually use Theme UI. -First, import the `Layout`, `Header`, `Main`, and `Container` [components from Theme UI](https://theme-ui.com/layout). +First, import the `Header`, and `Container` [components from Theme UI](https://theme-ui.com/components). ```jsx:title=gatsby-theme-events/src/components/layout.js import React from "react" // highlight-next-line -import { Layout as ThemeLayout, Header, Main, Container } from "theme-ui" +import { Heading, Container } from "theme-ui" const Layout = ({ children }) => (
@@ -1241,17 +1241,15 @@ Next, refactor the `layout.js` component to use the Theme UI components: ```jsx:title=gatsby-theme-events/src/components/layout.js import React from "react" -import { Layout as ThemeLayout, Header, Main, Container } from "theme-ui" +import { Heading, Container } from "theme-ui" // highlight-start const Layout = ({ children }) => { return ( - -
Gatsby Events Theme
-
- {children} -
- +
+ Gatsby Events Theme + {children} +
) } // highlight-end From bc7c2a27f92569d5c6e3223eae17a07fc4f1f201 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 09:28:17 +0000 Subject: [PATCH 091/127] sync with monorepo gatsbyjs/gatsby@672947958ec41bbcde92457a586da9d7523935a1 - chore(docs): typo fix (#22484) --- docs/tutorial/part-zero/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md index 05b92a2e5..f73da8b50 100644 --- a/docs/tutorial/part-zero/index.md +++ b/docs/tutorial/part-zero/index.md @@ -12,8 +12,7 @@ The command line is a text-based interface used to run commands on your computer Take a moment to locate and open up the command line interface (CLI) for your computer. Depending on which operating system you are using, see [**instructions for Mac**](http://www.macworld.co.uk/feature/mac-software/how-use-terminal-on-mac-3608274/), [**instructions for Windows**](https://www.lifewire.com/how-to-open-command-prompt-2618089) or [**instructions for Linux**](https://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/). -_**Note:** If you’re new to the command line, "running" a command, means "writing a given set of instructions in your command prompt, and hitting the Enter key". Commands will be shown in a highlighted box, someth -ing like `node --version`, but not every highlighted box is a command! If something is a command it will be mentioned as something you have to run/execute._ +_**Note:** If you’re new to the command line, "running" a command, means "writing a given set of instructions in your command prompt, and hitting the Enter key". Commands will be shown in a highlighted box, something like `node --version`, but not every highlighted box is a command! If something is a command it will be mentioned as something you have to run/execute._ ## Install Node.js for your appropriate operating system From 2af0f087d6f0882d943eb05bcf492efb6963449e Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 09:29:10 +0000 Subject: [PATCH 092/127] sync with monorepo gatsbyjs/gatsby@3ec92326b30385f4515df65bd03e6c274df0df07 - chore(docs): typo fix (#22485) --- docs/tutorial/part-zero/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md index f73da8b50..24e6b34be 100644 --- a/docs/tutorial/part-zero/index.md +++ b/docs/tutorial/part-zero/index.md @@ -216,7 +216,7 @@ gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world > 💡 What just happened? > -> - `new` is a a gatsby command to create a new Gatsby project. +> - `new` is a gatsby command to create a new Gatsby project. > - Here, `hello-world` is an arbitrary title — you could pick anything. The CLI tool will place the code for your new site in a new folder called “hello-world”. > - Lastly, the GitHub URL specified points to a code repository that holds the starter code you want to use. From 8936be0707f54b6884b0142ee1e0478a5e126b5f Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 09:45:54 +0000 Subject: [PATCH 093/127] =?UTF-8?q?sync=20with=20monorepo=20gatsbyjs/gatsb?= =?UTF-8?q?y@e945793cbef9aa5151847e3f2ad776fcd065c223=20-=20chore(showcase?= =?UTF-8?q?):=20Standardize=20urls=20in=20creators.yml=20by=20removing?= =?UTF-8?q?=E2=80=A6=20(#22467)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contributing/submit-to-creator-showcase.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/submit-to-creator-showcase.md b/docs/contributing/submit-to-creator-showcase.md index b36b0fc06..58cc9b611 100644 --- a/docs/contributing/submit-to-creator-showcase.md +++ b/docs/contributing/submit-to-creator-showcase.md @@ -34,8 +34,8 @@ There are only two major steps :) development using Static Site Generators, Headless CMS, CI / CD and CDN setup. location: Poland - website: "https://yourname.io/" - github: "https://github.com/githubusername" + website: https://yourname.io/ + github: https://github.com/githubusername image: images/image.jpg # Right now, you can only answer true to either `for_hire` or for `hiring`, but not for both. From d8808d9891b55501efebf5253f87af6f50524ac8 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 09:48:05 +0000 Subject: [PATCH 094/127] sync with monorepo gatsbyjs/gatsby@cef1850d852a577f27aae79b61cfcf8798d287be - docs: update tailwind init command (#22469) The new command is `tailwindcss` not `tailwind` --- docs/docs/tailwind-css.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/tailwind-css.md b/docs/docs/tailwind-css.md index 8fcf8f76c..e7b9ff5be 100644 --- a/docs/docs/tailwind-css.md +++ b/docs/docs/tailwind-css.md @@ -31,7 +31,7 @@ npm install tailwindcss --save-dev To configure Tailwind, you'll need to add a Tailwind configuration file. Luckily, Tailwind has a built-in script to do this. Just run the following command: ```shell -npx tailwind init +npx tailwindcss init ``` ### Option #1: PostCSS From 7b66e3c1abc9964cb6a0a3447032150f1fc63921 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 09:51:02 +0000 Subject: [PATCH 095/127] sync with monorepo gatsbyjs/gatsby@b83e3775c8b393a4e9c6153842938ab9b7113fe8 - fix(docs): use code block for links to avoid 404 (#22468) --- docs/docs/mdx/programmatically-creating-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/mdx/programmatically-creating-pages.md b/docs/docs/mdx/programmatically-creating-pages.md index cc81c367d..c84402cf2 100644 --- a/docs/docs/mdx/programmatically-creating-pages.md +++ b/docs/docs/mdx/programmatically-creating-pages.md @@ -129,8 +129,8 @@ to set up our page. `/blog${value}` is a [template string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) that will result in: -- blog-1.mdx => http://localhost:8000/blog/blog-1/ -- blog-2.mdx => http://localhost:8000/blog/blog-2/ +- `blog-1.mdx` => `http://localhost:8000/blog/blog-1/` +- `blog-2.mdx` => `http://localhost:8000/blog/blog-2/` [`createFilePath`](https://www.gatsbyjs.org/packages/gatsby-source-filesystem/?=gatsby-source#createfilepath) is a function from `gatsby-source-filesystem` that translates file From dad839d1795a9aad9b98946291e70348d6d5a0d8 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 12:48:11 +0000 Subject: [PATCH 096/127] sync with monorepo gatsbyjs/gatsby@157895140329fb353f68f11d7861c1b16a36bdcc - put install in its own code block (#22443) --- docs/docs/typography-js.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs/typography-js.md b/docs/docs/typography-js.md index a3350c25b..201ed0ae7 100644 --- a/docs/docs/typography-js.md +++ b/docs/docs/typography-js.md @@ -72,7 +72,11 @@ To find or create a new typography theme, you can visit [Typography.js](https:// ## Installing Typography themes -Typography.js has built in themes that can save time when defining your website's font styling. The Funston theme, maintained by Typography, is one of the built in themes. To install the Funston theme from npm, run the command: `npm install typography-theme-funston --save` +Typography.js has built in themes that can save time when defining your website's font styling. The Funston theme, maintained by Typography, is one of the built in themes. To install the Funston theme from npm, run the command: + +```shell +npm install typography-theme-funston +``` To use the theme, edit the `typography.js` file that you created before and inform Typography of the new configuration: From 070fb67f1622f1878a83b9839581502acc56444c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 13:13:51 +0000 Subject: [PATCH 097/127] sync with monorepo gatsbyjs/gatsby@cc2fc56d396835e91a9bdfac7c2ffff6a0233982 - update link to json section (#22461) The link to the JSON section is no longer valid. This updates it to make it valid again. --- 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 a878e9be2..53d183e98 100644 --- a/docs/docs/sourcing-content-from-json-or-yaml.md +++ b/docs/docs/sourcing-content-from-json-or-yaml.md @@ -14,7 +14,7 @@ gatsby new gatsby-YAML-JSON-at-buildtime https://github.com/gatsbyjs/gatsby-star ## Directly import data with YAML -This section starts with YAML data sourcing. If you want to see how to do it using JSON instead, jump to the [next section](#Directly-importing-data-with-JSON). +This section starts with YAML data sourcing. If you want to see how to do it using JSON instead, jump to the [next section](#directly-import-data-with-json). ### Add the YAML content From e96cdaf9389b15dd9034f3461609caa2cec23e74 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 15:52:18 +0000 Subject: [PATCH 098/127] sync with monorepo gatsbyjs/gatsby@603e376a1208c24dd3e68e5fc56320a6980c03f7 - docs: add starter for plugins with new plugin recipes (#22258) * add starter for plugins * add recipes for using the plugin starter and installing a plugin * Apply suggestions from code review Co-Authored-By: LB Co-authored-by: LB Co-authored-by: gatsbybot --- docs/docs/creating-a-local-plugin.md | 6 ++ docs/docs/recipes.md | 21 +++-- docs/docs/recipes/working-with-plugins.md | 101 ++++++++++++++++++++++ docs/docs/recipes/working-with-themes.md | 14 +-- 4 files changed, 128 insertions(+), 14 deletions(-) create mode 100644 docs/docs/recipes/working-with-plugins.md diff --git a/docs/docs/creating-a-local-plugin.md b/docs/docs/creating-a-local-plugin.md index c5f87da64..f603ccc2c 100644 --- a/docs/docs/creating-a-local-plugin.md +++ b/docs/docs/creating-a-local-plugin.md @@ -36,6 +36,12 @@ Then the plugin can begin to hook into Gatsby through [Node](/docs/node-apis/) a 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. +To get started developing a plugin outside of your site's root folder, you can quickly generate one using `gatsby new` with the [starter for plugins](https://github.com/gatsbyjs/gatsby/tree/master/starters/gatsby-starter-plugin): + +```shell +gatsby new gatsby-plugin-foo https://github.com/gatsbyjs/gatsby-starter-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`. diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md index bbcb7eebb..2a3ef48c2 100644 --- a/docs/docs/recipes.md +++ b/docs/docs/recipes.md @@ -55,13 +55,20 @@ There are so many ways to add styles to your website; Gatsby supports almost eve - [Using Google Fonts](/docs/recipes/styling-css#using-google-fonts) - [Using Font Awesome](/docs/recipes/styling-css#using-fontawesome) -## [3. Working with starters](/docs/recipes/working-with-starters) +## [3. Working with plugins](/docs/recipes/working-with-plugins) + +[Plugins](/docs/plugins/) are Node.js packages that implement Gatsby APIs that are maintained officially, or by the community. + +- [Using a plugin](/docs/recipes/working-with-plugins#using-a-plugin) +- [Creating a new plugin using a plugin starter](/docs/recipes/working-with-plugins#creating-a-new-plugin-using-a-plugin-starter) + +## [4. Working with starters](/docs/recipes/working-with-starters) [Starters](/docs/starters/) are boilerplate Gatsby sites maintained officially, or by the community. - [Using a starter](/docs/recipes/working-with-starters#using-a-starter) -## [4. Working with themes](/docs/recipes/working-with-themes) +## [5. Working with themes](/docs/recipes/working-with-themes) 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. @@ -69,7 +76,7 @@ A Gatsby theme lets you centralize the look-and-feel of your site. You can seaml - [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) -## [5. Sourcing data](/docs/recipes/sourcing-data) +## [6. Sourcing data](/docs/recipes/sourcing-data) Pull data from multiple locations, like the filesystem or database, into your Gatsby site. @@ -80,7 +87,7 @@ Pull data from multiple locations, like the filesystem or database, into your Ga - [Pulling data from an external source and creating pages without GraphQL](/docs/recipes/sourcing-data#pulling-data-from-an-external-source-and-creating-pages-without-graphql) - [Sourcing content from Drupal](/docs/recipes/sourcing-data#sourcing-content-from-drupal) -## [6. Querying data](/docs/recipes/querying-data) +## [7. Querying data](/docs/recipes/querying-data) Gatsby lets you access your data across all sources using a single GraphQL interface. @@ -94,7 +101,7 @@ Gatsby lets you access your data across all sources using a single GraphQL inter - [GraphQL Query Fragments](/docs/recipes/querying-data#graphql-query-fragments) - [Querying data client-side with fetch](/docs/recipes/querying-data#querying-data-client-side-with-fetch) -## [7. Working with images](/docs/recipes/working-with-images) +## [8. Working with images](/docs/recipes/working-with-images) Access images as static resources, or automate the process of optimizing them through powerful plugins. @@ -103,14 +110,14 @@ Access images as static resources, or automate the process of optimizing them th - [Optimizing and querying local images with gatsby-image](/docs/recipes/working-with-images#optimizing-and-querying-local-images-with-gatsby-image) - [Optimizing and querying images in post frontmatter with gatsby-image](/docs/recipes/working-with-images#optimizing-and-querying-images-in-post-frontmatter-with-gatsby-image) -## [8. Transforming data](/docs/recipes/transforming-data) +## [9. Transforming data](/docs/recipes/transforming-data) Transforming data in Gatsby is plugin-driven. Transformer plugins take data fetched using source plugins, and process it into something more usable (e.g. JSON into JavaScript objects, and more). - [Transforming Markdown into HTML](/docs/recipes/transforming-data#transforming-markdown-into-html) - [Transforming images into grayscale using GraphQL](/docs/recipes/transforming-data#transforming-images-into-grayscale-using-graphql) -## [9. Deploying your site](/docs/recipes/deploying-your-site) +## [10. Deploying your site](/docs/recipes/deploying-your-site) Showtime. Once you are happy with your site, you are ready to go live with it! diff --git a/docs/docs/recipes/working-with-plugins.md b/docs/docs/recipes/working-with-plugins.md new file mode 100644 index 000000000..4b6b885eb --- /dev/null +++ b/docs/docs/recipes/working-with-plugins.md @@ -0,0 +1,101 @@ +--- +title: "Recipes: Working with Plugins" +tableOfContentsDepth: 1 +--- + +A [Gatsby plugin](/docs/what-is-a-plugin/) abstracts Gatsby APIs into an installable package. This means that modular chunks of Gatsby functionality aren’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can add external data, transform data, add third-party services (e.g. Google Analytics, Stripe), and more. + +## Using a plugin + +Found a plugin you'd like to use in your project? Awesome! You can configure it for use by following the steps below. This recipe uses the [`gatsby-source-filesystem` plugin](/plugins/gatsby-source-filesystem) as an example. + +> If you'd like to take a look at available plugins, check out the [plugin library](/plugins). + +### Prerequisites + +- An existing [Gatsby site](/docs/quick-start/) with a `gatsby-config.js` file + +### Directions + +1. Install the `gatsby-source-filesystem` plugin by running the following command: + +```shell +npm install gatsby-source-filesystem +``` + +2. Add the plugin to your `gatsby.config.js`, and set any options it needs, the filesystem source plugin takes a `name` and `path` as options: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [ + // highlight-start + { + resolve: `gatsby-source-filesystem`, + options: { + name: `images`, + path: `${__dirname}/src/images`, + }, + }, + // highlight-end + ], +} +``` + +_The instructions found in the README of the plugin you're using can you help you determine specifics about what configurations (if any) it requires. For this example to have an effect in your own site, you would need to create the `src/images` folder and place files inside of it._ + +3. Run `gatsby develop`, your plugin should run as your site builds. + +### Additional resources + +- Learn more about configuring options or using default options in the [Using a Plugin in Your Site](/docs/using-a-plugin-in-your-site/) guide. +- See an example Gatsby site using this configuration in [the repo for the default Gatsby starter](https://github.com/gatsbyjs/gatsby-starter-default/blob/master/gatsby-config.js). + +## Creating a new plugin using a plugin starter + +If you want to create your own plugin you can get started with the Gatsby plugin starter. + +### Prerequisites + +- An existing [Gatsby site](/docs/quick-start/) with a `gatsby-config.js` file + +### Directions + +1. _Outside_ of your Gatsby site, generate a new plugin based on the starter using the `gatsby new` command: + +```shell +gatsby new my-plugin https://github.com/gatsbyjs/gatsby-starter-plugin +``` + +The directory structure should look something like this: + +``` +gatsby-site +└── gatsby-config.js +└── src + ├── components + └── pages +my-plugin +├── gatsby-browser.js +├── gatsby-node.js +├── gatsby-ssr.js +├── index.js +└── package.json +``` + +2. Add the plugin to your site's `gatsby-config.js`, linking it to your local plugin's root folder with `require.resolve`. The path (or name of the plugin) should be to the directory name you used when generating the plugin: + +```javascript:title=gatsby-site/gatsby-config.js +module.exports = { + plugins: [ + require.resolve(`../my-plugin), // highlight-line + ], +} +``` + +3. Run `gatsby develop`. To verify the plugin starter loaded correctly in your site it will log a message to the console saying it "Loaded" before the `onPreInit` step finishes. + +4. Now you can implement [browser](/docs/browser-apis/), [server-side rendering](/docs/ssr-apis/), or [node APIs](/docs/node-apis/) and your site will run them each time it loads your plugin! + +### Additional resources + +- Read about creating and loading your own plugins in development in the [Creating a Local Plugin](/docs/creating-a-local-plugin/) guide diff --git a/docs/docs/recipes/working-with-themes.md b/docs/docs/recipes/working-with-themes.md index c8866e11b..a1a73b0bc 100644 --- a/docs/docs/recipes/working-with-themes.md +++ b/docs/docs/recipes/working-with-themes.md @@ -9,7 +9,7 @@ A [Gatsby theme](/docs/themes/what-are-gatsby-themes) abstracts Gatsby configura Found a theme you'd like to use on your project? Awesome! You can configure it for use by following the steps below. -> 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). +> If you'd like to take a look at more theme options, check out this [list of themes](/plugins?=gatsby-theme). ### Prerequisites @@ -32,11 +32,11 @@ cd {your-project-name} npm install gatsby-theme-blog ``` -3. Add theme to `gatsby.config.js` +3. Add theme to `gatsby-config.js` Follow the instructions found in the README of the theme you're using to determine what configuration it requires. -```shell +```javascript:title=gatsby-config.js module.exports = { plugins: [ { @@ -55,15 +55,15 @@ module.exports = { } ``` -4. Run `gatsby develop`, the theme should be available at `http://localhost:8000/{basePath}` +4. Run `gatsby develop`, the theme should now be running on your site. In this case with the blog theme configured with the `basePath` to "/blog", it should be available at `http://localhost:8000/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). +> To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](/packages/gatsby-theme-blog/#theme-options). ### Additional resources -- To learn how to further customize a theme, check out the docs on [Gatsby theme shadowing.](https://www.gatsbyjs.org/docs/themes/shadowing/) +- To learn how to further customize a theme, check out the docs on [Gatsby theme shadowing.](/docs/themes/shadowing/) -- You can also [use multiple themes](https://www.gatsbyjs.org/docs/themes/using-multiple-gatsby-themes/) on a project. +- You can also [use multiple themes](/docs/themes/using-multiple-gatsby-themes/) on a project. ## Creating a new site using a theme starter From db84aa28191f72aeaba265ff38aa23ecb04eb952 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 16:07:58 +0000 Subject: [PATCH 099/127] sync with monorepo gatsbyjs/gatsby@8c2528db5c1a7b229a3ca343840c5bf18ebedb68 - chore(tutorial): Using multiple themes together (#21714) * Initial work * Small change to text * Updated text * First draft * More progress * More progress * Complete first draft * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Obinna Ekwuno * Additional changes * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * siteMetaData is the same in each example * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Switch to mdx * Update using multiple themes together I tested this tutorial and it works perfectly! Thanks, @ehowey. I also fixed up some sections for readability. * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: LB * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: LB * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: LB * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: LB * Partial changes and example repo * Update README.md with. more context * Partial changes * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/tutorial/using-multiple-themes-together.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update examples/using-multiple-themes/README.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update examples/using-multiple-themes/README.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Updated example * Additional changes * Minor restructuring and some formatting * pull avatar a level up * revert changes to the locale files Co-authored-by: Obinna Ekwuno Co-authored-by: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: LB Co-authored-by: gatsbybot Co-authored-by: Laurie Barth --- docs/tutorial/using-a-theme.md | 4 + .../using-multiple-themes-together.md | 408 +++++++++++++++++- 2 files changed, 411 insertions(+), 1 deletion(-) diff --git a/docs/tutorial/using-a-theme.md b/docs/tutorial/using-a-theme.md index d7f5ff5a8..96e080986 100644 --- a/docs/tutorial/using-a-theme.md +++ b/docs/tutorial/using-a-theme.md @@ -182,3 +182,7 @@ To see what other theme colors you can customize, check out the `colors.js` file ## Wrapping up This was a step-by-step introduction to using a Gatsby theme through looking at a specific example. Note that different themes will be built differently, to accept different customization options. To dive deeper, check out the [Gatsby Theme docs](/docs/themes/). + +## What's next? + +- [Using multiple themes together](/tutorial/using-multiple-themes-together/) diff --git a/docs/tutorial/using-multiple-themes-together.md b/docs/tutorial/using-multiple-themes-together.md index 3c0d0ba61..b41b5c990 100644 --- a/docs/tutorial/using-multiple-themes-together.md +++ b/docs/tutorial/using-multiple-themes-together.md @@ -2,4 +2,410 @@ title: Using Multiple Themes Together --- -_This tutorial is coming soon. In the meantime, check out the [introduction to using multiple themes in the docs](/docs/themes/using-multiple-gatsby-themes)._ +## What this tutorial covers + +This tutorial covers how to compose multiple themes into a final site using [gatsby-theme-blog](/packages/gatsby-theme-blog/), [gatsby-theme-notes](/packages/gatsby-theme-notes/) and [gatsby-mdx-embed](/packages/@pauliescanlon/gatsby-mdx-embed/) as examples. It will also cover the concept of component shadowing with [Theme-UI](docs/theme-ui/) for styling. + +## Prerequisites + +This tutorial assumes the following: + +- That you have an understanding of [Gatsby fundamentals](/tutorial/#gatsby-fundamentals) +- An existing knowledge of [Gatsby Themes](/docs/themes/what-are-gatsby-themes/) + +## Example repository + +You can view a [full working example of this tutorial](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-themes) on GitHub. Some longer code snippets have been edited for length and the full code is available for reference in the example repository. + +## Create a new site + +Using the hello world starter create a new site and navigate to that directory. + +```shell +gatsby new multiple-themes https://github.com/gatsbyjs/gatsby-starter-hello-world +cd multiple-themes +``` + +## Install and compose the themes + +This step composes [gatsby-theme-blog](/packages/gatsby-theme-blog/) and [gatsby-theme-notes](/packages/gatsby-theme-notes/). + +1. Install the themes: + +```shell +npm install gatsby-theme-blog gatsby-theme-notes +``` + +2. Edit `gatsby-config.js` to add the themes to the plugin array and to update the site metadata: + +```javascript:title=gatsby-config.js +module.exports = { + siteMetadata: { + title: `Your Site Title`, + description: `A description for your blazing fast site, using multiple themes!`, + author: `Your name`, + social: [ + { + name: `Twitter`, + url: `https://twitter.com/gatsbyjs`, + }, + { + name: `GitHub`, + url: `https://github.com/gatsbyjs`, + }, + ], + }, + plugins: [ + { + resolve: `gatsby-theme-blog`, + options: { + basePath: `/blog`, + }, + }, + { + resolve: `gatsby-theme-notes`, + options: { + basePath: `/notes`, + }, + }, + ], +} +``` + +3. Run the site: + +```shell +gatsby develop +``` + +4. Checkout `localhost:8000` to see what is currently there. + +## Add content + +Behind the scenes, the two themes created content folders in the root directory of the site. In this step, you will add some content to these folders. + +### Add a post + +Create a new file in `/content/posts`, like this one: + +```mdx:title=content/posts/hello-posts.md +--- +title: My first blog post +date: 2020-02-15 +--- + +Multiple themes are great! +``` + +### Add a note + +Create a new file in `/content/notes`, like this one: + +```mdx:title=content/note/hello-notes.md +--- +title: My first note +date: 2020-02-20 +--- + +Multiple themes are awesome! +``` + +Restart your development server with `gatsby develop`. Now if you visit `http://localhost:8000/blog/hello-posts/` and `http://localhost:8000/notes/hello-notes` you should see your new content. + +## Add an avatar image + +Put an avatar image into the `content/assets/` directory, this is used by `gatsby-theme-blog` for the bio component. The file name can be `avatar.png` or `avatar.jpg`. + +## Put the blog posts on the homepage + +1. Delete the existing `src/pages/index.js` file. + +2. Change the theme options for the blog theme in `gatsby-config.js`: + +```javascript:title=gatsby-config.js +{ + resolve: `gatsby-theme-blog`, + options: { + // basePath defaults to `/` so this could also be included without options as just `gatsby-theme-blog`, + basePath: `/`, + }, + }, +``` + +3. Restart your development server with `gatsby develop` to test your new homepage. + +## Shadow components + +Use [theme shadowing](/docs/themes/shadowing/) to customize components the theme provides for you. + +### Shadow `bio-content.js` + +The first component to update is `bio-content.js` which provides the content used in the `gatsby-theme-blog` `bio` component. + +> 💡 Don't forget to stop and restart your development server when adding a shadowed component for the first time. + +In order to shadow the file you need to place it in the same location it exists within the theme. In this case, that means `src/gatsby-theme-blog/components/bio-content.js`. So you'll create a file structure that looks look like this: + +```text +└── src + ├── gatsby-theme-blog + │ ├── components + │ │ ├── bio-content.js // highlight-line +``` + +Feel free to make the text of your bio anything you like, but the component will look something like this: + +```jsx:title=src/gatsby-theme-blog/components/bio-content.js +import React, { Fragment } from "react" +import { Styled } from "theme-ui" + +export default () => ( + + Words by Your Name. +
+ Change me. Your awesome bio, about how great you are! + +) +``` + +### Shadow Theme-UI + +`gatsby-theme-blog` and `gatsby-theme-notes` both use [Theme-UI](/docs/theme-ui/) design tokens to manage their styling: colors, font sizes, spacing, etc. You can use component shadowing to gain control over these design tokens in the final site. + +As with your bio, you need to match the file structure of the theme. In this case, that's `src/gatsby-plugin-theme-ui/index.js` and the resulting structure will look like this: + +```text +└── src + ├── gatsby-plugin-theme-ui + │ ├── index.js //highlight-line +``` + +Feel free to use whatever colors you like, but here is an example of what you could do. + +```javascript:title=src/gatsby-plugin-theme-ui/index.js +import merge from "deepmerge" +import defaultTheme from "gatsby-theme-blog/src/gatsby-plugin-theme-ui/index" + +export default merge(defaultTheme, { + colors: { + background: "ghostwhite", + text: "black", + primary: "mediumvioletred", + modes: { + dark: { + background: "indigo", + text: "ghostwhite", + primary: "gold", + }, + }, + }, +}) +``` + +> Note that this example uses `deepmerge`. This allows you to use the Theme-UI configuration for any settings you don't override in this file. + +## Add another theme + +Themes can be big, like `gatsby-theme-blog`, but they can also be a small discrete set of components or functions. A great example of this is [gatsby-mdx-embed](https://gatsby-mdx-embed.netlify.com/) which adds the ability to embed social media content and videos directly into your MDX files. + +1. Install the theme: + +```shell +npm install @pauliescanlon/gatsby-mdx-embed +``` + +2. Update the `gatsby-config.js` file and add `gatsby-mdx-embed` as a plugin: + +```javascript:title=gatsby-config.js +module.exports = { + siteMetadata: { + // ...siteMetadata is unchanged. + }, + plugins: [ + `@pauliescanlon/gatsby-mdx-embed`, // highlight-line + { + resolve: `gatsby-theme-blog`, + options: { + basePath: `/`, + }, + }, + { + resolve: `gatsby-theme-notes`, + options: { + basePath: `/notes`, + }, + }, + ], +} +``` + +3. Test it out by adding a Youtube video to one of your blog posts: + +```mdx:title=content/posts/video-post.md +--- +title: Jason and Jackson Talk Themes +date: 2020-02-21 +--- + +Here is a video about composing and styling themes with J&J! + + +``` + +## Add a navigation menu + +Use component shadowing to add a navigation menu. You can read more about [creating dynamic navigation menus](/docs/creating-dynamic-navigation/) in the docs. + +1. Add a `menuLinks` array to `gatsby-config.js`: + +```javascript:title=gatsby-config.js +module.exports = { + siteMetadata: { + title: `Your Site Title`, + description: `A description for your blazing fast site, using multiple themes!`, + author: `Your name`, + // highlight-start + menuLinks: [ + { + name: `Blog`, + url: `/`, + }, + { + name: `Notes`, + url: `/notes`, + }, + ], + // highlight-end + social: [ + // ...social array is unchanged. + ], + }, + plugins: [ + // ...plugins array is unchanged. + ], +} +``` + +2. Create the navigation component: + +```jsx:title=src/components/navigation.js +import React from "react" +import { Link, useStaticQuery, graphql } from "gatsby" +import { Styled, css } from "theme-ui" + +export default () => { + const data = useStaticQuery( + graphql` + query SiteMetaData { + site { + siteMetadata { + menuLinks { + name + url + } + } + } + } + ` + ) + const navLinks = data.site.siteMetadata.menuLinks + return ( + + ) +} +``` + +3. When that is done the next step is to shadow `header.js` from `gatsby-theme-blog`. You can copy and paste code from the original component as a starting point for your new shadowed component. + +Your file structure should look like this: + +`src/gatsby-theme-blog/components/header.js` + +```text +└── src + ├── gatsby-theme-blog + │ ├── components + │ │ ├── header.js // highlight-line +``` + +4. Import the navigation menu and add it to the header: + +> 💡 This code snippet is edited for length the [full component can be viewed on GitHub.](/examples/using-multiple-themes/src/gatsby-theme-blog/components/header.js) + +```jsx:title=src/gatsby-theme-blog/components/header.js +import React from "react" +import Navigation from "../../components/navigation" // highlight-line +;
+
+ // highlight-line +
+
+``` + +5. Run `gatsby develop` and test the new navigation component. + +## Wrapping up + +This tutorial has introduced you to the idea of composing multiple themes together in a single Gatsby site. Gatsby Themes are an innovative rethink of the traditional website template and understanding their potential gives you a powerful new set of tools as a developer. To keep diving deeper, check out the [Gatsby Theme docs](/docs/themes/) and some of the other resources listed below. + +## What's next? + +- [Building a theme](/tutorial/building-a-theme/) + +## Other resources + +- [Using Multiple Themes Example Repo](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-themes) +- [Gatsby Themes Reference Guide](/docs/themes/) +- [Egghead.io Course: Gatsby Theme Authoring (free)](https://egghead.io/courses/gatsby-theme-authoring) +- [IBM and Gatsby Themes: Driving Impact Through Design](https://www.youtube.com/watch?v=I2nh2juOKxM) +- [Setting up yarn workspaces for Gatsby theme development](/blog/2019-05-22-setting-up-yarn-workspaces-for-theme-development/#reach-skip-nav) +- [What is component shadowing?](/blog/2019-04-29-component-shadowing/) +- [Customizing styles in Gatsby Themes with Theme-UI](/blog/2019-07-03-customizing-styles-in-gatsby-themes-with-theme-ui/) +- [Composing and styling Gatsby Themes (with Brent Jackson) — Learn With Jason](https://www.youtube.com/watch?v=6Z4p-qjnKCQ) +- [Build a Personal Site Using Gatsby Themes (with Will Johnson) — Learn With Jason](https://www.youtube.com/watch?v=vf2Dy_xKUno) From fe76da5648216b56969a0ae26090c9b92739998b Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 16:25:09 +0000 Subject: [PATCH 100/127] sync with monorepo gatsbyjs/gatsby@003129a9896cfe64595383b3fba6b3cd300387c8 - chore(docs): Remove some whitespace (#22433) --- docs/contributing/gatsby-style-guide.md | 30 ++++++++++++------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/contributing/gatsby-style-guide.md b/docs/contributing/gatsby-style-guide.md index 386d80ab2..d9561edb0 100644 --- a/docs/contributing/gatsby-style-guide.md +++ b/docs/contributing/gatsby-style-guide.md @@ -308,10 +308,10 @@ You may also choose to include line highlighting in your code snippets, using th ````no-highlight ```javascript:title=gatsby-config.js module.exports = { - siteMetadata: { - title: `GatsbyJS`, // highlight-line - siteUrl: `https://www.gatsbyjs.org`, - }, + siteMetadata: { + title: `GatsbyJS`, // highlight-line + siteUrl: `https://www.gatsbyjs.org`, + }, } ``` ```` @@ -330,11 +330,11 @@ module.exports = { ````no-highlight ```javascript:title=gatsby-config.js module.exports = { - siteMetadata: { - title: `GatsbyJS`, - // highlight-next-line - siteUrl: `https://www.gatsbyjs.org`, - }, + siteMetadata: { + title: `GatsbyJS`, + // highlight-next-line + siteUrl: `https://www.gatsbyjs.org`, + }, } ``` ```` @@ -354,12 +354,12 @@ module.exports = { ````no-highlight ```javascript:title=gatsby-config.js module.exports = { - // highlight-start - siteMetadata: { - title: `GatsbyJS`, - siteUrl: `https://www.gatsbyjs.org`, - }, - // highlight-end + // highlight-start + siteMetadata: { + title: `GatsbyJS`, + siteUrl: `https://www.gatsbyjs.org`, + }, + // highlight-end } ``` ```` From 5546897fc64c6dd473ee6bad028ec361a79c1ed6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 16:51:47 +0000 Subject: [PATCH 101/127] sync with monorepo gatsbyjs/gatsby@2d6635fd751807d419efd8ea8f19c126459820b5 - Minor fixes for Multiple Themes Tutorial (#22495) Co-authored-by: Laurie Barth --- docs/tutorial/using-multiple-themes-together.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/using-multiple-themes-together.md b/docs/tutorial/using-multiple-themes-together.md index b41b5c990..82bf842bc 100644 --- a/docs/tutorial/using-multiple-themes-together.md +++ b/docs/tutorial/using-multiple-themes-together.md @@ -4,7 +4,7 @@ title: Using Multiple Themes Together ## What this tutorial covers -This tutorial covers how to compose multiple themes into a final site using [gatsby-theme-blog](/packages/gatsby-theme-blog/), [gatsby-theme-notes](/packages/gatsby-theme-notes/) and [gatsby-mdx-embed](/packages/@pauliescanlon/gatsby-mdx-embed/) as examples. It will also cover the concept of component shadowing with [Theme-UI](docs/theme-ui/) for styling. +This tutorial covers how to compose multiple themes into a final site using [gatsby-theme-blog](/packages/gatsby-theme-blog/), [gatsby-theme-notes](/packages/gatsby-theme-notes/) and [gatsby-mdx-embed](/packages/@pauliescanlon/gatsby-mdx-embed/) as examples. It will also cover the concept of component shadowing with [Theme-UI](/docs/theme-ui/) for styling. ## Prerequisites @@ -369,7 +369,7 @@ Your file structure should look like this: 4. Import the navigation menu and add it to the header: -> 💡 This code snippet is edited for length the [full component can be viewed on GitHub.](/examples/using-multiple-themes/src/gatsby-theme-blog/components/header.js) +> 💡 This code snippet is edited for length the [full component can be viewed on GitHub.](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-themes/src/gatsby-theme-blog/components/header.js) ```jsx:title=src/gatsby-theme-blog/components/header.js import React from "react" From 07932f6a13961cf1a2ce7789e350a5b7267c4772 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 17:34:37 +0000 Subject: [PATCH 102/127] sync with monorepo gatsbyjs/gatsby@75f6ee2ac28b091f1f4dd7f8d8e7c83385ddb4b8 - fix(docs): remove double words (#22494) * typo double word * typo double word * changed remove double to fix grammer --- docs/contributing/translation/maintainers.md | 2 +- docs/contributing/translation/new-translations.md | 2 +- docs/docs/sourcing-from-graphcms.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/translation/maintainers.md b/docs/contributing/translation/maintainers.md index 92d14adcb..45487215b 100644 --- a/docs/contributing/translation/maintainers.md +++ b/docs/contributing/translation/maintainers.md @@ -40,7 +40,7 @@ The Gatsby learning team is in charge of determining priorities for which docs s Don't be afraid to ask for help! If you're not sure about something, you can post in the `#localization` channel on the [Gatsby Discord](https://gatsby.dev/discord) or create an issue in the Gatsby repo. -If it feels like there is too much work and you need help, you have the ability to to add more codeowners by editing the `CODEOWNERS` file in the repo. Are there any contributors who are making exceptional contributions? If so, consider making them a codeowner. +If it feels like there is too much work and you need help, you have the ability to add more codeowners by editing the `CODEOWNERS` file in the repo. Are there any contributors who are making exceptional contributions? If so, consider making them a codeowner. We also understand that life sometimes gets in the way. If you find that you are no longer able to satisfy your codeowner duties, let the Gatsby team know so we can figure out the best path forward. diff --git a/docs/contributing/translation/new-translations.md b/docs/contributing/translation/new-translations.md index 1a5a5e275..543e57f25 100644 --- a/docs/contributing/translation/new-translations.md +++ b/docs/contributing/translation/new-translations.md @@ -2,7 +2,7 @@ title: Starting a New Translation --- -This page lists the steps to take to create a a new Gatsbyjs.org translation. +This page lists the steps to take to create a new Gatsbyjs.org translation. ## Creating a translation diff --git a/docs/docs/sourcing-from-graphcms.md b/docs/docs/sourcing-from-graphcms.md index d826b229f..4ea87069f 100644 --- a/docs/docs/sourcing-from-graphcms.md +++ b/docs/docs/sourcing-from-graphcms.md @@ -24,7 +24,7 @@ Navigate inside of the project with `cd gatsby-site`. ### Add the source plugin -Additionally, you need the the `gatsby-source-graphql` library. Because GraphCMS uses GraphQL natively, you will take advantage of Gatsby's ability to simply stitch two GraphQL APIs together, reducing the time required to transform content. There is no need to use a special gatsby-source-x-cms plugin, the GraphQL source plugin is all you need. +Additionally, you need the `gatsby-source-graphql` library. Because GraphCMS uses GraphQL natively, you will take advantage of Gatsby's ability to simply stitch two GraphQL APIs together, reducing the time required to transform content. There is no need to use a special gatsby-source-x-cms plugin, the GraphQL source plugin is all you need. You can install this component with: From dfe8fa0becf6ab59ac4cd1fe1d09bcd345860fb4 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Mon, 23 Mar 2020 19:05:10 +0000 Subject: [PATCH 103/127] sync with monorepo gatsbyjs/gatsby@1ce34b0c1218f7aacc08940348c1b77f2a975ddf - Add ./cache to cache paths for gitlab-ci template (#22501) --- docs/docs/deploying-to-gitlab-pages.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/deploying-to-gitlab-pages.md b/docs/docs/deploying-to-gitlab-pages.md index 78b100e05..42f1a46d4 100644 --- a/docs/docs/deploying-to-gitlab-pages.md +++ b/docs/docs/deploying-to-gitlab-pages.md @@ -45,6 +45,7 @@ image: node:latest cache: paths: - node_modules/ + - .cache/ pages: script: From d29b283a0ae8645dab15a6a0105d5c897802d90d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 01:18:40 +0000 Subject: [PATCH 104/127] sync with monorepo gatsbyjs/gatsby@5a0d5dc2818f84f66fd73a75f53a57708ca6be3f - chore(doc):Add babel preset css prop to jest-preprocess.js (#22181) --- docs/docs/testing-css-in-js.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/testing-css-in-js.md b/docs/docs/testing-css-in-js.md index 3e1ed460f..7638b80e7 100644 --- a/docs/docs/testing-css-in-js.md +++ b/docs/docs/testing-css-in-js.md @@ -22,7 +22,7 @@ If you followed along with the [Unit testing guide](/docs/unit-testing) you'll h ```diff:title=jest-preprocess.js const babelOptions = { - presets: ["babel-preset-gatsby"], +~ presets: ["babel-preset-gatsby", "@emotion/babel-preset-css-prop"], + plugins: [ + "emotion", + ], From c6dc6a36f5dd4ba4397b04806f2ce192afab4ff6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 02:14:13 +0000 Subject: [PATCH 105/127] sync with monorepo gatsbyjs/gatsby@67e19962ce757920a9ed336b3f68093f372994a7 - docs: add egghead video for installing plugins (#22517) --- docs/docs/recipes/working-with-plugins.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docs/recipes/working-with-plugins.md b/docs/docs/recipes/working-with-plugins.md index 4b6b885eb..e2f0ce540 100644 --- a/docs/docs/recipes/working-with-plugins.md +++ b/docs/docs/recipes/working-with-plugins.md @@ -11,6 +11,11 @@ Found a plugin you'd like to use in your project? Awesome! You can configure it > If you'd like to take a look at available plugins, check out the [plugin library](/plugins). + + ### Prerequisites - An existing [Gatsby site](/docs/quick-start/) with a `gatsby-config.js` file From 065d7eed451e7c7c0a39314fd2de8b865e5cedba Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 12:30:51 +0000 Subject: [PATCH 106/127] sync with monorepo gatsbyjs/gatsby@b727b922327db4c19ecdda5b71facb2f5f6b121b - Remove semi-colon, working example header (#22527) --- .../using-multiple-themes-together.md | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/tutorial/using-multiple-themes-together.md b/docs/tutorial/using-multiple-themes-together.md index 82bf842bc..15abccd22 100644 --- a/docs/tutorial/using-multiple-themes-together.md +++ b/docs/tutorial/using-multiple-themes-together.md @@ -373,19 +373,25 @@ Your file structure should look like this: ```jsx:title=src/gatsby-theme-blog/components/header.js import React from "react" +import { css } from "theme-ui" import Navigation from "../../components/navigation" // highlight-line -;
-
- // highlight-line -
-
+ +export default () => { + return ( +
+
+ // highlight-line +
+
+ ) +} ``` 5. Run `gatsby develop` and test the new navigation component. From 30212142eabb77b95829e0e9c0fd5a4d048026b5 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 12:52:48 +0000 Subject: [PATCH 107/127] sync with monorepo gatsbyjs/gatsby@526de477ef73bfdbb19069b67d57b3b5013cbe16 - fix(docs): working with plugins - 404, code block language, and more... (#22502) * fix 404 * typo in filename * add language to code block * add code block about value * add code block language * add logging example from readme * remove square bracket * remove file name from code block * changed starter log output Co-authored-by: gatsbybot --- docs/docs/recipes/working-with-plugins.md | 17 +++++++++++++---- docs/docs/recipes/working-with-themes.md | 2 +- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/docs/recipes/working-with-plugins.md b/docs/docs/recipes/working-with-plugins.md index e2f0ce540..2fb344674 100644 --- a/docs/docs/recipes/working-with-plugins.md +++ b/docs/docs/recipes/working-with-plugins.md @@ -7,7 +7,7 @@ A [Gatsby plugin](/docs/what-is-a-plugin/) abstracts Gatsby APIs into an install ## Using a plugin -Found a plugin you'd like to use in your project? Awesome! You can configure it for use by following the steps below. This recipe uses the [`gatsby-source-filesystem` plugin](/plugins/gatsby-source-filesystem) as an example. +Found a plugin you'd like to use in your project? Awesome! You can configure it for use by following the steps below. This recipe uses the [`gatsby-source-filesystem` plugin](/packages/gatsby-source-filesystem/) as an example. > If you'd like to take a look at available plugins, check out the [plugin library](/plugins). @@ -28,7 +28,7 @@ Found a plugin you'd like to use in your project? Awesome! You can configure it npm install gatsby-source-filesystem ``` -2. Add the plugin to your `gatsby.config.js`, and set any options it needs, the filesystem source plugin takes a `name` and `path` as options: +2. Add the plugin to your `gatsby-config.js`, and set any options it needs, the filesystem source plugin takes a `name` and `path` as options: ```javascript:title=gatsby-config.js module.exports = { @@ -73,7 +73,7 @@ gatsby new my-plugin https://github.com/gatsbyjs/gatsby-starter-plugin The directory structure should look something like this: -``` +```text gatsby-site └── gatsby-config.js └── src @@ -97,7 +97,16 @@ module.exports = { } ``` -3. Run `gatsby develop`. To verify the plugin starter loaded correctly in your site it will log a message to the console saying it "Loaded" before the `onPreInit` step finishes. +3. Run `gatsby develop`. To verify the plugin starter loaded correctly in your site it will log a message to the console saying it "Loaded" before the `onPreInit` step finishes: + +```shell +$ gatsby develop +success open and validate gatsby-configs - 0.033s +success load plugins - 0.074s +Loaded gatsby-starter-plugin +success onPreInit - 0.016s +... +``` 4. Now you can implement [browser](/docs/browser-apis/), [server-side rendering](/docs/ssr-apis/), or [node APIs](/docs/node-apis/) and your site will run them each time it loads your plugin! diff --git a/docs/docs/recipes/working-with-themes.md b/docs/docs/recipes/working-with-themes.md index a1a73b0bc..09a26fad4 100644 --- a/docs/docs/recipes/working-with-themes.md +++ b/docs/docs/recipes/working-with-themes.md @@ -55,7 +55,7 @@ module.exports = { } ``` -4. Run `gatsby develop`, the theme should now be running on your site. In this case with the blog theme configured with the `basePath` to "/blog", it should be available at `http://localhost:8000/blog`. +4. Run `gatsby develop`, the theme should now be running on your site. In this case with the blog theme configured with the `basePath` to `"/blog"`, it should be available at `http://localhost:8000/blog`. > To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](/packages/gatsby-theme-blog/#theme-options). From 5b5ff8aeebdd5c88d60b8868785037613a5d8ec2 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 16:08:47 +0000 Subject: [PATCH 108/127] sync with monorepo gatsbyjs/gatsby@561bd6a81fad3f6ff240a0236ec50d70cfdfa0e7 - Get rid of the Newsletter page Link In contributing/community.md (#21816) * Update community.md with EmailCaptureForm * Delete newsletter.js * Update redirects.yaml with newsletter link * Removed hash from redirect.yaml --- docs/contributing/community.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/community.md b/docs/contributing/community.md index f661b9475..1662a7c52 100644 --- a/docs/contributing/community.md +++ b/docs/contributing/community.md @@ -38,7 +38,7 @@ The Gatsby community welcomes contributions. Please refer to the guides below on Sign up for the Gatsby newsletter to keep up with the latest from the Gatsby community! Hear about new features, tips & tricks, and what people are building. -[Sign up here](/newsletter/) + ### Twitter From 5bdb1bd636bb25017a501b72952355ba6d2ce62c Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 17:53:39 +0000 Subject: [PATCH 109/127] sync with monorepo gatsbyjs/gatsby@c1a74c17d283b8dfd13ce1b30c56fddf85b7adc1 - chore(starters): add gatsby-starter-service-relief (#22547) * chore(starters):add gatsby-starter-service-relief * chore: format Co-authored-by: LB Co-authored-by: gatsbybot --- docs/docs/preprocessing-external-images.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs/preprocessing-external-images.md b/docs/docs/preprocessing-external-images.md index 863186146..adcbe307c 100644 --- a/docs/docs/preprocessing-external-images.md +++ b/docs/docs/preprocessing-external-images.md @@ -43,6 +43,7 @@ exports.createSchemaCustomization = ({ actions }) => { createTypes(` type MarkdownRemark implements Node { frontmatter: Frontmatter + featuredImg: File @link(from: "featuredImg___NODE") } type Frontmatter { @@ -84,7 +85,7 @@ exports.onCreateNode = async ({ Going step by step through the code: -1. Define some types for `MarkdownRemark` using the Schema Customization API. Defining a field for alternative text as `featuredImgAlt` can also improve accessibility, in addition to providing context for the image if it fails to load. +1. Define some types for `MarkdownRemark` using the Schema Customization API. For `featuredImg`, use the `from` argument to point the `link` extension to the correct field name (with a `___NODE` suffix), [more details about foreign-key fields here](https://www.gatsbyjs.org/docs/schema-customization/#foreign-key-fields). Defining a field for alternative text as `featuredImgAlt` can also improve accessibility, in addition to providing context for the image if it fails to load. 2. Create an `onCreateNode` function so you can watch for when `MarkdownRemark` nodes are made. 3. Use `createRemoteFileNode` by passing in the various required fields and get a reference to the file afterwards. 4. If the Node is created, attach it as a child of the original Node. `___NODE` tells the GraphQL layer that the name before it is going to be a field on the parent Node that links to another Node. To do this, pass the `id` as the reference. Do note, this new node is now attached to the root of the `markdownRemark` node instead of the `frontmatter` field. From 8e92c841a38b14e2d94dc0e298988c200cf85c5d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 19:28:50 +0000 Subject: [PATCH 110/127] sync with monorepo gatsbyjs/gatsby@6f17ac8add1cf4bd6979a44c33999052bfb6ff85 - fix: social sharing for blog posts (#22535) * use lg. social image for twitter, other platforms * chore: remove extra TOC from gatsby-image doc * keep resize for backcompat, downsize img to 1500 --- docs/docs/gatsby-image.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/docs/gatsby-image.md b/docs/docs/gatsby-image.md index dc5e1e1a8..363c5dfd2 100644 --- a/docs/docs/gatsby-image.md +++ b/docs/docs/gatsby-image.md @@ -8,17 +8,6 @@ Part of what makes Gatsby sites so fast is its recommended approach to handling Demo: [https://using-gatsby-image.gatsbyjs.org/](https://using-gatsby-image.gatsbyjs.org/) -## In this doc - -- [Setting up Gatsby Image](#setting-up-gatsby-image) -- [Types of images with gatsby-image](#types-of-images-with-gatsby-image) - - [Fixed images and parameters](#images-with-a-fixed-width-and-height) - - [Fluid images and parameters](#images-that-stretch-across-a-fluid-container) - - [Resized images](#resized-images) - - [Shared query parameters](#shared-query-parameters) -- [Image query fragments](#image-query-fragments) -- [Gatsby Image props](#gatsby-image-props) - ## Setting up Gatsby Image To start working with Gatsby Image, install the `gatsby-image` package along with necessary plugins `gatsby-transformer-sharp` and `gatsby-plugin-sharp`. Reference the packages in your `gatsby-config.js` file. You can also provide additional options to [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) in your config file. From f6eb9a101f7936e47a42c6202a61acdae9b658e1 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Tue, 24 Mar 2020 22:49:34 +0000 Subject: [PATCH 111/127] sync with monorepo gatsbyjs/gatsby@b21d6e07893197e00fc54beb2811af501068e1ba - Update docs/processing-payments-with-stripe (#22431) * Update docs/processing-payments-with-stripe * Link to ecommerce example code * Edit Stripe guide changes for clarity Co-authored-by: Aisha Blake --- docs/docs/processing-payments-with-stripe.md | 80 +++----------------- 1 file changed, 12 insertions(+), 68 deletions(-) diff --git a/docs/docs/processing-payments-with-stripe.md b/docs/docs/processing-payments-with-stripe.md index e29db0b15..6fbb6414b 100644 --- a/docs/docs/processing-payments-with-stripe.md +++ b/docs/docs/processing-payments-with-stripe.md @@ -20,83 +20,27 @@ Once logged into the Stripe dashboard, you can find your API keys under the Deve While testing, you must use the key(s) that include the word test. For production code, you will need to use the live keys. As the names imply, your publishable key may be included in code that you share publicly (for example, on the frontend, and in GitHub), whereas your secret key should not be shared with anyone or committed to any public repo. It’s important to restrict access to this secret key because anyone who has it could potentially read or send requests from your Stripe account and see information about charges or purchases or even refund customers. -## Existing plugins and starters using Stripe +## Resources for using Stripe -Several plugins and starters exist to help you get up and running with Stripe. +Several tutorials, plugins and starters exist to help you get up and running with Stripe. + +### Tutorials & Videos + +- [Gatsby E-commerce Tutorial](/tutorial/ecommerce-tutorial): A step-by-step tutorial for adding Stripe Checkout to your Gatsby site. +- [Learn with Jason Episode](https://youtu.be/g4aCBNt5Pcg): Build an E-commerce Site Using Stripe and Gatsby. ### Plugins -- [gatsby-plugin-stripe](https://www.gatsbyjs.org/packages/gatsby-plugin-stripe/) -- [gatsby-source-stripe](https://www.gatsbyjs.org/packages/gatsby-source-stripe/) -- [gatsby-plugin-stripe-checkout](https://www.gatsbyjs.org/packages/gatsby-plugin-stripe-checkout/) +- [gatsby-source-stripe](https://www.gatsbyjs.org/packages/gatsby-source-stripe/): This plugin allows you to bring your product and SKU data into your Gatsby site at build time to be [used with Stripe Checkout](https://www.gatsbyjs.org/tutorial/ecommerce-tutorial/#example-2-import-skus-via-source-plugin). -### Starters +### Starters & Examples +- [Example site from the Gatsby Stripe tutorial](https://github.com/gatsbyjs/gatsby/tree/master/examples/ecommerce-tutorial-with-stripe) - [gatsby-starter-ecommerce](https://www.gatsbyjs.org/starters/parmsang/gatsby-starter-ecommerce/) - [gatsby-starter-stripe](https://www.gatsbyjs.org/starters/brxck/gatsby-starter-stripe/) -## One-time transactions - -Stripe offers two solutions to create payment forms for one-time transactions. According to the Stripe documentation, "Checkout creates a secure, Stripe-hosted payment page that lets you collect payments with just a few lines of code". Stripe Elements is an alternative to Checkout if you need more control of the look and feel of the form. - -### Creating products - -Whether you're using Checkout or Elements, you'll need to create a product on Stripe. The Stripe [Product API](https://stripe.com/docs/api/products/create) can be used to create products, or you can use the dashboard to manually create products. Select Products in the navigation, click `+ New` and fill out the form with your product info. Once you create your product, you'll be able to add SKUs, view the product ID, and more. - -### Checkout - -The [Stripe Checkout documentation](https://stripe.com/docs/payments/checkout/one-time) provides detailed information on how to setup Checkout if you're interested. Because of how Gastby is rendered, there are a few changes you'll need to make like using the `gatsby-plugin-stripe`. - -Check out the [Gatsby E-Commerce Tutorial](https://www.gatsbyjs.org/tutorial/ecommerce-tutorial/#installing-the-stripejs-plugin) to learn how to set up your account to use the "Checkout client-only integration", create products on the Stripe dashboard, and integrate Checkout with Gatsby. The tutorial will explain everything you need to start selling your products. - -### Stripe Elements - -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). - -The Stripe documentation explains how to [accept a payment](https://stripe.com/docs/payments/accept-a-payment-charges#node) using Elements. - -As described in the documentation, you'll need to: - -1. Set up Stripe (client-side) -2. Create a payment form with Elements (client-side) -3. Create a token (client-side) -4. Submit the token to your server (client-side) -5. Create a charge with the token (server-side) - -Because of how Gatsby is rendered, you'll need to make sure the window is available before loading Stripe. One way to do this is using the `useState` hook to save an instance of Stripe and the useEffect hook to load Stripe if the window is not undefined. The code snippet below shows a small example of these changes. Instead of passing your API key to the ``, you'll pass the `stripe` variable. - -```javascript -import { Elements, StripeProvider } from "react-stripe-elements" -import CustomForm from "./CustomForm" - -const CheckoutForm = props => { - const [stripe, setStripe] = useState(null) - useEffect(() => { - if (typeof window !== undefined && typeof window.Stripe !== undefined) { - setStripe(window.Stripe("pk_YOUR_PUBLISHABLE_API_KEY")) - } - }, []) - - return ( - - - - - - ) -} -``` - -## Recurring payments - -Stripe Billing is an excellent tool for creating recurring payments, even providing the ability to charge based on usage or tiered subscription plans. The [Billing documentation](https://stripe.com/docs/billing) explains the different options to set up recurring payments. The [Subscription documentation](https://stripe.com/docs/billing/subscriptions/set-up-subscription) shows how to create subscription plans, payment methods, and customers. - ## Other resources - [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) -- [Making an e-commerce Gatsby Site with Stripe](https://www.gatsbyjs.org/tutorial/ecommerce-tutorial/) +- [Stripe docs](https://stripe.com/docs) +- [Stripe testing docs](https://stripe.com/docs/testing) From 5d6a8190ce91b6c714ac32b3288bf464aaec3a00 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 03:47:40 +0000 Subject: [PATCH 112/127] sync with monorepo gatsbyjs/gatsby@0cbf6b7d07384eac1bceabc634bb071ac25ed8c0 - Merge branch cw-add-showcase-sites --- docs/docs/themes/conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/themes/conventions.md b/docs/docs/themes/conventions.md index a075925cc..658e32aef 100644 --- a/docs/docs/themes/conventions.md +++ b/docs/docs/themes/conventions.md @@ -34,7 +34,7 @@ exports.onPreBootstrap = ({ store, reporter }) => { ## Separating queries and presentational components -As a theme author, it's preferable to separate your data gathering and the components that render the data. This makes it easier for end users to be able to override a component like `PostList` or `AuthorCard` without having to write a [pageQuery](/docs/page-query) or [StaticQuery](/docs/static-query). +As a theme author, it's preferable to separate your data gathering and the components that render the data. This makes it easier for end users to be able to shadow a component like `PostList` or `AuthorCard` without having to write a [pageQuery](/docs/page-query) or [StaticQuery](/docs/static-query). ### Page queries From 162b3319836e85c19161631b36a78bf1ecb003b1 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 03:52:04 +0000 Subject: [PATCH 113/127] sync with monorepo gatsbyjs/gatsby@599fc49d580ef46a609c288120b574504651288f - Add - to end of second `gatsby-theme` prefix str (#22523) The maximal prefix is `gatsby-theme-` so make sure both instances of that string include the final `-` for consistency. --- docs/docs/themes/conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/themes/conventions.md b/docs/docs/themes/conventions.md index 658e32aef..27d99820c 100644 --- a/docs/docs/themes/conventions.md +++ b/docs/docs/themes/conventions.md @@ -7,7 +7,7 @@ As methodologies for building Gatsby Themes begin to formalize and standardize, ## Naming It's required to prefix themes with `gatsby-theme-`. So if you'd like to name your theme "awesome" you -can name it `gatsby-theme-awesome` and place that as the `name` key in your `package.json`. Prefixing themes with `gatsby-theme` enables Gatsby in identifying theme packages for compilation. +can name it `gatsby-theme-awesome` and place that as the `name` key in your `package.json`. Prefixing themes with `gatsby-theme-` enables Gatsby in identifying theme packages for compilation. ## Initializing required directories From 094a8244ee318a2d009bec2923f01a79973e8ea6 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 03:55:52 +0000 Subject: [PATCH 114/127] sync with monorepo gatsbyjs/gatsby@406eefbf6fa45950e448115c43c3a68024a95cb6 - fix link to moved section (#22332) --- docs/contributing/translation/ui-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/translation/ui-messages.md b/docs/contributing/translation/ui-messages.md index c92b43839..463acd83c 100644 --- a/docs/contributing/translation/ui-messages.md +++ b/docs/contributing/translation/ui-messages.md @@ -8,7 +8,7 @@ Most content that needs to be translated is in Markdown files in translation rep Unlike Markdown documents, UI messages are kept in the same monorepo as the gatsby source. -1. Follow the instructions for [running the Gatsby website](/contributing/blog-and-website-contributions/#making-changes-to-the-website). +1. Follow the instructions for [running the Gatsby website](/contributing/website-contributions/). 2. Go to `www/` and run `yarn lingui:add-locale [lang code]` to generate a file for your language at `src/data/locales/[lang-code]/messages.po`. 3. Translate all the strings in `[lang code]/messages.po` by editing the `msgstr` field of each message. From f2e80420076cea2dbb5ae15585081bc7a6041783 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 04:08:08 +0000 Subject: [PATCH 115/127] sync with monorepo gatsbyjs/gatsby@09d9184ff059f0b652a0cbe40ac60d574260bfd1 - Override prismjs setting in example:using-remark (#20862) * Override prismjs setting in example:using-remark * Restore changes in commit 9aefd4e * Add inline code highlighting Co-authored-by: gatsbybot --- docs/contributing/translation/ui-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/translation/ui-messages.md b/docs/contributing/translation/ui-messages.md index 463acd83c..88b48c0c6 100644 --- a/docs/contributing/translation/ui-messages.md +++ b/docs/contributing/translation/ui-messages.md @@ -76,7 +76,7 @@ msgstr: "" These represent text in interpolated strings: -``` +```javascript t`${item.title} collapse` ``` From 9caf799edd93ea19d2b96a9ae9c15a3caaec823d Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 13:03:12 +0000 Subject: [PATCH 116/127] sync with monorepo gatsbyjs/gatsby@17a01bd8f50a971d9b322b99e196b9cd34646678 - Remove JustComments (#22567) The service is shutting down and should no longer be recommended - https://just-comments.com/blog/2020-03-06-just-comments-is-shutting-down.html --- docs/docs/adding-comments.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docs/adding-comments.md b/docs/docs/adding-comments.md index 9b321a255..9cc17f2d6 100644 --- a/docs/docs/adding-comments.md +++ b/docs/docs/adding-comments.md @@ -10,7 +10,6 @@ There are many options out there for adding comment functionality, several of th - [Commento](https://commento.io) - [Facebook Comments](https://www.npmjs.com/package/react-facebook) - [Staticman](https://staticman.net) -- [JustComments](https://just-comments.com) \([official plugin for Gatsby](https://www.gatsbyjs.org/packages/gatsby-plugin-just-comments/)\) - [TalkYard](https://www.talkyard.io) - [Gitalk](https://gitalk.github.io) From 258468b95d65b3198d5361b652f673c113758b2a Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 15:21:40 +0000 Subject: [PATCH 117/127] sync with monorepo gatsbyjs/gatsby@eed89bb9cf350cb797f9a8178e1868aeacb38a2f - docs: fix language codes (#22569) Co-authored-by: Laurie Barth --- docs/docs/loading-plugins-from-your-local-plugins-folder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 2768dc950..3f5cd0132 100644 --- a/docs/docs/loading-plugins-from-your-local-plugins-folder.md +++ b/docs/docs/loading-plugins-from-your-local-plugins-folder.md @@ -49,7 +49,7 @@ _The [`onPreInit` API](/docs/node-apis/#onPreInit) is the first Node API called Then, when running your site in develop or build mode, you should see "Testing..." logged in your terminal: -```sh +```shell success open and validate gatsby-configs - 0.051s success load plugins - 1.047s Testing... // highlight-line From f1b479fd75119d74ba2545e454091821974140f7 Mon Sep 17 00:00:00 2001 From: GatsbyJS Bot Date: Wed, 25 Mar 2020 16:39:46 +0000 Subject: [PATCH 118/127] sync with monorepo gatsbyjs/gatsby@27cb45650df1c66d45afc2251f88eb5c8a3e3b5b - [docs][tutorial] Improve example a bit (#21971) * [docs][tutorial] Improve example a bit * [docs][tutorial] Apply requested changes Co-authored-by: gatsbybot --- docs/tutorial/authentication-tutorial.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/tutorial/authentication-tutorial.md b/docs/tutorial/authentication-tutorial.md index 92f61e903..087d8d0a6 100644 --- a/docs/tutorial/authentication-tutorial.md +++ b/docs/tutorial/authentication-tutorial.md @@ -307,12 +307,13 @@ import { getUser, isLoggedIn, logout } from "../services/auth" // highlight-line // highlight-start export default () => { - const content = { message: "", login: true } + let greetingMessage = "" if (isLoggedIn()) { - content.message = `Hello, ${getUser().name}` + greetingMessage = `Hello ${getUser().name}` } else { - content.message = "You are not logged in" + greetingMessage = "You are not logged in" } + return ( // highlight-end
{ borderBottom: "1px solid #d1c1e0", }} > - {content.message} {/* highlight-line */} + {greetingMessage} {/* highlight-line */}