Uh oh!
There was an error while loading. Please reload this page.
docs: point readers (and their LLMs) at the markdown renditions - #2427
Conversation
Every guide page gets a muted footer line above the prev/next cards linking its own markdown rendition plus llms.txt and llms-full.txt, and a rel=alternate markdown link in its head for tools that look for one. The API reference pages have no renditions, so they get neither.
|
@modelcontextprotocol/client@modelcontextprotocol/codemod@modelcontextprotocol/core@modelcontextprotocol/server@modelcontextprotocol/server-legacy@modelcontextprotocol/express@modelcontextprotocol/fastify@modelcontextprotocol/hono@modelcontextprotocol/nodecommit: |
There was a problem hiding this comment.
LGTM — small docs-site-only change (VitePress theme/config) that surfaces the existing markdown renditions; the sidebar covers every built guide page, so the new footer and rel=alternate links all resolve.
Extended reasoning...
Overview
This PR touches only the docs site tooling: docs/.vitepress/config.mts gains a transformPageData hook adding a rel=alternate type=text/markdown head link on non-API pages, a new MarkdownSource.vue footer component is slotted into doc-footer-before, plus supporting CSS. No SDK package code, exports, or protocol behavior is affected.
Security risks
None. The change adds static links to already-published artifacts (per-page .md renditions, llms.txt, llms-full.txt) generated by the existing llms.ts build step. No user input, auth, or runtime code paths are involved.
Level of scrutiny
Low — this is documentation-site presentation code. The main correctness question is whether every page that gets the footer/head link actually has a markdown rendition. I cross-checked docs/.vitepress/nav.ts (which drives generateLlmsArtifacts) against the markdown files under docs/: every built guide page is in the sidebar (the only file not covered, behavior-surface-pins.md, is in srcExclude and never built), and API pages are correctly excluded in both the head-link hook and the Vue component. The ${siteUrl}/${relativePath} and withBase URL constructions match how llms.ts writes the renditions (<page>.md next to the HTML), and target=\"_self\" mirrors the established pattern from the version banner.
Other factors
The author reports pnpm docs:build green with rendered output verified, no changeset is needed for docs-only changes, and the bug hunting system found no issues.
Uh oh!
There was an error while loading. Please reload this page.
Makes the markdown renditions discoverable from the HTML site. Every guide page gets a muted footer line above the prev/next cards — "Are you an LLM (or feeding one)? This page as markdown · llms.txt · llms-full.txt" — and a
<link rel="alternate" type="text/markdown">in its head pointing at its own.mdrendition.Motivation and Context
#2407 added llms.txt and per-page markdown renditions, but nothing on the HTML site mentions them — an agent (or a person about to paste docs into a chat) landing on a page from search has no way to find the markdown twin. The footer line covers humans and agents reading the page; the head link is the machine-standard pointer for tools that look for one.
The API reference pages have no renditions, so they get neither.
How Has This Been Tested?
pnpm docs:buildgreen (0 dead links). Rendered output verified: the footer line and head link present on guide pages with the correct per-page URL, both absent on API pages.target="_self"keeps the SPA router from intercepting the non-HTML links (same fix as the version banners in #2396).Breaking Changes
None.
Types of changes
Checklist