docsReferenceStyle Conventions

SOP Style Conventions (shared)

These conventions apply to every guide in this docs app, for both audiences. The audience-specific creation guides build on top of this file.

⚠️ Important — Re-pathed for the monorepo 2026-08-18, then again for the apex split 2026-08-19: the docs now live inside apps/web (the productsync.io app — Nextra merged in, served natively at productsync.io/docs, no basePath). Admin SOPs are a separate system inside apps/admin (session-gated /admin/docs) — they never live here.

Folder layout

  • Dealer guides: apps/web/src/pages/docs/dealers/
  • WordPress plugin guides: apps/web/src/pages/docs/wordpress-plugin/
  • Images: apps/web/public/images/<doc-slug>/ (one folder per guide, named after the guide’s filename without .md)
  • This file and the two creation guides live in apps/web/src/pages/docs/reference/.

File naming

  • Kebab-case, audience-prefixed: admin-<topic>.md, dealer-<topic>.md.
  • The full filename (minus .md) is reused as the image-subfolder name, e.g. dealer-embed-code-setup.md → public/images/dealer-embed-code-setup/.

Document anatomy (every guide)

  1. Title (# ...)
  2. Metadata block (audience, owner, last updated, related SOPs)
  3. Purpose / “What this is”
  4. The procedure (numbered steps)
  5. Troubleshooting / what-if
  6. Completion checklist (- [ ])

Metadata block format

Place this immediately under the title:

**Audience:** Dealer | Admin
**Owner:** <team or role responsible>
**Last updated:** YYYY-MM-DD
**Related SOPs:** [link](./other-sop.md)

Callouts

Blockquote + emoji + bold label: 💡 Tip, 🤔 Not sure?, 📋 Hand-off, ✅ Done when, ⚠️ Important, 🛡️ Don’t worry, 📸 Screenshot needed.

Images

  • Path form: /images/<doc-slug>/<file>.png — files live in apps/web/public/images/<doc-slug>/, and since the apex split there is no basePath, so this is also the served URL. Never write /docs/images/... (it breaks the build).
  • Descriptive alt text, italic caption with a figure number directly beneath the image.
  • Every not-yet-captured image gets the three-line placeholder pattern:
    1. _(screenshot pending: <what it shows>)_
    2. *Figure N — <caption>.*
    3. A > 📸 **Screenshot needed** — \NN-.png“ callout with the exact capture spec (route, UI state, what to include/crop, demo-data note).
  • Filenames are zero-padded and sequential per guide (01-, 02-, …). Figure numbers are sequential per guide.
  • Screenshots are captured with the runner in tools/screenshots/ (per-guide spec files in tools/screenshots/src/specs/), so they can be regenerated when the UI changes.

ClickUp exports

Not migrated to the monorepo. The old monolith generated ClickUp-ready copies of each SOP; that workflow is parked. If it returns, exports will live alongside the guides — do not create sops/ paths.

Index

Every new guide is added to apps/web/src/pages/docs/index.mdx (the hand-maintained link hub) and, if it starts a new top-level section, to apps/web/src/pages/docs/_meta.js.

Dealer Sop Creation Guide