Adding and editing docs

This site is Astro Starlight. Content is plain Markdown in src/content/docs/.

Run it locally

npm run dev

The dev server prints a local URL and hot-reloads as you edit. npm run build produces the static site in dist/, and also fails on broken internal links, so run it before shipping.

Add a page

Start from templates/article.md — it is the standard article skeleton, and Article format explains each section and when to drop one. Copy it into the relevant section directory. The sidebar is autogenerated per directory, so a new file appears in the nav with no config change.

---
title: Restocking fees
description: One sentence that shows up in search results and link cards.
sidebar:
  order: 3
---

Body starts here. Do not repeat the title as an `# H1` — Starlight renders the
frontmatter `title` for you, so start at `##`.

sidebar.order controls position within the section. Pages without it sort alphabetically after the ordered ones.

Sections

Directory	Holds
getting-started/	Orientation, article format, authoring conventions.
policies/	Return policies, reasons, fees, warranty coverage.
outcomes/	Refunds, credit, exchanges, Shop Now, Keep Item.
workflows.mdx	Workflows — a single page, not a section.
shipping/	Destinations, labels, carriers, replacement shipments.
portal/	Customisation, custom domains, translations, blocking.
portal-flows/	Shopper-facing behaviour reference.
analytics/	Reporting and dashboards.
integrations/	Shopify, Amazon, and other connected systems.
best-practices/	Opinionated guidance on policy, retention, automation.
developer/	API, webhooks, events, MCP.

Adding a new top-level section means creating the directory and adding one line to the sidebar array in astro.config.mjs. An empty directory will fail the build, so add the first page at the same time.

Diagrams

Fenced mermaid blocks render as diagrams and follow the site’s light/dark theme:

```mermaid
flowchart TD
    A[Shopper opens portal] --> B{Eligible?}
    B -- Yes --> C[Choose outcome]
    B -- No --> D[Item unavailable]
```

Keep them for genuine branching logic. For linear instructions, a numbered list reads better.

Components

Starlight ships callouts, tabs, cards, and steps. Import them in .mdx files:

import { Aside, Tabs, TabItem, Steps } from '@astrojs/starlight/components';

In plain .md, use the callout shorthand instead:

:::caution
Changing a return window applies to new requests only.
:::

Conventions

• Write for a store team member who has not used the product before.
• Say what the setting does, then what the shopper sees as a result.
• Prefer short steps over long prose; the portal’s options change with policy and workflow configuration, so absolute statements age badly.
• Link to a single canonical page for each concept rather than restating it.
• Write internal links without a trailing slash: /refunds, not /refunds/.

The full article standard, including target length and heading rules, is in Article format.