Adobe Commerce Storefront documentation

Welcome to the storefront documentation site! To contribute documentation to this site follow the instructions below to install the prerequisites, configure your local environment, create new pages, submit PRs.

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 GitHub repository:

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

2. Navigate to the root of your local repository:

   cd microsite-commerce-storefront

3. Install the dependencies using pnpm:

   pnpm install

4. Run the docs site

   pnpm dev

   The site should open a broswer window at http://localhost:4321/.

Available scripts

The available scripts for running the project are defined in the package.json file:

• build:prod: Builds the production site with the /developer/commerce/storefront base path.

• preview:prod: Previews the production site.

• build: Builds a static, optimized development site without the production base path.

• preview: Previews the static development site.

• dev: Starts the development server and auto-opens the site in the browser.

• lint: Runs prettier formatting on all the project files.

• clean: Removes the dist, .astro, and node_modules directories and reinstalls the dependencies.

• scrub: Does the same as clean but also removes the pnpm-lock.yaml file and the ~./.pnpm-store directory.

Development commands

• pnpm dev to start the local dev server and preview your changes during development. Site auto-reloads when you save changes.
• pnpm lint to batch format all your files with the prettier module.
• pnpm clean to resolve dependency issues by deleting the node_modules and dist directories, then reinstalling dependencies.
• pnpm scrub to remove everything and reinstall dependencies. The nuclear option.

How to contribute PRs

1. Fork the repository.
2. Create a new branch for your changes.
3. Make your changes.
4. Push your changes to your fork.
5. Create a pull request to the develop branch of the commerce-docs/microsite-commerce-storefront repository.
6. Wait for the PR to be reviewed and merged.

How to create a new docs page

1. Create a new .mdx file in the src/content/docs/<docs-directory>.

2. Add the frontmatter to the top of the file. The frontmatter should include the title of the page and the description. The title will render as an <h1> on the page. The description will be used for SEO and social sharing. For example:

   ---
   title: Slots
   description: Learn about slots and how to use them to customize drop-in components.
   sidebar:
     label: Awesome Slots!   // Overrides the title in the sidebar
     order: 4                // Use order for auto-generated sidebar links. See src/content/docs/customize files for example.
   ---

3. Write the content of the page using the markdow/MDX syntax.

4. Add imports for any Astro components you want to use below the frontmatter fence. For example:

   ---
   title: Slots
   description: Learn about slots and how to use them to customize drop-in components.
   sidebar:
   label: Slots
   order: 4
   ---
   
   import Diagram from '@components/Diagram.astro';
   import Vocabulary from '@components/Vocabulary.astro';
   import Aside from '@components/Aside.astro';
   import Callouts from '@components/Callouts.astro';

How to create and use content fragments

Content fragments allow you to write reusable content once and include it across multiple pages. This is perfect for maintaining consistency and reducing duplication.

Step 1: Create a content fragment

1. Create a new .mdx file in the src/content/fragments/ directory
2. Add any imports you need (like Starlight components)
3. Write your reusable content using standard MDX/Markdown syntax

Example fragment file (src/content/fragments/my-note.mdx):

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip" title="Pro Tip">
This content will appear exactly the same on every page where it's imported.
You can use **markdown formatting**, lists, and Starlight components.
</Aside>

Step 2: Use the fragment in your pages

Import and use the fragment in any MDX page:

---
title: My Documentation Page
description: Example page using a content fragment
---

import MyNote from 'src/content/fragments/my-note.mdx';

# Page Title

Regular page content before the fragment...

<MyNote />

More content after the fragment...

The name MyNote is an example name/variable specific to the page to which you are importing the fragment. You can use any name you want. For example, AcoVersionNote.

Best Practices

• Naming: Use descriptive names like prerequisites.mdx or api-warning.mdx
• Organization: Keep fragments in src/content/fragments/ for easy discovery
• Import paths: Use the same path src/content/fragments/<your-file.mdx> so you don't have to worry about deciphering relative paths from your file's location in the project.
• Content scope: Use fragments for content that appears on multiple pages (obviously).
• Updates: Edit the fragment file once to update all instances.

Common Use Cases

• Prerequisites and requirements
• Warning messages and cautions
• Legal disclaimers
• Contact information
• Version compatibility notes
• Troubleshooting tips