feat: add markdown output support for package pages

Serve package info as Markdown via /raw/<package>.md routes.
Clients can request Markdown by adding Accept: text/markdown header
to any package URL (/package/vue, /vue, etc.).

Content includes: metadata, stats, links (npmx + npm + repo + homepage),
compatibility (engines), dist-tags, keywords, maintainers, and README.

- Add server route handler at /raw/[...slug].md.get.ts
- Add markdown generation utility at server/utils/markdown.ts
- Add Vercel rewrite rules for content negotiation
- Add ISR caching (60s) for /raw/** routes
- Add <link rel=alternate type=text/markdown> to package page
- Add comprehensive unit tests (35 tests, ~98% coverage)

Author: BYK

app/pages/package/[[org]]/[name].vue

@@ -495,7 +495,10 @@ const numberFormatter = useNumberFormatter()
 const bytesFormatter = useBytesFormatter()
 
 useHead({
-  link: [{ rel: 'canonical', href: canonicalUrl }],
+  link: [
+    { rel: 'canonical', href: canonicalUrl },
+    { rel: 'alternate', type: 'text/markdown', href: `/raw/${packageName.value}.md` },
+  ],
 })
 
 useSeoMeta({

nuxt.config.ts

@@ -100,6 +100,7 @@ export default defineNuxtConfig({
   routeRules: {
     // API routes
     '/api/**': { isr: 300 },
+    '/raw/**': { isr: 60 },
     '/api/registry/badge/**': {
       isr: {
         expiration: 60 * 60 /* one hour */,

server/routes/raw/[...slug].md.get.ts

@@ -0,0 +1,169 @@
+import { generatePackageMarkdown } from '../../utils/markdown'
+import { isStandardReadme, fetchReadmeFromJsdelivr } from '../../utils/readme-loaders'
+import * as v from 'valibot'
+import { PackageRouteParamsSchema } from '#shared/schemas/package'
+import { NPM_MISSING_README_SENTINEL, ERROR_NPM_FETCH_FAILED } from '#shared/utils/constants'
+
+// Cache TTL matches the ISR config for /raw/** routes (60 seconds)
+const CACHE_MAX_AGE = 60
+
+const NPM_API = 'https://api.npmjs.org'
+
+const standardReadmeFilenames = [
+  'README.md',
+  'readme.md',
+  'Readme.md',
+  'README',
+  'readme',
+  'README.markdown',
+  'readme.markdown',
+]
+
+function encodePackageName(name: string): string {
+  if (name.startsWith('@')) {
+    return `@${encodeURIComponent(name.slice(1))}`
+  }
+  return encodeURIComponent(name)
+}
+
+async function fetchWeeklyDownloads(packageName: string): Promise<{ downloads: number } | null> {
+  try {
+    const encodedName = encodePackageName(packageName)
+    return await $fetch<{ downloads: number }>(
+      `${NPM_API}/downloads/point/last-week/${encodedName}`,
+    )
+  } catch {
+    return null
+  }
+}
+
+function parsePackageParamsFromSlug(slug: string): {
+  rawPackageName: string
+  rawVersion: string | undefined
+} {
+  const segments = slug.split('/').filter(Boolean)
+
+  if (segments.length === 0) {
+    return { rawPackageName: '', rawVersion: undefined }
+  }
+
+  const vIndex = segments.indexOf('v')
+
+  if (vIndex !== -1 && vIndex < segments.length - 1) {
+    return {
+      rawPackageName: segments.slice(0, vIndex).join('/'),
+      rawVersion: segments.slice(vIndex + 1).join('/'),
+    }
+  }
+
+  const fullPath = segments.join('/')
+  const versionMatch = fullPath.match(/^(@[^/]+\/[^@]+|[^@]+)@(.+)$/)
+  if (versionMatch) {
+    const [, packageName, version] = versionMatch as [string, string, string]
+    return {
+      rawPackageName: packageName,
+      rawVersion: version,
+    }
+  }
+
+  return {
+    rawPackageName: fullPath,
+    rawVersion: undefined,
+  }
+}
+
+export default defineEventHandler(async event => {
+  // Get the slug parameter - Nitro captures it as "slug.md" due to the route pattern
+  const params = getRouterParams(event)
+  const slugParam = params['slug.md'] || params.slug
+
+  if (!slugParam) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Package not found',
+    })
+  }
+
+  // Remove .md suffix if present (it will be there from the route)
+  const slug = slugParam.endsWith('.md') ? slugParam.slice(0, -3) : slugParam
+
+  const { rawPackageName, rawVersion } = parsePackageParamsFromSlug(slug)
+
+  if (!rawPackageName) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Package not found',
+    })
+  }
+
+  const { packageName, version } = v.parse(PackageRouteParamsSchema, {
+    packageName: rawPackageName,
+    version: rawVersion,
+  })
+
+  let packageData
+  try {
+    packageData = await fetchNpmPackage(packageName)
+  } catch {
+    throw createError({
+      statusCode: 502,
+      statusMessage: ERROR_NPM_FETCH_FAILED,
+    })
+  }
+
+  let targetVersion = version
+  if (!targetVersion) {
+    targetVersion = packageData['dist-tags']?.latest
+  }
+
+  if (!targetVersion) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Package version not found',
+    })
+  }
+
+  const versionData = packageData.versions[targetVersion]
+  if (!versionData) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Package version not found',
+    })
+  }
+
+  let readmeContent: string | undefined
+
+  if (version) {
+    readmeContent = versionData.readme
+  } else {
+    readmeContent = packageData.readme
+  }
+
+  const readmeFilename = version ? versionData.readmeFilename : packageData.readmeFilename
+  const hasValidNpmReadme = readmeContent && readmeContent !== NPM_MISSING_README_SENTINEL
+
+  if (!hasValidNpmReadme || !isStandardReadme(readmeFilename)) {
+    const jsdelivrReadme = await fetchReadmeFromJsdelivr(
+      packageName,
+      standardReadmeFilenames,
+      targetVersion,
+    )
+    if (jsdelivrReadme) {
+      readmeContent = jsdelivrReadme
+    }
+  }
+
+  const weeklyDownloadsData = await fetchWeeklyDownloads(packageName)
+
+  const markdown = generatePackageMarkdown({
+    pkg: packageData,
+    version: versionData,
+    readme: readmeContent && readmeContent !== NPM_MISSING_README_SENTINEL ? readmeContent : null,
+    weeklyDownloads: weeklyDownloadsData?.downloads,
+  })
+
+  setHeader(event, 'Content-Type', 'text/markdown; charset=utf-8')
+  setHeader(event, 'Cache-Control', `public, max-age=${CACHE_MAX_AGE}, stale-while-revalidate`)
+
+  return markdown
+})