chore(gatsby): Update documentation around pathPrefix and assetPrefix combination (#34226)

Author: marvinjude

docs/docs/how-to/previews-deploys-hosting/path-prefix.md

@@ -101,4 +101,4 @@ For pathnames you construct manually, there’s a helper function, [`withPrefix`
 
 The [`assetPrefix`](/docs/how-to/previews-deploys-hosting/asset-prefix/) feature can be thought of as semi-related to this feature. That feature allows your assets (non-HTML files, e.g. images, JavaScript, etc.) to be hosted on a separate domain, for example a CDN.
 
-This feature works seamlessly with `assetPrefix`. Build out your application with the `--prefix-paths` flag and you'll be well on your way to hosting an application with its assets hosted on a CDN, and its core functionality available behind a path prefix.
+This feature works seamlessly with `assetPrefix`. Build out your application with the `--prefix-paths` flag and you'll be well on your way to hosting an application with its assets hosted on a CDN, and its core functionality available behind a path prefix. If you use `assetPrefix`, your `pathPrefix` will be changed to `<assetPrefix>/<pathPrefix>`. If you need to access the same `pathPrefix` as in your `gatsby-config.js`, consider using [`basePath`](/docs/reference/config-files/node-api-helpers/#basePath).

packages/gatsby/index.d.ts

@@ -946,12 +946,23 @@ export interface ParentSpanPluginArgs extends NodePluginArgs {
 export interface NodePluginArgs {
   /**
    * Use to prefix resources URLs. `pathPrefix` will be either empty string or
-   * path that starts with slash and doesn't end with slash. Check
-   * [Adding a Path Prefix](https://www.gatsbyjs.org/docs/path-prefix/)
+   * path that starts with slash and doesn't end with slash. `pathPrefix` also
+   * becomes <assetPrefix>/<pathPrefix> when you pass both `assetPrefix` and
+   * `pathPrefix` in your `gatsby-config.js`.
+   *
+   * See [Adding a Path Prefix](https://www.gatsbyjs.com/docs/how-to/previews-deploys-hosting/path-prefix/)
    * page for details about path prefixing.
    */
   pathPrefix: string
 
+  /**
+   * This is the same as `pathPrefix` passed in `gatsby-config.js`.
+   * It's an empty string if you don't pass `pathPrefix`.
+   * When using assetPrefix, you can use this instead of pathPrefix to recieve the string you set in `gatsby-config.js`.
+   * It won't include the `assetPrefix`.
+   */
+  basePath: string
+
   /**
    * Collection of functions used to programmatically modify Gatsby’s internal state.
    */

packages/gatsby/src/utils/api-node-docs.ts

@@ -437,6 +437,13 @@ export const onPreBuild = true
 /**
  * The last extension point called after all other parts of the build process
  * are complete.
+ *
+ * @example
+ * exports.onPostBuild = ({ reporter, basePath, pathPrefix }) => {
+ *  reporter.info(
+ *   `Site was built with basePath: ${basePath} & pathPrefix: ${pathPrefix}`
+ *  );
+ * };
  */
 export const onPostBuild = true
 

packages/gatsby/src/utils/api-node-helpers-docs.js

@@ -302,9 +302,21 @@ module.exports.tracing = true;
 
 /**
  * Use to prefix resources URLs. `pathPrefix` will be either empty string or
- * path that starts with slash and doesn't end with slash. Check
- * [Adding a Path Prefix](https://www.gatsbyjs.org/docs/path-prefix/)
+ * path that starts with slash and doesn't end with slash. `pathPrefix` also
+ * becomes <assetPrefix>/<pathPrefix> when you pass both `assetPrefix` and
+ * `pathPrefix` in your `gatsby-config.js`.
+ *
+ * See [Adding a Path Prefix](https://www.gatsbyjs.com/docs/how-to/previews-deploys-hosting/path-prefix/)
  * page for details about path prefixing.
  * @type {string}
  */
 module.exports.pathPrefix = true;
+
+/**
+ * This is the same as `pathPrefix` passed in `gatsby-config.js`.
+ * It's an empty string if you don't pass `pathPrefix`.
+ * When using assetPrefix, you can use this instead of pathPrefix to recieve the string you set in `gatsby-config.js`.
+ * It won't include the `assetPrefix`.
+ * @type {string}
+ */
+module.exports.basePath = true;