Adobe Commerce Storefront documentation

Welcome to the storefront documentation site! This site is built with Astro and Starlight. To contribute documentation, follow the instructions below to install the prerequisites, configure your local environment, create new pages, and submit PRs.

• Prerequisites
• Set up your local environment
• Development commands
• Content structure
• How to add a page
• How to add images
• How to add a diagram
• How to link between docs
• How to add a PR
• How to add release notes

Prerequisites

Install node and pnpm:

• Node.js 20.13.1 or later.
• Pnpm 9.x or later. See the pnpm installation instructions.

Set up your local environment

1. Clone the repository and install dependencies:

   git clone git@github.com:commerce-docs/microsite-commerce-storefront.git
   cd microsite-commerce-storefront
   pnpm install

2. Run the docs site locally:

   pnpm dev

   This starts the development server, builds the site, and opens a browser at http://localhost:4321/. The site auto-reloads when you save changes.

Development commands

• pnpm dev — Start the local dev server. The site auto-reloads when you save.
• pnpm build:prod-fast — Run a test production build before opening a PR.
• pnpm clean — Reinstall dependencies (removes node_modules, dist, .astro).
• pnpm scrub — Nuclear option: same as clean but also removes pnpm-lock.yaml.

Content structure

Docs live in src/content/docs/. Use dropins/ for B2C (cart, checkout, wishlist), dropins-b2b/ for B2B (requisition list, quote management). Folder structure maps to the sidebar, mostly.

How to add a page

• Docs pages are .mdx files in src/content/docs/<section>/ (e.g. dropins/cart, dropins-b2b/requisition-list).
• Add frontmatter: title, description, and a sidebar entry so the page appears in the nav.
• Use sidebar.label and sidebar.order to control placement within the navigation sidebar on the left of a page.

---
title: Page Title
description: Brief description for SEO and social sharing.
sidebar:
  label: Sidebar Label
  order: 4
---

import Aside from '@components/Aside.astro';

Your content here. Use components like:

<Aside type="tip" title="Pro Tip">
  Helpful information for the reader.
</Aside>

How to add images

• Shared images: Put files in public/images/ (optionally in subfolders like dropins/cart/). Reference with ![Alt text](@images/path/to/image.png).
• Colocated images: Put an images/ folder next to your docs (e.g. src/content/docs/how-tos/images/). Reference with ![Alt text](images/filename.png) from pages in that section.
• For images inside a diagram with a caption, wrap in the Diagram component, below.

How to add a diagram

Import the Diagram component and wrap images or Mermaid code:

import Diagram from '@components/Diagram.astro';

<Diagram caption="Optional caption for the image.">![Alt text](@images/path/to/image.png)</Diagram>

<Diagram type="mermaid" code={`graph LR; A --> B`} />

Use caption for images; use type="mermaid" and code for flowcharts and sequence diagrams. Example pages of each:

• Images src/content/docs/dropins/all/slots.mdx
• Mermaid src/content/docs/setup/configuration/aem-prerender.mdx

How to link between docs

Links outside the storefront site must use the Link component. Internal links use standard markdown.

• Internal links (within the storefront docs): Use standard markdown with a path starting with /. For example, [SEO metadata](/setup/seo/metadata/).
• External links (outside the storefront site): Use the Link component so they open in a new tab with proper styling:

import Link from '@components/Link.astro';

See the <Link href="https://example.com/docs" text="external documentation" /> for details.

How to add a PR

If you don't have write access to the repo, fork the repository first. Clone your fork instead of the repo, push to your fork, then open a PR from your fork to develop.

1. Create a new branch for your changes, based on develop:

   git checkout develop
   git pull origin develop
   git checkout -b your-branch-name

2. Make your changes to the docs (edit or add .mdx files in src/content/docs/).

3. Run pnpm build:prod-fast to verify your changes build, then commit, push, and open a PR against develop. The develop branch is the main branch used for publishing the site.

4. After your PR is merged into develop, content is published to the Commerce Storefront site by the nightly build.

How to add release notes

1. Run gh auth login (required for Cursor to access private repos).

2. In Cursor, prompt the agent with the release month and PR merge links. Example:

   Add the [Month] 2026 release. Use the release merge PRs to generate the release notes and all the code changes: B2C: hlxsites/aem-boilerplate-commerce#1152 B2B: hlxsites/aem-boilerplate-commerce#1156

See the release-notes skill for full details.