Services for Adobe Commerce Documentation

Welcome! This site contains the latest Services for Adobe Commerce developer documentation for ongoing releases.

Local development

This is a Gatsby project that uses the Adobe I/O Theme.

To build the site locally:

1. Clone this repo.

2. Install project dependencies.

   yarn install

3. Launch the project in development mode.

   yarn dev

Components

To achieve specific user experience goals for Commerce documentation, this repo overrides the original Edition component from the upstream 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

# Page-level (metadata)
edition: saas # For SaaS-only features
edition: paas # For PaaS-only features

<!-- Section-level (inline) -->
<Edition name="paas" />  <!-- For PaaS-only features -->
<Edition name="saas" />  <!-- For SaaS-only features -->

Resources

See the following resources to learn more about using the theme:

• Arranging content structure
• Linking to pages
• Using assets
• Configuring global navigation
• Configuring side navigation
• Using content blocks
• Writing enhanced Markdown
• Deploying the site (Adobe employees only)

If you have questions, open an issue and ask us. We look forward to hearing from you!

GraphQL API reference generator

The Merchandising GraphQL API reference is generated using SpectaQL. It uses live introspection against the GraphQL endpoint and a metadata overlay to filter the schema down to the documented queries and types.

Quick start

1. Create a .env file in the project root:

   cp .env.example .env

2. Build the API reference:

   yarn build:merchandising-api

The generated output is written to static/graphql-api/merchandising-api/index.html and embedded in the documentation site using the Adobe I/O theme's frameSrc feature. After rebuilding, verify the output in your browser before committing changes.

To generate a live preview during local development, run: yarn dev:merchandising-api.

Prerequisites

• Node.js matching the version in .nvmrc
• Yarn

Update the API reference

If the schema or metadata descriptions change, rebuild and test the API reference locally:

1. Create a branch from main.

2. Regenerate the API reference using the enhanced build (includes custom descriptions):

   node scripts/build-with-enhanced-schema.js

3. Verify the output in your browser.

4. Commit the updated index.html and enhanced-schema.json files.

5. After updates are approved, a documentation team member merges the PR and publishes the updates to the developer site.

See spectaql/README.md for detailed configuration, build commands, offline builds, and script documentation.

REST API Reference Generator

See Generate the Data Ingestion API Reference.