feat(mdx): move to app router with @next/mdx

[avivkeller]

Fixes #8262

View commits including and after 97e493e to isolate the changes (from the pure Markdown move)

---

TODO:

• next-data routes
• Blog categories
• Download archive
• Fallback Routes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
nodejs-org	Error		Jan 9, 2026 11:03pm

[github-actions]

👋 Codeowner Review Request

The following codeowners have been identified for the changed files:

Team reviewers: @nodejs/web-infra @nodejs/nodejs-website

Please review the changes when you have a chance. Thank you! 🙏

[avivkeller]

I'm aware reviewing this many files is impossible. Once I get everything passing, I will make this much more manageable. Right now, the goal was just to be in a position where a feature branch could be opened

[codecov]

❌ 2 Tests Failed:

Tests completed	Failed	Passed	Skipped
234	2	232	0

View the top 2 failed test(s) by shortest run time

test::getArticles

Stack Traces | 0.00727s run time

[Error [ERR_TEST_FAILURE]: Expected values to be strictly deep-equal:
+ actual - expected

  [
    {
      content: 'content',
+     pathname: '/'
-     pathname: 'filename'
    }
  ]
] {
  code: 'ERR_TEST_FAILURE',
  failureType: 'testCodeFailure',
  cause: AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal:
  + actual - expected
  
    [
      {
        content: 'content',
  +     pathname: '/'
  -     pathname: 'filename'
      }
    ]
  
      at TestContext.<anonymous> (.../runner/work/nodejs.org/nodejs..../orama-search/__tests__/get-documents.test.mjs:35:10)
      at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
      at async Test.run (node:internal/test_runner/test:1113:7)
      at async Test.processPendingSubtests (node:internal/test_runner/test:788:7) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: [ [Object] ],
    expected: [ [Object] ],
    operator: 'deepStrictEqual',
    diff: 'simple'
  }
}

test::scripts/blog-data/__test__/generate.test.mjs

Stack Traces | 1.94s run time

[Error: test failed] { code: 'ERR_TEST_FAILURE', failureType: 'testCodeFailure', cause: 'test failed', exitCode: 7, signal: null }

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[ovflowd]

casual tuesday 1am (cest): claudio about to chill with YouTube
aviv: Imma gonna destroy this man's plans muahahaha

[avivkeller]

I think you might wanna go back to that YouTube... this is no where near ready 😅. On the silver lining, through the process of building this, I have several bug reports to send to Next.js.

[github-actions]

📦 Build Size Comparison

Summary

Metric	Value
Old Total Size	3.75 MB
New Total Size	3.09 MB
Delta	-679.82 KB (-17.70%)

Changes

➕ Added Assets (1)

Name	Size
.next/static/chunks/3706bf043231ef56.js	205.09 KB

➖ Removed Assets (3)

Name	Size
.next/static/chunks/9385d8b2e7a095eb.js	205.09 KB
.next/static/chunks/96f7a6f942e912ae.js	561.55 KB
.next/static/chunks/976ea1c2d37f9b6c.js	118.27 KB

[avivkeller]

-743.48 KB (-19.53%)

😲

I'm still figuring out where this is a good thing or a bad thing :/

[ovflowd]

I think you might wanna go back to that YouTube... this is no where near ready 😅. On the silver lining, through the process of building this, I have several bug reports to send to Next.js.

Imma gonna back to another lifetime 😆 -- Im out! HAHAHA

[ovflowd]

-743.48 KB (-19.53%)

😲

I'm still figuring out where this is a good thing or a bad thing :/

🌡️

[ovflowd]

[avivkeller]

If I can get it to work, we should see a substantial size reduction on both the client and server build.... if I can get it to work

[Copilot]

Pull request overview

This PR refactors the Node.js website's MDX handling from a custom implementation to the Next.js-recommended next-mdx-remote library. The change simplifies the codebase by replacing custom MDX compilation logic with a well-supported third-party solution.

Key changes:

• Migrated from custom @mdx-js/mdx compilation to next-mdx-remote/rsc
• Removed dependencies on @vcarl/remark-headings, remark-reading-time, vfile, and vfile-matter (now handled by next-mdx-remote)
• Reorganized MDX-related code into a new router/ directory structure with dedicated plugin files
• Simplified page rendering logic across locale and blog routes

Reviewed changes

Copilot reviewed 30 out of 32 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Updated dependencies: added next-mdx-remote, moved @mdx-js/mdx to devDependencies, removed custom remark/vfile packages
apps/site/package.json	Aligned package changes with lock file
apps/site/types/server.ts	Updated type definitions to use inline heading type instead of @vcarl/remark-headings
apps/site/types/markdown.ts	Added MarkdownFile type and canonical frontmatter field
apps/site/util/array.ts	Added joinNested utility for path segment joining
apps/site/router/index.ts	New centralized router logic using next-mdx-remote's compileMDX
apps/site/router/render.tsx	Extracted page rendering logic into dedicated component
apps/site/router/page.ts	Shared page metadata and viewport generation logic
apps/site/router/mdx/plugins/*	Reorganized MDX plugins (table, headings, shiki) into dedicated files
apps/site/app/[locale]/page.tsx	Simplified page component using new router infrastructure
apps/site/app/[locale]/blog/[cat]/page.tsx	New blog category page using simplified routing
apps/site/app/[locale]/download/archive/[version]/page.tsx	Refactored to use new router infrastructure
apps/site/next.helpers.mjs	Simplified markdown file retrieval with new CONTENT_ROOT constant
apps/site/scripts/*	Updated to use new helper functions and constants

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ovflowd]

nit: children can be part os ...props spread,

return <LayoutComponent {...props} />

[ovflowd]

For all that is good, please make two separate branches one containing the changes/file moves and whatnot under pages amd the other being the actual code changes, otherwise reviewing the actual changes becomes impossible.

Make so that:

• main
  • feat/mdx-migration-core
    • chore/mdx-migration-files

Something like that.