docs: Link mapping to @link (#16152)

* docs: Link mapping to @link * Add clarifying line
gatsbyjs · Aug 5, 2019 · 2aa002b · 2aa002b
1 parent f6aa41e
commit 2aa002b
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 0 deletions.
diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md
@@ -87,6 +87,8 @@ See more about [Browser Support](/docs/browser-support/#polyfills) in Gatsby.
 
 Gatsby includes an advanced feature that lets you create "mappings" between node types.
 
+> Note: Gatsby v2.2 introduced a new way to create foreign-key relations between node types with [the `@link` GraphQL field extension](/docs/schema-customization/#foreign-key-fields).
+
 For instance, imagine you have a multi-author markdown blog where you want to "link" from each blog post to the author information stored in a yaml file named `author.yaml`:
 
 ```markdown

diff --git a/docs/docs/schema-customization.md b/docs/docs/schema-customization.md
@@ -319,6 +319,10 @@ Gatsby's automatic type inference has one trick up its sleeve: for every field
 that ends in `___NODE` it will interpret the field value as an `id` and create a
 foreign-key relation.
 
+> Note: Before the introduction of the Schema Customization APIs in Gatsby v2.2,
+> there were two mechanisms to create links between node types: a plugin author would use the `___NODE`
+> fieldname convention (for plugins), and a user would define [mappings](/docs/gatsby-config/#mapping-node-types) between fields in their `gatsby-config.js`. Both users and plugin authors can now use the `@link` extension described below.
+
 Creating foreign-key relations with the `createTypes` action,
 i.e. without relying on type inference and the `___NODE` field naming
 convention, requires a bit of manual setup.