diff --git a/packages/gatsby/index.d.ts b/packages/gatsby/index.d.ts
index 80751b15560bc..6120ac8a0c25e 100644
--- a/packages/gatsby/index.d.ts
+++ b/packages/gatsby/index.d.ts
@@ -431,12 +431,34 @@ export interface GatsbyNode<
    * transform nodes created by other plugins should implement this API.
    *
    * See also the documentation for `createNode`
-   * and [`createNodeField`](https://www.gatsbyjs.com/docs/actions/#createNodeField)
+   * and [`createNodeField`](https://www.gatsbyjs.com/docs/reference/config-files/actions/#createNodeField)
+   * @param {object} $0
+   * @param {object} $0.node A node object.
+   * @param {object} $0.actions
+   * @param {function} $0.actions.createNode Create a new node.
+   * @param {function} $0.actions.createNodeField Extend another node. The new node field is placed under the fields key on the extended node object.
    * @example
-   * exports.onCreateNode = ({ node, actions }) => {
-   *   const { createNode, createNodeField } = actions
-   *   // Transform the new node here and create a new node or
-   *   // create a new node field.
+   * exports.onCreateNode = ({ node, getNode, actions }) => {
+   *   const { createNodeField } = actions
+   *
+   *   if (node.internal.type === `MarkdownRemark`) {
+   *     const nodePath = node.fileAbsolutePath
+   *
+   *     if (nodePath.match(/\/blog\//)) {
+   *       const postSlug = createFilePath({
+   *         node,
+   *         getNode,
+   *         basePath: `src/content`,
+   *         trailingSlash: true,
+   *       })
+   *
+   *       createNodeField({
+   *         node,
+   *         name: `slug`,
+   *         value: `/blog/${postSlug}/`,
+   *       })
+   *     }
+   *   }
    * }
    */
   onCreateNode?(