feat: tasteful concept-link policy in the API reference (events + first-occurrence dedup)#1210
Open
dawnho wants to merge 4 commits into
Open
feat: tasteful concept-link policy in the API reference (events + first-occurrence dedup)#1210dawnho wants to merge 4 commits into
dawnho wants to merge 4 commits into
Conversation
Event documentation pages re-declare shared properties (workspace_id, connected_account_id, device_id, ...) on every event, and each carried the same generic concept-page link from upstream @seamapi/types descriptions — workspace linked ~100x per page, connected account ~70x. These repeat links add noise without aiding comprehension. Add stripBoilerplateConceptLinks() in the event codegen to unwrap links to the seven generic core-concept/developer-tools pages, leaving the link text intact. Applied to event/property prose only (never the JSON example payloads, which must echo descriptions verbatim). Anchored and sub-path links (e.g. workspaces#sandbox-workspaces, devices/managed-and-unmanaged-devices) and all contextual links (thermostat set-points, credential guides, ISO-8601) are kept. Removes 214 boilerplate links across 21 event pages (276 -> 62). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Extend the concept-link policy beyond event pages. Consolidate the logic into a shared `concept-links.ts` module and add a codegen phase that, on every non-event API page, keeps the first link to each generic concept (workspace, connected account, device, ...) and unwraps every later occurrence to plain text. A concept link teaches on first encounter; repeating it on every shared property is noise. - `concept-links.ts`: shared `BOILERPLATE_CONCEPT_PATHS`, `stripConceptLinks` (event pages, unwrap all), `dedupeConceptLinks` (other pages, keep first). The dedup skips fenced code blocks so example JSON payloads are untouched. - `events.ts`: reuse `stripConceptLinks` instead of a local copy. - `generate.ts`: run the dedup after canonicalization (Phase H). Anchored/sub-path links (e.g. `.../connect-webviews/customizing-...#...`) are left intact — only bare generic concept links are deduped. Removes 25 of 36 concept links across 7 object pages while preserving all contextual links. The root-cause cleanup of the foreign-key concept links lives upstream in seam-connect (seamapi/seam-connect#16179); this is the docs-rendering half. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dawnho
changed the title
…-concept-links-events # Conflicts: # mintlify-docs/api/client_sessions/object.mdx
…917.0) Regenerate object/event pages on the merged tree so the concept-link policy (event strip + first-occurrence dedup) is applied on top of the 1.917.0 type bump and the object-page TOC removal from main. openapi.json is left as main's (the concept-link changes only affect .mdx).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Generic concept nouns — workspace, connected account, device, Connect Webview, action attempt, client session, webhook — were linked to their core-concept pages on nearly every shared property, so the same link repeated dozens of times per page (workspace ~285×, connected account ~187× across the API reference). This is the docs-rendering half of a tasteful policy for these links; the root-cause source cleanup is seamapi/seam-connect#16179.
Governing principle: a concept link is a teaching aid — worth the most on first encounter, noise on repetition and on mechanical foreign-key fields.
Two behaviors (in
mintlify-codegen/concept-links.ts)stripConceptLinks), on prose only, at render time. Advanced audience + maximum repetition (every event re-declares the shared props). Example payloads are left byte-for-byte intact.dedupeConceptLinks, new Phase H): keep the first link to each concept, unwrap the rest. Skips fenced code blocks so example JSON is untouched.What's preserved
.../connect-webviews/customizing-connect-webviews#...,.../devices/managed-and-unmanaged-devices) — an anchor or deeper path carries real context.Impact
Relationship to the source fix
seamapi/seam-connect#16179 removes the foreign-key concept links at the source of truth (
public-types/models), which flows to@seamapi/types→@seamapi/blueprint→ these docs on the next dependency bump — and also cleans SDK type docstrings. This PR delivers the policy to the live docs now, and the first-occurrence dedup remains the durable home for the per-page rule (which can't be expressed in a per-field source description).Verification
npm run generate:mintlifyregenerated cleanly;typecheck,eslint,prettier --checkall pass.🤖 Generated with Claude Code