Writing docs

This site is docs-as-code: MDX files in apps/docs/content/docs, reviewed in the same pull request as the change they describe.

Run the docs locally

pnpm dev:docs

Open http://localhost:3002. Changes to MDX reload automatically.

Add a page

Pick the section that matches the reader: getting started, merchant guide, developer guide, or reference.
Create a .mdx file with frontmatter:

---
title: Create a coupon
description: Create a discount code with limits and a validity window.
---

Opening paragraph.

## Before you start

## Steps

## Verify

## Related

Add the file name to the section's meta.json pages array to control order.
Link it from at least one existing page so readers can find it.
Run pnpm -F docs check-types and pnpm -F docs build.

Choose the right content type

Type	Use it for	Shape
Tutorial	Learning a workflow end to end	Outcome, prerequisites, numbered steps, verify, next
How-to	Completing one task	Before you start, steps, verify, troubleshoot
Reference	Looking up facts	Tables, definitions, exact values
Explanation	Understanding a design	Context, diagram, trade-offs, related links

Do not mix all four into one page. If a page needs a tutorial and a reference, split it and link between them.

Style guide

Write in the second person: "Open Settings → Store".
Use exact UI labels in bold.
Put the outcome in the first sentence.
Prefer short paragraphs and scannable headings.
Use 1. numbered lists for procedures.
Add a Before you start section when prerequisites matter.
Add a Verify section when the user needs to confirm success.
Add a Related section with 2–4 links.
Use DZD and Algerian examples where relevant.
Define jargon on first use, or link to the glossary.
Do not document features marked "coming soon" as if they exist.
Do not include secrets, real API keys, or production database URLs.

Links and assets

Use absolute site paths: /docs/merchant-guide/orders.
Use descriptive link text, not "click here".
Prefer text over screenshots. When you add a screenshot, annotate the relevant control and write meaningful alt text.
Keep screenshots in a stable location and update them when the UI changes.

API reference pages

Do not edit files in content/docs/api-reference that carry a generated comment. Refresh them from the admin spec:

# Start the admin app first
pnpm docs:sync-api

The command fetches /api/openapi.json, tags operations by module, rewrites the public server URL, and regenerates the operation pages. Review the diff before committing.

Review checklist

Title and description are accurate.
The page matches the current code and UI labels.
Prerequisites and permissions are stated.
Commands work from the repository root.
Links resolve and point to existing pages.
No placeholder text or "coming soon" claims.
No secrets or production data.
pnpm -F docs build passes.
Docs were updated in the same PR as the behavior change.

On this page