Skip to main content

Trophy Docs

Mintlify documentation site for Trophy. Repo-root paths are the canonical English source; es/** is generated by the translation workflow. See README.md for Lingo and MCP setup (Cursor-specific steps there).

Dev server

  • Never open a browser when starting the dev server. Use npm run dev (already passes --no-open) or, if invoking Mintlify directly, always pass --no-open (for example mint dev --no-open).

Writing style

  • Never abbreviate “leaderboard” to “board” in docs copy, comments or commit messages. Always write “leaderboard”.

Localization Workflow

  • Treat repo-root docs paths as the canonical English source and keep identical relative file paths/filenames across all locales.
  • For planned doc changes, default scope to English source files only. Do not plan or execute manual edits to non-English locale content (for example es/**) unless the user explicitly asks for localized updates; rely on the existing translation workflow to propagate English changes.
  • Keep all locale navigation in docs.json under navigation.languages; do not reintroduce navigation.global or top-level navbar.
  • Keep SEO metatags in English unless explicitly requested otherwise.
  • Do not translate code snippets, inline code, URLs, route slugs, or API identifiers.
  • Shared media lives under repo-root assets/. Default-language pages are at repo-root section paths (for example <section>/<page>.mdx) and targets are under locale directories (for example es/<section>/<page>.mdx), so relative src paths need one more ../ under each locale segment than in English. scripts/localize-internal-links.mjs rewrites markdown ](/...) and JSX href="/..." only (absolute navigation paths). Relative repo-root assets/ src and MDX import paths are normalized by scripts/localize-mdx-paths.mjs after Lingo.
  • scripts/localize-mdx-paths.mjs rewrites: <locale>/components/*.jsx for the active locale; from ".../snippets/..."; and JSX src=".../assets/..." so ../ depth matches the file’s path. Run after Lingo in translate:generate and translate-on-main; CI checks via translate:localize-mdx-paths:check.
  • Shared MDX snippets live under repo-root snippets/ (not per-locale). Import with relative paths from each page; do not add shared MDX snippets to Lingo i18n.json buckets unless you intend to translate them.
  • Locale-aware React components that can contain text live under components/*.jsx for default language and <locale>/components/*.jsx for targets, and are manually maintained per locale (do not add them to Lingo i18n.json buckets; do not keep these in shared snippets/).
  • Endpoint and webhook MDX must pin a repo-local OpenAPI file in frontmatter (do not put remote OpenAPI URLs in frontmatter, and do not set tab/group-level openapi in docs.json navigation—tab openapi auto-populates endpoints and duplicates MDX nav entries; remote URLs in frontmatter are not reliably resolved by Mintlify). Specs live under openapi/application.json (Application API + webhooks) and openapi/admin.json (Admin API), also listed under api.openapi in docs.json. Forms: openapi: "/openapi/application.json GET /path", openapi: "/openapi/application.json webhook <eventKey>", openapi: "/openapi/admin.json METHOD /path". Keep those lines identical across locales; Lingo must not alter them.
  • English nav titles for those pages come from OpenAPI summary via scripts/sync-openapi-titles.mjs (npm run translate:sync-openapi-titles). It runs at the start of translate:generate and on the translate-on-main workflow. Lingo translates the title field for target locales; the script only fills a missing target title with English (bootstrap)—it does not overwrite existing translations.
  • Mintlify custom heading IDs use markdown ## Title {#slug} (see Mintlify docs). Slugs are aligned from English source root files via scripts/sync-heading-anchors.mjs. Never translate or alter {#…}; sync runs after Lingo in PIT/CI. Do not merge heading-count drift between source root and target locales without fixing structure first.
  • For Mintlify <Accordion> components that may be deep-linked, always set explicit id values (do not rely on title-derived hashes) and keep those ids identical across locales.
  • Do not use fragile OpenAPI parameter hash links like #parameter-* in docs links; link to the endpoint page and reference parameter names inline in prose/code.
  • Treat lingo/brand-voice.md as the source of truth for brand voice (tone and style) only. Do not add structural or tooling rules there (for example Mintlify {#slug} handling); those stay in this rule, README, and optionally in the Lingo engine Instructions field—not brand voice.
  • Do not add script-based brand voice sync; sync brand voice on demand via Lingo MCP tools from chat.
  • Treat lingo/glossary.csv as the glossary source of truth; use MCP sync with canonical key sourceLocale|targetLocale|type|sourceText.
  • For glossary sync, always do dry-run first, show create/update/delete counts, then apply on confirmation.
  • When adding locales, update both docs.json language blocks and i18n.json locale.targets.