chore(docs): Add example to link directive (#30253)

* chore(docs): Add example to link directive

* chore: format

Co-authored-by: gatsbybot <[email protected]>

Author: LekoArts

docs/docs/reference/graphql-data-layer/schema-customization.md

@@ -435,13 +435,42 @@ type AuthorJson implements Node {
 }
 ```
 
+This example assumes that your markdown frontmatter is in the shape of:
+
+```markdown
+---
+reviewers:
+  - jane@example.com
+  - doe@example.com
+---
+```
+
+And your author JSON looks like this:
+
+```json
+[
+  {
+    "name": "Doe",
+    "firstName": "Jane",
+    "email": "[email protected]"
+  },
+  {
+    "name": "Doe",
+    "firstName": "Zoe",
+    "email": "[email protected]"
+  }
+]
+```
+
 You provide a `@link` directive on a field and Gatsby will internally
 add a resolver that is quite similar to the one written manually above. If no
 argument is provided, Gatsby will use the `id` field as the foreign-key,
 otherwise the foreign-key has to be provided with the `by` argument. The
 optional `from` argument allows getting the field on the current type which acts as the foreign-key to the field specified in `by`.
 In other words, you `link` **on** `from` **to** `by`. This makes `from` especially helpful when adding a field for back-linking.
 
+For the above example you can read `@link` this way: Use the value from the field `Frontmatter.reviewers` and match it by the field `AuthorJson.email`.
+
 Keep in mind that in the example above, the link of `posts` in `AuthorJson` works because `frontmatter` and `author` are both objects. If, for example, the `Frontmatter` type had a list of `authors` instead (`frontmatter.authors.email`), it wouldn't work since the `by` argument doesn't support arrays. In that case, you'd have to provide a custom resolver with [Gatsby Type Builders](/docs/reference/graphql-data-layer/schema-customization/#gatsby-type-builders) or [createResolvers API](/docs/reference/graphql-data-layer/schema-customization/#createresolvers-api).
 
 > Note that when using `createTypes` to fix type inference for a foreign-key field