Repository navigation
v1.17.0
Fixed: Starlight .md mirrors now stand on their own
The src/pages/[...slug].md.ts route that enhance writes for Astro + Starlight served each page's
raw MDX body. Two problems, both found on a real production Starlight docs site:
- Relative links broke.
../guide/in a page at/docs/page/resolves to a different place
next to/docs/page.md, and to nothing once an agent has the text without its URL. afdocs 0.22's
markdown-link-portabilitycheck fails on this. - Component text was hidden. Starlight components stayed as raw JSX, and a
LinkCard's title
and description live in attributes, so card-based landing pages lost most of their text in the
markdown (36–90% missing on that site). afdocs'markdown-content-paritycheck fails on this.
The mirror now runs the body through toAgentMarkdown() in a new src/lib/md-mirror.js:
- Every link and image target is resolved against the page's HTML URL: absolute when
astro.configsetssite, root-relative otherwise.baseis respected. LinkCardbecomes a list item with the description on its own line under the link,
LinkButtona link,Badge(text),Asidea**Note:**/title label,Card/TabItema bold
label.CardGrid,Steps,Tabs,FileTreewrappers and import lines are dropped.- Fenced code is left untouched.
If you already ran enhance: it never overwrites your existing [...slug].md.ts. Re-running
siteready enhance now writes src/lib/md-mirror.js and warns when your route still serves the raw
body. Wire it in:
import { toAgentMarkdown } from '../lib/md-mirror.js';
// ...
const root = import.meta.env.BASE_URL.replace(/\/?$/, '/');
const slug = params.slug === 'index' ? '' : params.slug;
const pageUrl = new URL(`${root}${slug ? `${slug}/` : ''}`, site ?? 'http://localhost/');
const body = toAgentMarkdown(entry.body ?? '', pageUrl, Boolean(site));(params and site come from the GET handler's context.)