Files
supabase/apps/ui-library/middleware.ts
Saxon Fletcher bf60e6cdce feat(library): serve agent-readable markdown for each docs page (#49567)
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Feature: agent-readable markdown pages for the UI library docs.

## What is the current behavior?

Library docs are HTML-only. `llms.txt` lists page titles, but there is
no `.md` body an agent can fetch.

## What is the new behavior?

Each docs page is also served as markdown:

- Build-time MDX → markdown (`pnpm --filter library build:markdown`)
- `GET /library/docs/{slug}.md` (and `Accept: text/markdown`)
- HTML pages advertise `rel=alternate` `text/markdown`
- `llms.txt` links to the `.md` URLs

This is the base of a stack. The prompt-tab PR sits on top:
https://github.com/supabase/supabase/pull/49566

## Additional context

Interactive previews are omitted from the markdown. `BlockItem` emits
the production `npx shadcn add` command so agents still get an install
path.

## To test

1. `pnpm --filter library dev` (generates markdown in `predev`).
2. Open http://localhost:3004/library/docs/nextjs/password-based-auth.md
— markdown with the install command, file tree, and setup steps; no
interactive previews.
3. Open the same path without `.md` — HTML docs unchanged (no prompt tab
in this PR).
4. `curl -H 'Accept: text/markdown'
http://localhost:3004/library/docs/nextjs/password-based-auth` should
also return markdown.
5. http://localhost:3004/library/llms.txt — links should end in `.md`.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Documentation pages are available as Markdown through `.md` URLs and a
dedicated endpoint.
* Markdown is generated automatically during development and production
builds.
* Generated content preserves front matter, links, callouts,
installation instructions, and supported documentation elements.
* Installation commands support npm, pnpm, yarn, and bun for React and
Vue projects.

* **Bug Fixes**
* Improved Markdown file handling, link rewriting, and content
negotiation.

* **Tests**
* Added coverage for Markdown conversion, content negotiation, and
installation commands.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-01 11:35:55 +10:00

51 lines
1.5 KiB
TypeScript

import { negotiateMarkdown } from 'common/markdown-negotiation'
import { NextResponse, type NextRequest } from 'next/server'
import MARKDOWN_SLUGS from '@/public/markdown/manifest.json'
const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? '/library'
const DOCS_PATH = `${BASE_PATH}/docs`
const MARKDOWN_SLUG_SET = new Set(MARKDOWN_SLUGS)
export function middleware(request: NextRequest) {
const url = new URL(request.url)
const { pathname } = url
if (!pathname.startsWith(`${DOCS_PATH}/`)) {
return NextResponse.next()
}
// Server Actions POST to the page URL with `Accept: text/x-component`, which
// matches none of the types this route negotiates and would 406. Let Next.js
// handle them.
if (request.headers.get('next-action')) {
return NextResponse.next()
}
const isMdSuffix = pathname.endsWith('.md')
const slug = pathname.replace(`${DOCS_PATH}/`, '').replace(/\.md$/, '')
const decision = negotiateMarkdown(
{ acceptHeader: request.headers.get('accept') ?? '' },
{ hasMarkdownVariant: MARKDOWN_SLUG_SET.has(slug), isMarkdownSuffix: isMdSuffix }
)
if (decision === 'not-acceptable') {
return new NextResponse('Not Acceptable', {
status: 406,
headers: { 'Cache-Control': 'no-store', Vary: 'Accept' },
})
}
if (decision === 'markdown') {
const rewriteUrl = new URL(url)
rewriteUrl.pathname = `${BASE_PATH}/api/docs-md/${slug}`
return NextResponse.rewrite(rewriteUrl)
}
return NextResponse.next()
}
export const config = {
matcher: ['/docs/:path*'],
}