feat: File System Route API - General Availability (#27424)

Co-authored-by: Peter van der Zee <[email protected]>
Co-authored-by: Megan Sullivan <[email protected]>
Co-authored-by: gatsbybot <[email protected]>

Author: 4 people

benchmarks/gabe-fs-markdown-route-api/package.json

@@ -7,10 +7,10 @@
   "version": "0.1.0",
   "license": "MIT",
   "scripts": {
-    "bench": "rm -rf generated_articles; gatsby clean; N=${N:-512} node gen.js; CI=1 GATSBY_EXPERIMENTAL_ROUTING_APIS=1 node --max_old_space_size=${M:-2}000 node_modules/.bin/gatsby build",
-    "build": "GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby build",
+    "bench": "rm -rf generated_articles; gatsby clean; N=${N:-512} node gen.js; CI=1 node --max_old_space_size=${M:-2}000 node_modules/.bin/gatsby build",
+    "build": "gatsby build",
     "clean": "gatsby clean",
-    "develop": "GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby develop",
+    "develop": "gatsby develop",
     "format": "prettier --write \"**/*.{js,jsx,json,md}\""
   },
   "devDependencies": {

docs/docs/creating-and-modifying-pages.md

@@ -6,13 +6,13 @@ Gatsby makes it easy to programmatically control your pages.
 
 Pages can be created in three ways:
 
-- In your site's gatsby-node.js by implementing the API
-  [`createPages`](/docs/node-apis/#createPages)
-- Gatsby core automatically turns React components in `src/pages/*` into pages. Note that you must make the component the [default export](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export)
-- Plugins can also implement `createPages` and create pages for you
+- By creating React components in the `src/pages` directory. (Note that you must make the component the [default export](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export).)
+- By using the [File System Route API](/docs/file-system-route-api/) to programmatically create pages from GraphQL and to create client-only routes.
+- In your site's `gatsby-node.js` file, by implementing the API [`createPages`](/docs/node-apis/#createPages). ([Plugins](/docs/plugins/) can also implement `createPages` and create pages for you.)
 
-You can also implement the API [`onCreatePage`](/docs/node-apis/#onCreatePage)
-to modify pages created in core or plugins or to create [client-only routes](/docs/client-only-routes-and-user-authentication/).
+Pages can also be modified by you after their creation. For example, you could change the `path` to create internationalized routes (see [gatsby-theme-i18n](https://github.com/gatsbyjs/themes/blob/1ddd07c4248239e6323833c6d6d572ac0a0d57a1/packages/gatsby-theme-i18n/gatsby-node.js#L132-L172) for instance) by implementing the API [`onCreatePage`](/docs/node-apis/#onCreatePage).
+
+> **Note:** For most use cases you'll be able to use the [File System Route API](/docs/file-system-route-api/) to create pages. Please read on if you need more control over the page creation or consume data outside of Gatsby's GraphQL data layer.
 
 ## Debugging help
 
@@ -264,6 +264,6 @@ export default Page
 
 Page context is serialized before being passed to pages. This means it can't be used to pass functions into components and `Date` objects will be serialized into strings.
 
-## Creating Client-only routes
+## Creating client-only routes
 
-In specific cases, you might want to create a site with client-only portions that are gated by authentication. For more on how to achieve this, refer to [client-only routes & user authentication](https://www.gatsbyjs.com/docs/client-only-routes-and-user-authentication/).
+In specific cases, you might want to create a site with client-only portions that are gated by authentication. For more on how to achieve this, refer to [client-only routes & user authentication](/docs/client-only-routes-and-user-authentication/).