[docs-infra] Add Markdown Alternates

[dav-is]

For each page.mdx, we should generate a markdown alternate.

e.g. /app/components/checkbox/page.mdx will be availiable at /components/checkbox with a markdown alternate stored at /components/checkbox.md

To install, create app/[...markdownPath]/route.ts:

export * from '@mui/internal-docs-infra/markdownAlternatePage';

This route exports generateStaticParams with a list of all expected .md files.

Add to your build script in the docs package.json:

  "scripts": {
    "dev": "next dev --turbopack",
-   "build": "next build",
+   "build": "next build && docs-infra post-build",
    "start": "serve ./out"
  },

To publish this markdown, each page should add this to the head:

<link rel="alternate" type="text/markdown" href="/components/checkbox.md" title="Markdown" />

and this to HTTP headers so the alternate can be discovered using a HEAD request:

Link: </components/checkbox.md>; rel="alternate"; type="text/markdown"; title="Markdown"

A link should also be added somewhere directly in the page.

If the server is capable of Next.js rewrites, it should also support Accept: text/markdown and Accept: text/plain

module.exports = {
  async rewrites() {
    return {
      beforeFiles: [
        {
          source: '/:path*',
          has: [{ type: 'header', key: 'Accept', value: '^(?!text/html).*text/markdown.*$' }],
          destination: '/:path*.md',
        },
      ],
      afterFiles: [],
      fallback: [],
    }
  },
}