DCAT-2416 Refactor navigation and editorial updates

.github/linters/metadata.schema.yml

@@ -19,15 +19,19 @@ properties:
         - Cloud
         - Configuration
         - Cron
+        - Data Import
+        - Data Export
         - Events
         - Extensibility
         - Extensions
         - GraphQL
         - Integration
         - Inventory
+        - Merchandising
         - Payments
         - Performance
         - Personalization
+        - Product discovery
         - Recommendations
         - Reporting
         - REST
@@ -37,7 +41,8 @@ properties:
         - Storefront
         - Tools
         - Upgrade
+        - Troubleshooting
 
 required:
   - title
-  - description
+  - description

.github/workflows/stage.yml

@@ -7,6 +7,7 @@
         - ccdm-early-access
   jobs:
     set-state:
+      if: ${{ github.ref == 'refs/heads/ccdm-early-access' }}
       runs-on: ubuntu-latest
       outputs:
         clean_cache: ${{ contains(github.event.inputs.clean, 'yes') }}

.gitignore

@@ -47,4 +47,4 @@ tmp/
 yalc.lock
 
 # other
-tmp/*
+tmp/*

.remarkrc.yaml

@@ -0,0 +1,8 @@
+plugins:
+  - remark-heading-id
+  - remark-validate-links
+  - remark-frontmatter
+  - - remark-lint-frontmatter-schema
+    - schemas:
+        './.github/linters/metadata.schema.yml':
+          - './src/pages/**/*.md'

.remarkrc.yml

@@ -0,0 +1,8 @@
+plugins:
+  - remark-heading-id
+  - remark-validate-links
+  - remark-frontmatter
+  - - remark-lint-frontmatter-schema
+    - schemas:
+        './.github/linters/metadata.schema.yml':
+          - './src/pages/**/*.md'

README.md

@@ -21,7 +21,27 @@ To build the site locally:
    yarn dev
    ```
 
-**Tip:** If you encounter unexpected failures or delays, try to clean up the gatsby and yarn caches with the command: `yarn clean && yarn cache clean` for troubleshooting.
+## Components
+
+To achieve specific user experience goals for Commerce documentation, this repo overrides the original [`Edition`](https://github.com/adobe/aio-theme/blob/main/packages/gatsby-theme-aio/src/components/Edition/index.js) component from the upstream [`aio-theme`](https://github.com/adobe/aio-theme/) repo that we use as a dependency.
+
+### Edition
+
+The custom `Edition` component in this repo displays a badge indicating whether a feature or functionality is available in specific Adobe Commerce environments. It has been customized to align with the badges that we use in Experience League docs.
+
+#### Usage
+
+```yaml
+# Page-level (metadata)
+edition: saas # For SaaS-only features
+edition: paas # For PaaS-only features
+```
+
+```md
+<!-- Section-level (inline) -->
+<Edition name="paas" />  <!-- For PaaS-only features -->
+<Edition name="saas" />  <!-- For SaaS-only features -->
+```
 
 ## Resources
 

gatsby-browser.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import React from 'react';
+import { MDXProvider } from '@mdx-js/react';
+import { Edition } from './src/@adobe/gatsby-theme-aio/components/Edition';
+
+// Define the components that will be available in MDX files
+const components = {
+  // Register the Edition component for inline use
+  Edition
+};
+
+// Wrap the root element with the MDXProvider
+export const wrapRootElement = ({ element }) => {
+  return <MDXProvider components={components}>{element}</MDXProvider>;
+};
+
+const isBrowser = typeof window !== "undefined";
+
+export const onClientEntry = () => {
+  // set adobe analytics window object
+  if (isBrowser) {
+    window._satellite = window._satellite || {};
+    window.alloy_all = window.alloy_all || {};
+    window.alloy_all.data = window.alloy_all.data || {};
+    window.alloy_all.data._adobe_corpnew = window.alloy_all.data._adobe_corpnew || {};
+    window.alloy_all.data._adobe_corpnew.web = window.alloy_all.data._adobe_corpnew.web || {};
+    window.alloy_all.data._adobe_corpnew.web.webPageDetails = window.alloy_all.data._adobe_corpnew.web.webPageDetails || {};
+  }
+};
+
+export const onRouteUpdate = ({ location, prevLocation }) => {
+  if (isBrowser) {
+    function watchAndFireAnalytics() {
+      // eslint-disable-next-line no-undef
+      if (typeof window._satellite !== 'undefined' && typeof window._satellite.track === 'function') {
+        // eslint-disable-next-line no-undef
+        _satellite.track('state',
+          {
+            xdm: {},
+            data: {
+              _adobe_corpnew: {
+                web: {
+                  webPageDetails: {
+                    customPageName: location.href
+                  }
+                }
+              }
+            }
+          }
+        );
+
+        clearInterval(intervalId);
+      }
+    }
+
+    // watch if analytics is online then track page
+    const intervalId = setInterval(watchAndFireAnalytics, 1000);
+  }
+}

gatsby-ssr.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 Adobe. All rights reserved.
+ * Copyright 2020 Adobe. All rights reserved.
  * This file is licensed to you under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License. You may obtain a copy
  * of the License at http://www.apache.org/licenses/LICENSE-2.0
@@ -11,10 +11,16 @@
  */
 
 import React from 'react';
-import {withPrefix} from 'gatsby';
+import { MDXProvider } from '@mdx-js/react';
+import { Edition } from './src/@adobe/gatsby-theme-aio/components/Edition';
 
-export const onRenderBody = ({setHeadComponents}) => {
-  setHeadComponents([
-    <script src={withPrefix('/redirections.js')}></script>
-  ]);
-};
+// Define the components that will be available in MDX files
+const components = {
+  // Register the Edition component for inline use
+  Edition
+};
+
+// Wrap the root element with the MDXProvider
+export const wrapRootElement = ({ element }) => {
+  return <MDXProvider components={components}>{element}</MDXProvider>;
+};

package.json

@@ -7,18 +7,17 @@
     "url": "https://github.com/AdobeDocs/commerce-services"
   },
   "dependencies": {
-    "@adobe/gatsby-theme-aio": "4.14.19",
+    "@adobe/gatsby-theme-aio": "4.15.1",
     "gatsby": "4.22.0",
     "react": "^17.0.0",
-    "react-dom": "^17.0.0",
-    "spectaql": "^3.0.2"
+    "react-dom": "^17.0.0"
   },
   "devDependencies": {
+    "browserslist": "latest",
     "remark-cli": "^12.0.1",
     "remark-frontmatter": "^5.0.0",
     "remark-heading-id": "^1.0.1",
     "remark-lint-frontmatter-schema": "^3.15.4",
-    "remark-lint-no-dead-urls": "^1.1.0",
     "remark-validate-links": "^13.0.1"
   },
   "scripts": {
@@ -29,12 +28,13 @@
     "build": "NODE_OPTIONS='--max-old-space-size=8192' gatsby build",
     "serve": "NODE_OPTIONS='--max-old-space-size=8192' gatsby serve",
     "clean": "gatsby clean",
-    "test": "remark src/pages --quiet --frail",
+    "test": "remark src/pages --frail",
     "build:admin-api": "spectaql --target-file index.html --config spectaql/config-admin.yml",
-    "dev:admin-api": "spectaql --development-mode-live --config spectaql/config-admin.yml",
+    "dev:admin-api": "spectaql --target-file index.html --config spectaql/config-admin.yml --development-mode",
     "build:storefront-api": "spectaql --target-file index.html --config spectaql/config-storefront.yml",
-    "dev:storefront-api": "spectaql --development-mode-live --config spectaql/config-storefront.yml",
-    "build:graphql": "yarn run build:admin-api && yarn run build:storefront-api"
+    "dev:storefront-api": "spectaql --target-file index.html --config spectaql/config-storefront.yml --development-mode",
+    "build:graphql": "yarn build:admin-api && yarn build:storefront-api",
+    "lint": "docker run --rm -e RUN_LOCAL=true --env-file .github/super-linter.env -v \"$PWD\":/tmp/lint github/super-linter:slim-v5"
   },
   "packageManager": "yarn@3.2.4"
 }

spectaql/config-storefront.yml

@@ -422,12 +422,12 @@ info:
   ##############################################
 
   description: |
-     Use the storefront GraphQL API to access rich view-model (read-only) catalog data to build product-related storefront experiences.
-     For more information about the API, see the <a href="https://developer-stage.adobe.com/commerce/services/composable-catalog/storefront-services/" target="_blank">developer documentation</a>.
-  title: Storefront API
+     Use the Merchandising GraphQL API to access rich view-model (read-only) catalog data to build product-related storefront experiences.
+     For more information about the API, see the <a href="https://developer-stage.adobe.com/commerce/services/composable-catalog/storefront-services/api-reference/" target="_blank">developer documentation</a>.
+  title: Merchandising GraphQL API
   # This is non-standard and optional. If omitted, will use "title". Also, only relevant
   # when building non-embedded.
-  x-htmlTitle: Storefront API
+  x-htmlTitle: Merchandising GraphQL API
   # termsOfService: 'https://yoursite.com/terms'
   # contact:
   #   name: YourSite Support

spectaql/metadata-storefront.json

@@ -1,5 +1,13 @@
 {
+    "INTERFACE": {
+        "CategoryViewInterface": {
+            "documentation": { "undocumented": true }
+        }
+    },
     "OBJECT": {
+        "CategoryView": {
+            "documentation": { "undocumented": true }
+        },
         "Query": {
             "fields": {
                 "categories": {

src/@adobe/gatsby-theme-aio/components/Edition/index.js

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import React from 'react';
+import PropTypes from 'prop-types';
+import '@spectrum-css/badge';
+import '@spectrum-css/link';
+import '@spectrum-css/tooltip';
+
+let editionText = '';
+let editionColor = '';
+let editionTooltip = '';
+const EDITIONS_LINK = 'https://experienceleague.adobe.com/en/docs/commerce/user-guides/product-solutions';
+
+const Edition = ({ ...props }) => {
+  switch (props.name) {
+    case 'paas':
+      editionText = 'PaaS only';
+      editionColor = 'spectrum-Badge--informative';
+      editionTooltip = 'Applies to Adobe Commerce on Cloud (Adobe-managed PaaS infrastructure) and on-premises projects only.';
+      break;
+    case 'saas':
+      editionText = 'SaaS only';
+      editionColor = 'spectrum-Badge--positive';
+      editionTooltip = 'Applies to Adobe Commerce as a Cloud Service and Adobe Commerce Optimizer projects (Adobe-managed SaaS infrastructure).';
+      break;
+    default:
+      editionText = 'Create an Edition tag';
+      editionColor = 'spectrum-Badge--yellow';
+      editionTooltip = '';
+  }
+
+  return (
+    <a
+      href={EDITIONS_LINK}
+      className="spectrum-Link"
+      target="_blank"
+      rel="noreferrer"
+      style={{
+        textDecoration: 'none',
+        display: 'inline-block',
+        marginTop: '1rem',
+        marginRight: '0.5rem',
+        position: 'relative'
+      }}
+      title={editionTooltip}
+    >
+      <span
+        className={`spectrum-Badge spectrum-Badge--sizeS ${editionColor}`} 
+        style={{ paddingBottom: '4px', cursor: 'pointer' }}
+      >
+        {editionText}
+      </span>
+    </a>
+  );
+};
+
+Edition.propTypes = {
+  name: PropTypes.string
+};
+
+export { Edition };

src/_includes/authentication/get-new-bearer-token.md

@@ -15,4 +15,8 @@ Replace the following placeholders with your credentials:
 - `<client_id>`: The client ID generated for your Adobe developer project
 - `<client_secret>`: The client secret generated for your Adobe developer project
 
-You can get these credentials from the Adobe Developer Console project details page. If you don't have access to the developer console, contact your system administrator to get the credentials.
+You can get these credentials from the Adobe Developer Console project details page. If you don't have access to the developer console, contact your system administrator for assistance.
+
+<InlineAlert variant="info" slots="text" />
+
+For information on managing, refreshing, and revoking bearer tokens, see the [User Authentication Implementation Guide](https://developer.adobe.com/developer-console/docs/guides/authentication/UserAuthentication/) in the *Adobe Developer Console documentation*.