Astro Starlight + `text/markdown`

Starlight sites contain exactly the material coding agents need: installation steps, API references, concepts, and troubleshooting. HTML delivery works, but Markdown removes interface chrome and reduces context spent on navigation and presentation.

Because Starlight runs on Astro, the Markdown for Agents integration can be added through astro.config.mjs.

Install

pnpm add @puralex/astro-markdown-for-agents

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import markdownForAgents from '@puralex/astro-markdown-for-agents';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Product Docs',
    }),
    markdownForAgents({
      siteTitle: 'Product Docs',
      siteDescription: 'Installation, API, and operations documentation.',
    }),
  ],
});

Static Starlight deployments

Most Starlight sites use static output. During the build, each generated documentation page receives a matching Markdown file and llms.txt entry.

For this route:

/guides/deploy/

the output includes:

/guides/deploy/index.html
/guides/deploy/index.md

Link retrieval tools to the explicit Markdown URL, or configure a hosting-layer rewrite.

Server-rendered documentation

If documentation uses Astro server output, middleware can return Markdown from the original URL:

curl -H "Accept: text/markdown" https://docs.example.com/guides/deploy/

Browser requests remain HTML.

Conversion quality checks

Starlight pages can contain tabs, asides, expressive code blocks, autogenerated headings, and custom components. Review representative pages before rollout:

Installation guide with shell commands.
API reference with tables.
Page containing callouts or asides.
Long page with nested lists.
Custom MDX component output.

The converter operates on rendered HTML, so custom components need meaningful server-rendered markup. Interactive state that only appears after client JavaScript will not be present.

Keep agent content focused

High-quality documentation benefits both people and agents:

One task per guide.
Descriptive headings.
Complete code samples.
Stable internal links.
Explicit prerequisites and expected results.
Error messages written exactly as users see them.

Markdown delivery reduces transport noise. It cannot repair vague or outdated documentation.

Measure impact

Compare representative HTML and Markdown payloads:

curl -s https://docs.example.com/guide/ | wc -c
curl -s -H "Accept: text/markdown" https://docs.example.com/guide/ | wc -c

Also inspect semantic quality. Smaller output is useful only when important warnings, code, and links remain intact.

Astro Starlight + text/markdown