docs: name the current site in both version banners and add a beta callout to the landing page - #2401
Conversation
…llout to the landing The banners now say where the reader is, not only where they can go (v2: 'the documentation for the v2 beta'; v1: 'the documentation for v1.x'), and the v2 landing page opens with a beta callout: status, the spec the API tracks, the feedback issue form, and the v1 docs. Also drops a stale drafting-status frontmatter key from the landing page.
|
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs-only copy changes to the version banners and a beta callout on the landing page; the inline note about banner wrapping on very narrow viewports is a cosmetic nit that needn't block.
Extended reasoning...
Overview
The PR touches three files: the v2 and v1 Banner.vue components (copy-only changes naming the current site) and docs/index.md (a new ::: info v2 beta callout plus removal of a stale status: calibration frontmatter key). No code, no API surface, no protocol behavior is affected.
Verification
The linked feedback issue template .github/ISSUE_TEMPLATE/v2-feedback.yml exists in the repo, and the v1/v2 cross-site links match the URLs already used by the existing banners. Nothing in docs/.vitepress reads the removed status frontmatter key (it is only an authoring convention documented in docs/_meta/CONVENTIONS.md), so dropping it is inert. The author reports a clean pnpm docs:build with no dead links.
Security risks
None — static documentation prose and Vue template text only; the links point to first-party MCP domains and the repo's own issue template.
Level of scrutiny
Low: presentation-only docs change with no impact on the SDK packages, tests, or CI. The single finding (longer banner copy can wrap/clip inside the fixed 36px banner on ~320–360px viewports) is a cosmetic mobile nit posted inline and does not warrant blocking.
Other factors
No changeset is needed for a docs-site-only change, consistent with recent docs PRs on this repo. No outstanding reviewer comments.
| This is the documentation for the v2 beta — looking for the | ||
| <a href="https://ts.sdk.modelcontextprotocol.io/" target="_self">v1 documentation</a>? |
There was a problem hiding this comment.
🟡 The new, longer banner copy can wrap to 2–3 lines on narrow phone-width viewports (~320–360px), but .version-banner in the shared docs/.vitepress/theme/custom.css keeps a fixed 36px height with overflow: hidden, so the wrapped text gets vertically clipped — this affects both the v2 and v1 banners since they share the same stylesheet. Consider shortening/hiding the prefix below a breakpoint or letting the banner auto-size (and updating --vp-layout-top-height).
Extended reasoning...
What happens. Both Banner.vue files render into VitePress's layout-top slot and are styled by the shared .version-banner rule in docs/.vitepress/theme/custom.css (lines 142–160): position: fixed, height: var(--vp-layout-top-height) (hard-coded to 36px at line 60), display: flex, align-items: center, overflow: hidden, padding: 0 16px, font-size: 13px, line-height: 1.3. There are no media queries anywhere in the file and neither Banner.vue has scoped styles, so nothing adapts the banner for narrow viewports. The v1 site imports the exact same stylesheet (docs/v1/.vitepress/theme/index.ts → ../../../.vitepress/theme/custom.css), so both banners are governed by this sizing.\n\nWhy this PR triggers it. The previous copy ("Looking for the v1 documentation?", ~33 chars) fit on one line even at 320px. The new prefix ("This is the documentation for the v2 beta — looking for the", ~61 chars) is roughly 370–390px wide at 13px — wider than the usable content area of any phone-width viewport once the 32px of horizontal padding is subtracted. Inside the flex row, that prefix is an anonymous flex item that wraps internally, while the <a> link is a sibling flex item that only shrinks to its min-content (~the width of "documentation").\n\nStep-by-step example (320px viewport). Usable width = 320 − 32 (padding) ≈ 288px. The link's min-content takes ~85–90px and the trailing "?" a few more, leaving ~190px for the prefix item. A ~380px-wide prefix squeezed into ~190px wraps to 3 lines. At 13px × 1.3 line-height ≈ 16.9px per line, 3 lines ≈ 51px — well over the fixed 36px banner height. With align-items: center + overflow: hidden, the first and last lines are vertically cut in half. At ~360–375px the prefix typically wraps to 2 lines (~34px), which just fits inside 36px but still renders as a cramped two-line strip rather than the single tidy line the banner was designed for.\n\nAddressing the dissenting verifier. One verifier correctly points out that at common 360–400px widths two lines (~34px) still fit within the 36px box, so outright clipping is mostly limited to the very narrow end (~≤340px) and the exact breakpoint depends on font metrics. That's fair — the original report's "clearly at 375px" was overstated. But the regression at the narrow end is real (3 lines cannot fit in 36px under any reasonable metrics), and even where it doesn't clip, the doubled copy turns the banner into a wrapped two-line strip on most phones, which the old copy never did. The actionable v1/v2 link itself remains visible in all cases since it's a separately centered flex item.\n\nHow to fix. Any of: (1) hide or shorten the "This is the documentation for…" prefix below a breakpoint (e.g. wrap it in a <span class="banner-prefix"> and display: none it under ~480px), (2) let the banner auto-size (min-height instead of height, drop overflow: hidden) and bump --vp-layout-top-height responsively so the layout offset stays correct, or (3) keep the new wording only on wider screens. Purely presentational and limited to narrow mobile viewports on the docs site, so this should not block the PR.
1 participant
Two small presentation changes to the v2 docs site, following the Python SDK docs.
Motivation and Context
The site banner only said where the reader could go ("Looking for the v1 documentation?") without saying where they are; the landing page had no version-status callout. Both are standard on the Python SDK docs site.
v2 betainfo callout under the title: status, the spec the API tracks, a link to the v2 feedback issue form, and the v1 documentation link.How Has This Been Tested?
pnpm docs:build(0 dead links, 0 typedoc warnings) and the rendered output inspected.Breaking Changes
None.
Types of changes
Checklist
Additional context
Also removes a stale drafting-status frontmatter key from the landing page.