Document .graphql and .gql file loading with graphql.macro (#5481)

docusaurus/docs/loading-graphql-files.md

@@ -0,0 +1,71 @@
+---
+id: loading-graphql-files
+title: Loading .graphql Files
+sidebar_label: Loading .graphql Files
+---
+
+To load `.gql` and `.graphql` files, first install the [`graphql.macro`](https://www.npmjs.com/package/graphql.macro) package by running:
+
+```sh
+npm install --save graphql.macro
+```
+
+Alternatively you may use `yarn`:
+
+```sh
+yarn add graphql.macro
+```
+
+Then, whenever you want to load `.gql` or `.graphql` files, import the `loader` from the macro package:
+
+```js
+import { loader } from 'graphql.macro';
+
+const query = loader('./foo.graphql');
+```
+
+And your results get automatically inlined! This means that if the file above, `foo.graphql`, contains the following:
+
+```graphql
+gql`
+  query {
+    hello {
+      world
+    }
+  }
+`;
+```
+
+The previous example turns into:
+
+```javascript
+const query = {
+  'kind': 'Document',
+  'definitions': [{
+    ...
+  }],
+  'loc': {
+    ...
+    'source': {
+      'body': '\\\\n  query {\\\\n    hello {\\\\n      world\\\\n    }\\\\n  }\\\\n',
+      'name': 'GraphQL request',
+      ...
+    }
+  }
+};
+```
+
+You can also use the `gql` template tag the same way you would use the non-macro version from `graphql-tag` package with the added benefit of inlined parsing results.
+
+```js
+import { gql } from 'graphql.macro';
+
+const query = gql`
+  query User {
+    user(id: 5) {
+      lastName
+      ...UserEntry1
+    }
+  }
+`;
+```

docusaurus/website/i18n/en.json

@@ -94,6 +94,10 @@
         "title": "Integrating with an API Backend",
         "sidebar_label": "Integrating with an API"
       },
+      "loading-graphql-files": {
+        "title": "Loading .graphql Files",
+        "sidebar_label": "Loading .graphql Files"
+      },
       "making-a-progressive-web-app": {
         "title": "Making a Progressive Web App"
       },

docusaurus/website/sidebars.json

@@ -20,6 +20,7 @@
       "adding-a-sass-stylesheet",
       "post-processing-css",
       "adding-images-fonts-and-files",
+      "loading-graphql-files",
       "using-the-public-folder",
       "code-splitting"
     ],