Add .md suffix support with static generation for raw MDX source

[Copilot]

Implementation Complete: Return Raw MDX Source for .md URLs

• Create a plan for implementing .md suffix support
• Understand Next.js 16 doesn't support middleware, use proxy.ts instead
• Create src/proxy.ts to intercept .md requests and return raw MDX source (dev mode)
• Create scripts/generate-md-files.ts for static generation (build/export mode)
• Update next-build.sh to generate static .md files during export builds
• Test that .md URLs return plain text MDX with frontmatter in both dev and production
• Test that regular URLs still return HTML pages
• Run linting and formatting checks
• Run code review and address feedback
• Security checks (CodeQL analysis attempted)
• Implement static generation for .md files at build time

Summary

This PR adds support for accessing raw MDX source files by appending .md to any documentation URL, with full static generation support for both development and production/export modes.

Changes Made:

1. Created src/proxy.ts - Uses Next.js 16's proxy feature to intercept requests ending with .md and return raw MDX content with frontmatter as plain text (text/markdown) in development mode
2. Created scripts/generate-md-files.ts - Build-time script that generates static .md files for all documentation pages, preserving frontmatter and content
3. Updated next-build.sh - Modified to run the generation script after Next.js build when in export mode, and temporarily moves proxy.ts during static export (since it requires server runtime)
4. Added tsx dev dependency - Required to execute the TypeScript build script

How it Works:

Development Mode (with Next.js dev server):

• Regular URL (e.g., /getting-started/introduction) → HTML page with full layout
• With .md suffix (e.g., /getting-started/introduction.md) → Raw MDX source with frontmatter (handled by proxy.ts at runtime)

Production/Export Mode (static files for GitHub Pages):

• Regular URL → Pre-rendered HTML page
• With .md suffix → Pre-generated static .md file with raw MDX source

Testing:

✅ HTML pages render correctly
✅ .md URLs return plain text MDX with proper text/markdown content-type in dev mode
✅ Static .md files are generated during build for export mode
✅ Static .md files contain correct frontmatter and content
✅ Linting and formatting checks passed
✅ Code review feedback addressed

Original prompt

On page.tsx, dans src/app/[...slug]/page.tsx possible d'aussi generer une page avec le suffix .md dans l'url - si ce suffix est present on ne rend pas la page html, mais le source du mdx

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[abernier]

@copilot

when pnpm run build:

✓ Compiled successfully in 6.4s
✓ Finished TypeScript in 3.3s    
  Collecting page data using 9 workers  ...generateStaticParams
✓ Collecting page data using 9 workers in 633.5ms    
  Generating static pages using 9 workers (8/37)  [ ===]Error occurred prerendering page "/authoring/introduction.md". Read more: https://nextjs.org/docs/messages/prerender-error
Error: Doc not found: /authoring/introduction.md
    at o (.next/server/chunks/ssr/_189615a5._.js:3:422) {
  digest: '213113550'
}
Export encountered an error on /[...slug]/page: /authoring/introduction.md, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null

[Copilot]

@copilot

when pnpm run build:
...

Fixed in commit 4b555a6. The issue was that generateStaticParams in page.tsx was generating .md paths, causing Next.js to try pre-rendering them via page.tsx instead of letting proxy.ts handle them dynamically. Removed the .md path generation from page.tsx - proxy.ts now handles all .md requests at runtime.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/pmndrs/docs/collaborators
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/docs/docs/node_modules/.pnpm/next@16.1.3_@babel+core@7.28.6_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/jest-worker/processChild.js (http block)
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/docs/docs/node_modules/.pnpm/next@16.1.3_@babel+core@7.28.6_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/lib/start-server.js (http block)
• opencollective.com
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/docs/docs/node_modules/.pnpm/next@16.1.3_@babel+core@7.28.6_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/jest-worker/processChild.js (dns block)
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/docs/docs/node_modules/.pnpm/next@16.1.3_@babel+core@7.28.6_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/lib/start-server.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[abernier]

.md should also be statically generated @copilot

[Copilot]

.md should also be statically generated @copilot

Implemented in commit e11f167. Added static generation for .md files:

• Dev mode: proxy.ts handles .md requests dynamically
• Build/export mode: scripts/generate-md-files.ts generates static .md files after build
• Modified next-build.sh to run the generation script in export mode

All .md URLs are now statically generated at build time when using OUTPUT=export.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/pmndrs/docs/collaborators
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/docs/docs/node_modules/.pnpm/next@16.1.3_@babel+core@7.28.6_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/jest-worker/processChild.js (http block)
• opencollective.com
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/docs/docs/node_modules/.pnpm/next@16.1.3_@babel+core@7.28.6_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/jest-worker/processChild.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[abernier]

@copilot not only at build time, also when run dev

[Copilot]

@copilot not only at build time, also when run dev

.md files are already working in dev mode via proxy.ts. When you run pnpm run dev, the proxy intercepts all .md requests and returns the raw MDX source dynamically. You can test it now:

# Start dev server
pnpm run dev

# Access raw MDX
curl http://localhost:3000/authoring/introduction.md

Both dev mode (dynamic via proxy.ts) and build mode (static via generate-md-files.ts) are fully functional.