feat(www): Convert API pages to MDX

docs/docs/actions.md

@@ -0,0 +1,19 @@
+---
+title: Actions
+description: Documentation on actions and how they help you manipulate state within Gatsby
+jsdoc:
+  - "gatsby/src/redux/actions/public.js"
+  - "gatsby/src/redux/actions/restricted.js"
+contentsHeading: Functions
+---
+
+Gatsby uses [Redux](http://redux.js.org) internally to manage state. When you implement a Gatsby API, you are passed a collection of actions (equivalent to actions bound with [bindActionCreators](https://redux.js.org/api/bindactioncreators/) in Redux) which you can use to manipulate state on your site.
+
+The object `actions` contains the functions and these can be individually extracted by using ES6 object destructuring.
+
+```javascript
+// For function createNodeField
+exports.onCreateNode = ({ node, getNode, actions }) => {
+  const { createNodeField } = actions
+}
+```

docs/docs/browser-apis.md

@@ -0,0 +1,11 @@
+---
+title: Gatsby Browser APIs
+description: Documentation about leveraging standard browser APIs within Gatsby
+jsdoc: ["gatsby/src/utils/api-browser-docs.js"]
+apiCalls: BrowserAPI
+showTopLevelSignatures: true
+---
+
+## Usage
+
+Implement any of these APIs by exporting them from a file named `gatsby-browser.js` in the root of your project.

docs/docs/node-api-helpers.md

@@ -0,0 +1,31 @@
+---
+title: Node API Helpers
+description: Documentation on API helpers for creating nodes within Gatsby's GraphQL data layer
+jsdoc: ["gatsby/src/utils/api-node-helpers-docs.js"]
+apiCalls: NodeAPIHelpers
+contentsHeading: Shared helpers
+showTopLevelSignatures: true
+---
+
+The first argument passed to each of [Gatsby’s Node APIs](/docs/node-apis/) is an object containing a set of helpers. Helpers shared by all Gatsby’s Node APIs are documented in [Shared helpers](#shared-helpers) section.
+
+```javascript
+// in gatsby-node.js
+exports.createPages = gatsbyNodeHelpers => {
+  const { actions, reporter } = gatsbyNodeHelpers
+  // use helpers
+}
+```
+
+Common convention is to destructure helpers right in argument list:
+
+```javascript
+// in gatsby-node.js
+exports.createPages = ({ actions, reporter }) => {
+  // use helpers
+}
+```
+
+## Note
+
+Some APIs provide additional helpers. For example `createPages` provides `graphql` function. Check documentation of specific APIs in [Gatsby Node APIs](/docs/node-apis/) for details.

docs/docs/node-apis.md

@@ -0,0 +1,33 @@
+---
+title: Gatsby Node APIs
+description: Documentation on Node APIs used in Gatsby build process for common uses like creating pages
+jsdoc: ["gatsby/src/utils/api-node-docs.js"]
+apiCalls: NodeAPI
+---
+
+Gatsby gives plugins and site builders many APIs for controlling your site's data in the GraphQL data layer.
+
+## Async plugins
+
+If your plugin performs async operations (disk I/O, database access, calling remote APIs, etc.) you must either return a promise or use the callback passed to the 3rd argument. Gatsby needs to know when plugins are finished as some APIs, to work correctly, require previous APIs to be complete first. See [Debugging Async Lifecycles](/docs/debugging-async-lifecycles/) for more info.
+
+```javascript
+// Promise API
+exports.createPages = () => {
+  return new Promise((resolve, reject) => {
+    // do async work
+  })
+}
+
+// Callback API
+exports.createPages = (_, pluginOptions, cb) => {
+  // do Async work
+  cb()
+}
+```
+
+If your plugin does not do async work, you can just return directly.
+
+## Usage
+
+Implement any of these APIs by exporting them from a file named `gatsby-node.js` in the root of your project.

docs/docs/node-model.md

@@ -0,0 +1,28 @@
+---
+title: Node Model
+description: Documentation explaining the model of nodes in Gatsby's GraphQL data layer
+jsdoc: ["gatsby/src/schema/node-model.js"]
+apiCalls: NodeModel
+contentsHeading: Methods
+---
+
+Gatsby exposes its internal data store and query capabilities to GraphQL field resolvers on `context.nodeModel`.
+
+## Example Usage
+
+```javascript:title=gatsby-node.js
+createResolvers({
+  Query: {
+    mood: {
+      type: `String`,
+      resolve(source, args, context, info) {
+        const coffee = context.nodeModel.getAllNodes({ type: `Coffee` })
+        if (!coffee.length) {
+          return 😞
+        }
+        return 😊
+      },
+    },
+  },
+})
+```

docs/docs/ssr-apis.md

@@ -0,0 +1,11 @@
+---
+title: Gatsby Server Rendering APIs
+description: Documentation on APIs related to server side rendering during Gatsby's build process
+jsdoc: ["gatsby/cache-dir/api-ssr-docs.js"]
+apiCalls: SSRAPI
+showTopLevelSignatures: true
+---
+
+## Usage
+
+Implement any of these APIs by exporting them from a file named `gatsby-ssr.js` in the root of your project.

packages/gatsby/src/redux/actions/public.js

@@ -544,8 +544,10 @@ actions.deleteNode = (options: any, plugin: Plugin, args: any) => {
   }
 }
 
+// Marked private here because it was supressed in documentation pages.
 /**
  * Batch delete nodes
+ * @private
  * @param {Array} nodes an array of node ids
  * @example
  * deleteNodes([`node1`, `node2`])
@@ -582,8 +584,11 @@ actions.deleteNodes = (nodes: any[], plugin: Plugin) => {
 let NODE_COUNTER = 0
 
 const typeOwners = {}
+
+// memberof notation is added so this code can be referenced instead of the wrapper.
 /**
  * Create a new node.
+ * @memberof actions
  * @param {Object} node a node object
  * @param {string} node.id The node's ID. Must be globally unique.
  * @param {string} node.parent The ID of the parent's node. If the node is