DEVDOCS-4719: [migrate] Upgrade docs to new Dev Center syntax and spe…

…c standards (#1212) Co-authored-by: Sarah Riehl <[email protected]> Co-authored-by: Traci Porter <[email protected]> Co-authored-by: Andrea Dao <[email protected]> Co-authored-by: Tina Gomez <[email protected]> Co-authored-by: Constanze Kratel <[email protected]> Co-authored-by: Mark Murphy <[email protected]> Co-authored-by: Katie Hoesley <[email protected]> Co-authored-by: Stephen Hilliard <[email protected]> Co-authored-by: Heather Barr <[email protected]> Co-authored-by: Matthew Volk <[email protected]> Co-authored-by: Nate Stewart <[email protected]>
bigcommerce · Mar 10, 2023 · 6c7a67f · 6c7a67f
1 parent 16bf158
commit 6c7a67f
Show file tree

Hide file tree

Showing 118 changed files with 14,051 additions and 12,272 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,10 @@
+{
+  "extends": ["plugin:mdx/recommended"],
+  // optional, if you want to lint code blocks at the same time
+  "settings": {
+    "mdx/code-blocks": true,
+    // optional, if you want to disable language mapper, set it to `false`
+    // if you want to override the default language mapper inside, you can provide your own
+    "mdx/language-mapper": {}
+  }
+}
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -0,0 +1,16 @@
+name: lint-valid-mdx
+on:
+  - pull_request
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js v17.x
+        uses: actions/setup-node@v3
+        with:
+          node-version: 17.x
+      - run: npm ci
+      - run: npm run lint
diff --git a/.gitignore b/.gitignore
@@ -1 +1,4 @@
 .idea
+node_modules
+.DS_Store
+
diff --git a/docs/available-apis.md → docs/available-apis.mdx b/docs/available-apis.md → docs/available-apis.mdx
@@ -1,64 +1,64 @@
-# Available APIs
-
-## Storefront APIs
-
-### REST
-
-Manage a shopper's cart and checkout and fetch order data via client-side JavaScript on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts.
-
-[Learn more about storefront APIs](/api-docs/storefront/overview).
-
-### GraphQL
-
-Use GraphQL to query data for headless storefronts and BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts.
-
-[Learn more about the GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview)
-
-### Add to cart URLs
-
-Append query string parameters to product and `/cart.php` URLs to pre-select a SKU or add a product to cart. Use these parameters to build custom add to cart links and forms on BigCommerce hosted storefronts and remote sites (such as WordPress, blog posts, and social media).
-
-[Learn more about add to cart URLs](/api-docs/cart-and-checkout/add-to-cart-url).
-
-### Current Customer
-
-Identify logged-in customers securely via JavaScript.
-
-[Learn more about the current customer API](/api-docs/customers/current-customer-api).
-
-### Customer Login SSO
-
-Enable single sign-on for shoppers on BigCommerce hosted storefronts.
-
-[Learn more about the customer login API](/api-docs/customers/customer-login-api).
-
-## Management APIs
-
-### V2 REST API
-
-Mananage store resources from server-side code.
-
-Some **V2** resources are not yet exposed in the **V3 API**; however, for resources that are accessible via both APIs, the **V3 API** is recommended; it contains performance optimizations and [other improvements](#v3-rest-api).
-
-### V3 REST API
-
-Mananage store resources from server-side code.
-
-Interactions with the **V3** API are very similar to that of the **V2** API; however, the **V3** API introduces a number of improvements:
-* Most tasks can be performed with fewer API calls (for example, a product with variants and custom fields can be created in a single request)
-* Each **V3** resource includes a `meta` object, simplifying pagination
-* **V3** Brands, Categories, Products, and Product Variants expose a [metafields](/api-reference/catalog/catalog-api/product-metafields/createproductmetafield) resource for use by developers to store custom data.
-* **V3** API is optimized for performance (in general, data can be sent, received, and processed faster via **V3**, relative to **V2**).
-
-[Learn more about the V3 API](/api-docs/getting-started/about-our-api).
-
-## Provider APIs
-
-Implement endpoints consumed by BigCommerce for custom integrations (ex: custom shipping carrier rates via `/rates`).
-
-[Learn more about the Shipping Provider API](/api-docs/store-management/shipping/shipping-provider-api).
-
-## Resources
-
-- [Deprecations and Sunsets](/api-docs/getting-started/deprecations-and-sunsets)
-- [Difference between V2 and V3 Catalog REST APIs](/api-docs/store-management/catalog/v2-vs-v3)
+# Available APIs
+
+## Storefront APIs
+
+### REST
+
+Manage a shopper's cart and checkout and fetch order data via client-side JavaScript on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts.
+
+[Learn more about storefront APIs](/api-docs/storefront/overview).
+
+### GraphQL
+
+Use GraphQL to query data for headless storefronts and BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts.
+
+[Learn more about the GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview)
+
+### Add to cart URLs
+
+Append query string parameters to product and `/cart.php` URLs to pre-select a SKU or add a product to cart. Use these parameters to build custom add to cart links and forms on BigCommerce hosted storefronts and remote sites (such as WordPress, blog posts, and social media).
+
+[Learn more about add to cart URLs](/api-docs/cart-and-checkout/add-to-cart-url).
+
+### Current Customer
+
+Identify logged-in customers securely via JavaScript.
+
+[Learn more about the current customer API](/api-docs/customers/current-customer-api).
+
+### Customer Login SSO
+
+Enable single sign-on for shoppers on BigCommerce hosted storefronts.
+
+[Learn more about the customer login API](/api-docs/customers/customer-login-api).
+
+## Management APIs
+
+### V2 REST API
+
+Mananage store resources from server-side code.
+
+Some **V2** resources are not yet exposed in the **V3 API**; however, for resources that are accessible via both APIs, the **V3 API** is recommended; it contains performance optimizations and [other improvements](#v3-rest-api).
+
+### V3 REST API
+
+Mananage store resources from server-side code.
+
+Interactions with the **V3** API are very similar to that of the **V2** API; however, the **V3** API introduces a number of improvements:
+* Most tasks can be performed with fewer API calls (for example, a product with variants and custom fields can be created in a single request)
+* Each **V3** resource includes a `meta` object, simplifying pagination
+* **V3** Brands, Categories, Products, and Product Variants expose a [metafields](/docs/rest-management/catalog/product-metafields#create-a-product-metafield) resource for use by developers to store custom data.
+* **V3** API is optimized for performance (in general, data can be sent, received, and processed faster via **V3**, relative to **V2**).
+
+[Learn more about the V3 API](/api-docs/getting-started/about-our-api).
+
+## Provider APIs
+
+Implement endpoints consumed by BigCommerce for custom integrations (ex: custom shipping carrier rates via `/rates`).
+
+[Learn more about the Shipping Provider API](/api-docs/store-management/shipping/shipping-provider-api).
+
+## Resources
+
+- [Deprecations and Sunsets](/api-docs/getting-started/deprecations-and-sunsets)
+- [Difference between V2 and V3 Catalog REST APIs](/api-docs/store-management/catalog/v2-vs-v3)
diff --git a/docs/customer-login-sso.md → docs/customer-login-sso.mdx b/docs/customer-login-sso.md → docs/customer-login-sso.mdx
@@ -1,20 +1,21 @@
 # Customer Login SSO
 
-* **Host**: {store_domain}/graphql
+* **Host**: `{store_domain}/graphql`
 * **Protocols**:`https`
 * **Accepts**: `application/json`
 * **Responds With**: `application/json`
 
 
-Download Spec: [customer_login.json](https://bigcommerce.stoplight.io/api/v1/projects/bigcommerce/api-reference/nodes/reference/customer_login.yml?branch=master&amp;deref=all&amp;format=json)
+Download Spec: [customer_login.json](#)
+{/* https://bigcommerce.stoplight.io/api/v1/projects/bigcommerce/api-reference/nodes/reference/customer_login.yml?branch=master&amp;deref=all&amp;format=json */}
 
 Create a login URL for customer single sign-on.
 
 ## Authentication
 
 To log in a customer using the Customer Login API, redirect the customer's browser to the following access point URL:
 
-```http
+```http copy
   https://yourstore.example.com/login/token/{{TOKEN}}
 ```
 
@@ -35,7 +36,7 @@ We recommend writing a script to generate a login token since the `JWT iat` (iss
 
 ### JWT Header
 
-```json
+```json copy
   {
     "alg": "HS256",
     "typ": "JWT"
@@ -50,7 +51,7 @@ We recommend writing a script to generate a login token since the `JWT iat` (iss
 
 To create the signature, sign the encoded header, the encoded payload, and client_secret using the `HMAC SHA256` algorithm.
 
-```js
+```js copy
   HMACSHA256(
     base64UrlEncode(header) + "." +
     base64UrlEncode(payload),
@@ -63,21 +64,29 @@ To create the signature, sign the encoded header, the encoded payload, and clien
 
 Create `urlGenerator.js` node app and install dependencies.
 
-```shell
+```shell copy
   mkdir urlGenerator
+```
 
+```shell copy
   cd urlGenerator
+```
 
+```shell copy
   touch urlGenerator.js
+```
 
+```shell copy
   npm init
+```
 
+```shell copy
   npm install jsonwebtoken uuid
 ```
 
 Paste the following into `urlGenerator/urlGenerator.js`.
 
-```js
+```js copy
   const jwt = require('jsonwebtoken');
   const {v4: uuidv4} = require('uuid');
 
@@ -109,15 +118,15 @@ Paste the following into `urlGenerator/urlGenerator.js`.
 
 Replace `{{CLIENT_ID}}` and other variables with your credentials, then run the app.
 
-```shell
+```shell copy
   node urlGenerator.js
 ```
 
 You should receive a complete access point URL as an output.
 
-<!-- theme: info -->
-> #### Note
-> You are required to include the `channel_id` when using the login JWTs to redirect to an embedded checkout. Default value = 1. For more information, see the [Embedded Checkout Overview](/api-docs/storefronts/embedded-checkout/embedded-checkout-overview).
+<Callout type="info">
+  You are required to include the `channel_id` when using the login JWTs to redirect to an embedded checkout. Default value = 1. For more information, see the [Embedded Checkout Overview](/api-docs/storefronts/embedded-checkout/embedded-checkout-overview).
+</Callout>
 
 
 ## Resources

diff --git a/docs/storefront-graphql.md → docs/storefront-graphql.mdx b/docs/storefront-graphql.md → docs/storefront-graphql.mdx
@@ -19,9 +19,9 @@ To explore Storefront nodes in an interactive graph, check out the [GraphQL Expl
 
 ### Request tokens with REST API
 
-Create JWT tokens for authenticating cross-origin requests by making a `POST` request to the [Create a token](/api-reference/store-management/tokens/api-token/createtoken) endpoint.
+Create JWT tokens for authenticating cross-origin requests by making a `POST` request to the [Create a token](/docs/storefront-auth/tokens#create-a-token) endpoint.
 
-```http title="Example request: Create a token" lineNumbers
+```http filename="Example request: Create a token" showLineNumbers copy
 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token
 X-Auth-Token: {{ACCESS_TOKEN}}
 Content-Type: application/json
@@ -36,7 +36,7 @@ Accept: application/json
 }
 ```
 &nbsp;
-```json title="Example response: Create a token" lineNumbers
+```json filename="Example response: Create a token" showLineNumbers copy
 {
   "data": {
     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
@@ -47,7 +47,7 @@ Accept: application/json
 
 You can complete the GraphQL query call with any HTTP library. Use the `data.token` value from the preceding response as the `{{JWT}}` value in the `Authorization: Bearer {{JWT}}` header. 
 
-```http title="Example GraphQL query" lineNumbers
+```http filename="Example GraphQL query" showLineNumbers copy
 POST /graphql
 Authorization: Bearer {{JWT}}
 Content-Type: application/json
@@ -62,7 +62,7 @@ Content-Type: application/json
 
 Client scripts on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil)-powered storefronts can access a token with the `{{settings.storefront_api.token}}` Handlebars object.
 
-```handlebars title="Example GraphQL query script with Stencil token" lineNumbers
+```handlebars filename="Example GraphQL query script with Stencil token" showLineNumbers copy
 <script>
 // nest within any conditional, such as onload
   fetch('/graphql', {
@@ -80,9 +80,9 @@ Client scripts on BigCommerce [Stencil](/stencil-docs/getting-started/about-sten
 
 ### Customer impersonation tokens
 
-It's also possible to generate tokens for use in server-to-server interactions with a trusted consumer. Make a `POST` request to the [Create a customer impersonation token](/api-reference/store-management/tokens/customer-impersonation-token/createtokenwithcustomerimpersonation) endpoint.
+It's also possible to generate tokens for use in server-to-server interactions with a trusted consumer. Make a `POST` request to the [Create a customer impersonation token](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) endpoint.
 
-```http title="Example request: Create a customer impersonation token" lineNumbers
+```http filename="Example request: Create a customer impersonation token" showLineNumbers copy
 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation
 X-Auth-Token: {{ACCESS_TOKEN}}
 Content-Type: application/json
@@ -95,7 +95,7 @@ Accept: application/json
 
 ```
 &nbsp;
-```json title="Example response: Create a customer impersonation token" lineNumbers
+```json filename="Example response: Create a customer impersonation token" showLineNumbers copy
 {
   "data": {
     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
@@ -109,7 +109,7 @@ Accept: application/json
 
 If you're using the Storefront API from a browser (for example, on top of your Stencil storefront) you can use the Customer Login mutation to log in a customer account with an email address and password (for server-side integrations, consider a customer impersonation token instead). This will set a session cookie in the browser which will authenticate the customer account on future requests:
 
-```graphql title="Customer login mutation" lineNumbers
+```graphql filename="Customer login mutation" showLineNumbers copy
 mutation Login($email: String!, $pass: String!) {
   login(email: $email, password: $pass) {
     result