docs: Document query fragment usage (#130)

* docs: Table for configuration options * docs: Add features list * docs: Document query fragment usage * docs: Formatting * docs: Rephrasing * style(lint): prettier --write * docs: Formatting
hygraph · Oct 21, 2020 · fc1ba08 · fc1ba08
1 parent fc25c39
commit fc1ba08
Showing 1 changed file with 72 additions and 33 deletions.
diff --git a/gatsby-source-graphcms/README.md b/gatsby-source-graphcms/README.md
@@ -53,39 +53,24 @@ module.exports = {
 
 ### Options
 
-- `endpoint` _String_ (**required**)
+| Key                   | Type                                     | Description                                                                                                                                                                                                                                                                                                                            |
+| --------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `endpoint`            | _String_ (**required**)                  | The endpoint URL for the GraphCMS project. This can be found in the [project settings UI](https://graphcms.com/docs/guides/concepts/apis#working-with-apis).                                                                                                                                                                           |
+| `token`               | String                                   | If your GraphCMS project is **not** publicly accessible, you will need to provide a [Permanent Auth Token](https://graphcms.com/docs/reference/authorization) to correctly authorize with the API. You can learn more about creating and managing API tokens [here](https://graphcms.com/docs/guides/concepts/apis#working-with-apis). |
+| `typePrefix`          | String _(Default: `GraphCMS_`)_         | The string by which every generated type name is prefixed with. For example, a type of `Post` in GraphCMS would become `GraphCMS_Post` by default. If using multiple instances of the source plugin, you **must** provide a value here to prevent type conflicts.                                                                      |
+| `downloadLocalImages` | Boolean _(Default: `false`)_             | Download and cache GraphCMS image assets in your Gatsby project. [Learn more](#downloading-local-image-assets).                                                                                                                                                                                                                        |
+| `buildMarkdownNodes`  | Boolean _(Default: `false`)_             | Build markdown nodes for all [`RichText`](https://graphcms.com/docs/reference/fields/rich-text) fields in your GraphCMS schema. [Learn more](#using-markdown-nodes).                                                                                                                                                                   |
+| `fragmentsPath`       | String _(Default: `graphcms-fragments`)_ | The local project path where generated query fragments are saved. This is relative to your current working directory. If using multiple instances of the source plugin, you **must** provide a value here to prevent type and/or fragment conflicts.                                                                                   |
+| `locales`             | [String] _(Default: `['en']`)_           | An array of locale key strings from your GraphCMS project. [Learn more](#querying-localised-nodes). You can read more about working with localisation in GraphCMS [here](https://graphcms.com/docs/guides/concepts/i18n).                                                                                                              |
 
-  - The endpoint URL for the GraphCMS project. This can be found in the [project settings UI](https://graphcms.com/docs/guides/concepts/apis#working-with-apis).
+## Features
 
-- `token` _String_
+- [Querying localised nodes](#querying-localised-nodes)
+- [Downloading local image assets](#downloading-local-image-assets)
+- [Using markdown nodes](#using-markdown-nodes)
+- [Working with query fragments](#working-with-query-fragments)
 
-  - If your GraphCMS project is **not** publicly accessible, you will need to provide a [Permanent Auth Token](https://graphcms.com/docs/reference/authorization) to correctly authorize with the API. You can learn more about creating and managing API tokens [here](https://graphcms.com/docs/guides/concepts/apis#working-with-apis).
-
-- `typePrefix` _String_ (default value: `GraphCMS_`)
-
-  > If using multiple instances of the source plugin, you **must** provide a value here to prevent type conflicts.
-
-  - The string by which every generated type name is prefixed with. For example, a type of `Post` in GraphCMS would become `GraphCMS_Post` by default.
-
-- `downloadLocalImages` _Boolean_ (default value: `false`)
-
-  - Download and cache GraphCMS image assets in your Gatsby project. [Learn more](#downloading-local-image-assets).
-
-- `buildMarkdownNodes` _Boolean_ (default value: `false`)
-
-  - Build markdown nodes for all [`RichText`](https://graphcms.com/docs/reference/fields/rich-text) fields in your GraphCMS schema. [Learn more](#using-markdown-nodes).
-
-- `fragmentsPath` _String_ (default value: `graphcms-fragments`)
-
-  > If using multiple instances of the source plugin, you **must** provide a value here to prevent type and/or fragment conflicts.
-
-  - The local project path where generated query fragments are saved. This is relative to your current working directory.
-
-- `locales` _[String]_ (default value: `['en']`)
-
-  - An array of locale key strings from your GraphCMS project. [Learn more](#querying-localised-nodes). You can read more about working with localisation in GraphCMS [here](https://graphcms.com/docs/guides/concepts/i18n).
-
-## Querying localised nodes
+### Querying localised nodes
 
 If using GraphCMS localisation, this plugin provides support to build nodes for all provided locales.
 
@@ -120,7 +105,7 @@ To query for nodes for a specific locale, use the `filter` query argument.
 
 Check out the [demo source](https://github.com/GraphCMS/gatsby-source-graphcms/tree/next/demo) for an example of a localisation implementation.
 
-## Downloading local image assets
+### Downloading local image assets
 
 This source plugin provides the option to download and cache GraphCMS assets in your Gatsby project. This enables you to use [`gatsby-image`](https://www.gatsbyjs.org/packages/gatsby-image), for image loading optimizations, with your GraphCMS image assets.
 
@@ -163,7 +148,7 @@ You can then use the fragments from [`gatsby-transformer-sharp`](https://www.gat
 
 For more information on using `gatsby-image`, please see the [documentation](https://www.gatsbyjs.org/packages/gatsby-image/?=#how-to-use).
 
-## Using markdown nodes
+### Using markdown nodes
 
 This source plugin provides the option to build markdown nodes for all `RichText` fields in your GraphCMS schema, which in turn can be used with [MDX](https://mdxjs.com).
 
@@ -186,7 +171,7 @@ module.exports = {
 
 Enabling this option adds a `markdownNode` nested field to all `RichText` fields on the generated Gatsby schema.
 
-### Usage with `gatsby-plugin-mdx`
+#### Usage with `gatsby-plugin-mdx`
 
 These newly built nodes can be used with [`gatsby-plugin-mdx`](https://www.gatsbyjs.org/packages/gatsby-plugin-mdx) to render markdown from GraphCMS.
 
@@ -210,3 +195,57 @@ Once installed, you will be able to query for `MDX` fields using a query similar
 ```
 
 Check out the [demo source](https://github.com/GraphCMS/gatsby-source-graphcms/tree/next/demo) for an example of a full MDX implementation.
+
+### Working with query fragments
+
+The source plugin will generate and save GraphQL query fragments for every node type. By default, they will be saved in a `graphcms-fragments` directory at the root of your Gatsby project. This can be configured:
+
+> If using multiple instances of the source plugin, you **must** provide a value to prevent type and/or fragment conflicts.
+
+```js
+// gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: 'gatsby-source-graphcms',
+      options: {
+        endpoint: process.env.GRAPHCMS_ENDPOINT,
+        fragmentsPath: 'my-query-fragments',
+      },
+    },
+  ],
+}
+```
+
+The generated fragments are then read from the project for subsequent builds. It is recommended that they are checked in to version control for your project.
+
+Should you make any changes or additions to your GraphCMS schema, you will need to update the query fragments accrdingly. Alternatively they will be regnerated on a subsequent build after removing the directory from your project.
+
+#### Modifying query fragments
+
+In some instances, you may need modify query fragments on a per type basis. This may involve:
+
+- Removing unrequired fields
+- Adding new fields with arguments as an aliased field
+
+For example, adding a `featuredCaseStudy` field:
+
+```graphql
+fragment Industry on Industry {
+  featuredCaseStudy: caseStudies(where: { featured: true }, first: 1)
+}
+```
+
+Field arguments cannot be read by Gatsby from the GraphCMS schema. Instead we must alias any required usages as aliased fields. In this example, the `featuredCaseStudy` field would then be available in our Gatsby queries:
+
+```graphql
+{
+  allGraphCmsIndustry {
+    nodes {
+      featuredCaseStudy {
+        ...
+      }
+    }
+  }
+}
+```