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 examplemint 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.jsonundernavigation.languages; do not reintroducenavigation.globalor top-levelnavbar. - 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 examplees/<section>/<page>.mdx), so relativesrcpaths need one more../under each locale segment than in English.scripts/localize-internal-links.mjsrewrites markdown](/...)and JSXhref="/..."only (absolute navigation paths). Relative repo-rootassets/srcand MDXimportpaths are normalized byscripts/localize-mdx-paths.mjsafter Lingo. scripts/localize-mdx-paths.mjsrewrites:<locale>/components/*.jsxfor the active locale;from ".../snippets/..."; and JSXsrc=".../assets/..."so../depth matches the file’s path. Run after Lingo intranslate:generateand translate-on-main; CI checks viatranslate: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 Lingoi18n.jsonbuckets unless you intend to translate them. - Locale-aware React components that can contain text live under
components/*.jsxfor default language and<locale>/components/*.jsxfor targets, and are manually maintained per locale (do not add them to Lingoi18n.jsonbuckets; do not keep these in sharedsnippets/). - 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
openapiindocs.jsonnavigation—tabopenapiauto-populates endpoints and duplicates MDX nav entries; remote URLs in frontmatter are not reliably resolved by Mintlify). Specs live underopenapi/application.json(Application API + webhooks) andopenapi/admin.json(Admin API), also listed underapi.openapiindocs.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
summaryviascripts/sync-openapi-titles.mjs(npm run translate:sync-openapi-titles). It runs at the start oftranslate:generateand on the translate-on-main workflow. Lingo translates thetitlefield for target locales; the script only fills a missing targettitlewith 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 viascripts/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 explicitidvalues (do not rely on title-derived hashes) and keep thoseids 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.mdas 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.csvas the glossary source of truth; use MCP sync with canonical keysourceLocale|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.jsonlanguage blocks andi18n.jsonlocale.targets.