ReferenceStyle 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 — This file was re-pathed for the monorepo on 2026-08-18. The old monolith sops/ tree no longer exists; content lives in apps/docs (Nextra, served at productsync.io/docs).

Folder layout

  • Dealer guides: apps/docs/pages/dealers/
  • WordPress plugin guides: apps/docs/pages/wordpress-plugin/
  • Admin guides: apps/docs/pages/admin/ (section not yet created — added when the first admin guide lands)
  • Images: apps/docs/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/docs/pages/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: /docs/images/<doc-slug>/<file>.png (the app is served under basePath /docs; static files in public/ are served with that prefix).
  • 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/docs/pages/index.mdx (the hand-maintained link hub) and, if it starts a new top-level section, to apps/docs/pages/_meta.js.

Dealer Sop Creation Guide