Skip to content

v1.17.0

Choose a tag to compare

@dkdev24 dkdev24 released this 17 Oct 08:39
· 40 commits to main since this release

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-portability check 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-parity check 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.config sets site, root-relative otherwise. base is respected.
  • LinkCard becomes a list item with the description on its own line under the link,
    LinkButton a link, Badge (text), Aside a **Note:**/title label, Card/TabItem a bold
    label. CardGrid, Steps, Tabs, FileTree wrappers 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.)