Document .graphql and .gql file loading with graphql.macro

docusaurus/docs/loading-graphql-files.md

@@ -0,0 +1,60 @@
+---
+id: loading-graphql-files
+title: Loading .graphql Files
+sidebar_label: Loading .graphql Files
+---
+
+You can load `.gql` and `.graphql` files by using [`babel-plugin-macros`](https://github.com/kentcdodds/babel-plugin-macros) included with Create React App.
+
+To load the files, first install the [`graphl-tag.macro`](https://www.npmjs.com/package/graphql-tag.macro) package by running
+
+```sh
+npm install --save-dev graphl-tag.macro
+```
+
+Alternatively you may use `yarn`:
+
+```sh
+yarn add --dev graphql-tag.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.

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

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