improvement(docs): make the API reference read as code and unify its type token - #6653
Conversation
… type token The API-page font override matched every span/div/p inside the page, which outranks the .font-mono class on specificity, so every parameter name, type, and identifier silently rendered in the body sans face. Exclude .font-mono so code tokens stay monospace. Consolidate the three divergent type-slot treatments — plain scalar, union, and schema reference each carried their own chip definition, differing in size, weight, face, and box height — onto one code token that reuses the docs inline-code recipe and the platform's 20px chip height. Demote the row metadata: 'required' and 'header' were filled pills, 'required' on the error token, making a constraint the loudest element on the page and a page of required parameters read as a page of alarms. Both are now uncontained text, leaving the type token as the only box on the row. Pin the two 'application/json' labels to one treatment; the Request Body and Response headers rendered the same string at different weights and faces.
…icons to emcn Status codes in the example panel are numeric literals and render as code everywhere else on the page, including the Response header's own trigger, but fumadocs rendered the strip in the body sans face. Language tabs sit in a separate container and stay sans — those are product names, not code. fumadocs draws a few lucide glyphs on API pages that its client-component overrides do not expose (the heading anchor and the code-block copy button). emcn strokes at 1.55 and lucide at 2, so those icons read heavier than every icon around them; match the weight.
…d wrap example code The auth row collapses its real `<token>` type and renders the chip through ::after, so the span is only a wrapper — but it still matched the type-token rule and kept that rule's border, height, and gap. The border drew a second empty box around the real chip and the gap opened in front of it, because the collapsed text remains an anonymous flex item; together they pushed the chip right by roughly 8px that no other row had. Example-panel code overflowed sideways instead of wrapping: fumadocs sizes the block with `w-max`, so it grew to its longest line inside a 400px scroller and the existing pre-wrap never applied. Cap the width, switch break-all to overflow-wrap anywhere so only unfittable tokens split, and reserve room for the copy button fumadocs floats over the first line.
Wrapping restarts every continuation line at column zero, and in a JSON body indentation is what carries nesting depth — so a wrapped response misreports its own structure. A hanging indent keeps the depth but needs the shiki lines forced from flex rows to blocks, which breaks the line rhythm. Removes the pre-wrap rules rather than repointing them: fumadocs sizes the block with w-max, so the previous rule never took effect and overflow was already the behaviour on the page.
…ible An `array<T>` slot holds its angle brackets as bare text nodes, which become anonymous flex items, so the slot's gap prised `array<` and `>` away from the type they wrap. Drop the gap and let the union separator carry its own margin; this also makes the auth row's gap override redundant. The separator was dimmed twice, by a muted token and again by opacity, which on the dark chip fill left `string | null` reading as `string null`.
…reference CSS The rule hiding the trailing `In: header` line matched `p:has(> code)`, which is a shape, not a target — every scheme description in our specs cites a status code, so the whole explanation of personal vs workspace-scoped keys was display:none on every API reference page. Match the last child instead, and shorten the description to one line now that it renders. The dropdown trigger's hover rule had been left below a new id-qualified base rule that outranked it, so the trigger could no longer change colour on hover. Removes what does not run: the four `::-webkit-scrollbar` rules (specifying a non-auto scrollbar-width makes Chromium ignore them, and Firefox never had them) and an `order: 2` block whose selectors and declaration the type-token rule above it already carried. Names the two values the API reference repeats — the monospace stack, written out eleven times, and the 12.5px code size, written nine — as --font-mono-stack and --text-code. Also drops four !important declarations that already won on specificity, a --text-muted fallback that can never fire, and a lucide selector subsumed by the one beside it.
…mentary The metadata face — size, leading, weight, mono stack — was written out in seven rules that a comment asked future readers to keep in sync by hand; it is now one rule those seven consume, each adding only its own colour, content, and order. The auth row's chip likewise re-derived all eleven declarations of the type token and now joins that rule, keeping only its label. Comments were running longer than the rules they documented — 88 added comment lines against 73 declarations. Trimmed to the load-bearing facts: cascade traps, browser behaviour, and the bugs a rule prevents. Dropped the block narrating why the wrap rules were reverted, which duplicated its own commit message. Also retires a scrollbar token left unreferenced by the webkit removal, moves the last two fumadocs colours in our own components onto platform tokens, and brings the callout icon to 1.55 so the docs really do have one icon weight.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
PR SummaryLow Risk Overview Row metadata — Content bug — The rule that hid redundant “In: header” text used Consistency — Status dropdown, Cleanup — Removed ineffective Reviewed by Cursor Bugbot for commit 256147f. Configure here. |
Greptile SummaryThe PR standardizes API-reference typography and metadata styling while fixing the selector that hid API-key descriptions. It also shortens the shared API-key description and regenerates the seven OpenAPI documents.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| apps/docs/app/global.css | Refines the fenced API-reference presentation rules and fixes the overly broad selector that hid authentication descriptions. |
| apps/sim/lib/api/contracts/v2/openapi/shared.ts | Shortens the shared API-key description used to generate the public OpenAPI documents. |
| apps/docs/openapi-v2-billing.json | Regenerates the billing OpenAPI document with the updated shared API-key description. |
| apps/docs/openapi-v2-files-audit.json | Regenerates the files-audit OpenAPI document with the updated shared API-key description. |
| apps/docs/openapi-v2-knowledge.json | Regenerates the knowledge OpenAPI document with the updated shared API-key description. |
| apps/docs/openapi-v2-logs.json | Regenerates the logs OpenAPI document with the updated shared API-key description. |
| apps/docs/openapi-v2-resources.json | Regenerates the resources OpenAPI document with the updated shared API-key description. |
| apps/docs/openapi-v2-tables.json | Regenerates the tables OpenAPI document with the updated shared API-key description. |
| apps/docs/openapi-v2-workflows.json | Regenerates the workflows OpenAPI document with the updated shared API-key description. |
Reviews (3): Last reviewed commit: "fix(docs): keep the union separator in t..." | Re-trigger Greptile
|
@cursor review |
The `|` between union members is a classless span, so the page-wide `span:not(.font-mono)` rule assigned it the body sans face while the members beside it stayed mono — one chip rendering in two faces. Applies the inherit reset to every descendant of a type token rather than just its links, so anything fumadocs nests there later is covered too.
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 256147f. Configure here.
Summary
.font-monoon specificitystring | null), array (array<T>), and schema reference each carried their own chip definition and rendered at different sizes, weights, faces, and box heights; they are now one code token reusing the docs inline-code recipe at the platform's 20px chip heightrequiredandheaderwere filled pills,requiredon the error token, which made a constraint the loudest thing on the page. Both are now uncontained text, leaving the type token as the only box on a rowIn: headerline matchedp:has(> code), so it also hid the entire API key description on every API reference page. Matched by position now, and the description shortened to one lineapplication/jsonlabels and the status-code tabs to one treatment; they rendered the same strings at different weights and facesCleanup in the same pass: removed the four
::-webkit-scrollbarrules (a non-autoscrollbar-widthmakes Chromium ignore them, so they never ran), anorder: 2block the type-token rule already covered, and thepre-wraprules that never applied because fumadocs sizes the block withw-max. Named the two repeated values (--font-mono-stack, written out 11 times;--text-code, 9 times) and collapsed the metadata face from seven hand-synced copies into one rule.Type of Change
Testing
Tested manually against the running docs server in both light and dark themes, verifying computed styles rather than by eye — every type slot now resolves to the same face, size, weight, and 20px box, and the auth chip matches the path chip exactly (57px, was 65px). Confirmed
lint:check,check:openapi(7 specs, 135 operations),check:api-validation, docstype-check, and a full docs production build.Notes
Deliberately left for a follow-up, since each is a change of a different kind:
SIM_LIGHT_RULES/SIM_DARK_RULES) — notably strings green rather than blue, which is most of a JSON response body. Both config hooks exist (shikiOptionsoncreateAPIPage,rehypeCodeOptionsfor MDX); the work is authoring the TextMate scope mapping.header/required/stringthrough CSScontent:. All seven specs declare the sameapiKey/in: headerscheme so it is accurate today, but it is a stylesheet asserting an API fact, and pseudo-element text is not selectable or findable with Cmd+F.renderOperationLayoutalready receives the dereferenced schema, so an app-owned auth component would read it properly.renderHeadingandrenderCodeBlockwould let us drop fumadocs' lucide glyphs for the emcnHeading/CodeBlockcomponents the app already owns, retiring the stroke-width rule.Checklist