feat(gatsby-source-wordpress): use env var to disable catch links (#36141)

* use env var to disable catch links

* Update gatsby-link.md

* convert to plugin option instead of env var

Author: TylerBarnes

packages/gatsby-source-wordpress/docs/features/gatsby-link.md

@@ -4,4 +4,29 @@ Anchor tag src's in html that are links to your WP instance are automatically re
 
 Anchor tags in html that are relative links automatically become `gatsby-link`'s so that navigation via html links are blazing fast.
 
+## `gatsby-plugin-catch-links`
+
+Because links in html fields are so common in WordPress, `gatsby-source-wordpress` auto-installs `gatsby-plugin-catch-links` for you. In 99% of cases this works well, but for some sites you may need to configure catch-links yourself. You can disable the automatically included version of `gatsby-plugin-catch-links` by setting the `catchLinks` plugin option to `false`. Once it's disabled you can install it yourself and configure its plugin options in your gatsby-config.js
+
+Example `gatsby-config.js` file:
+
+```js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-source-wordpress`,
+      options: {
+        catchLinks: false,
+      },
+    },
+    {
+      resolve: `gatsby-plugin-catch-links`,
+      options: {
+        // add the options you need here.
+      },
+    },
+  ],
+}
+```
+
 :point_left: [Back to Features](./index.md)

packages/gatsby-source-wordpress/docs/plugin-options.md

@@ -42,6 +42,7 @@
 - [searchAndReplace](#searchandreplace)
   - [searchAndReplace[].search](#searchandreplacesearch)
   - [searchAndReplace[].replace](#searchandreplacereplace)
+- [catchLinks](#catchlinks)
 - [html](#html)
   - [html.useGatsbyImage](#htmlusegatsbyimage)
   - [html.gatsbyImageOptions](#htmlgatsbyimageoptions)
@@ -870,6 +871,24 @@ The replacement string for each regex match.
 
 ```
 
+## catchLinks
+
+Turns on/off an automatically included copy of gatsby-plugin-catch-links which is used to catch anchor tags in html fields to perform client-side routing instead of full page refreshes.
+
+**Field type**: `Boolean`
+
+**Default value**: `true`
+
+```js
+{
+  resolve: `gatsby-source-wordpress`,
+  options: {
+    catchLinks: false,
+  },
+}
+
+```
+
 ## html
 
 Options related to html field processing.

packages/gatsby-source-wordpress/gatsby-config.js

@@ -1,7 +1,11 @@
-module.exports = {
-  plugins: [
-    `gatsby-plugin-catch-links`,
-    `gatsby-plugin-image`,
-    `gatsby-plugin-sharp`,
-  ],
+module.exports = ({ catchLinks = true }) => {
+  const plugins = [`gatsby-plugin-image`, `gatsby-plugin-sharp`]
+
+  if (catchLinks) {
+    plugins.push(`gatsby-plugin-catch-links`)
+  }
+
+  return {
+    plugins,
+  }
 }

packages/gatsby-source-wordpress/src/steps/declare-plugin-options-schema.js

@@ -591,6 +591,17 @@ When using this option, be sure to gitignore the wordpress-cache directory in th
           ],
         `),
       }),
+    catchLinks: Joi.boolean()
+      .default(true)
+      .allow(null)
+      .description(
+        `Turns on/off an automatically included copy of gatsby-plugin-catch-links which is used to catch anchor tags in html fields to perform client-side routing instead of full page refreshes.`
+      )
+      .meta({
+        example: wrapOptions(`
+          catchLinks: false,
+        `),
+      }),
     html: Joi.object({
       useGatsbyImage: Joi.boolean()
         .default(true)