feat: better separation of mdx content and headings support (#5467)

next.config.mjs

@@ -7,6 +7,8 @@ const nextConfig = {
   // We intentionally disable Next.js's built-in i18n support
   // as we dom have our own i18n and internationalisation engine
   i18n: null,
+  // We want to always enforce that SWC minifies the sources even during Development mode
+  // so that bundles are minified on-the-go. SWF minifying is fast, and has almost no penalties
   swcMinify: true,
   // We don't use trailing slashes on URLs from the Node.js Website
   trailingSlash: false,
@@ -30,18 +32,10 @@ const nextConfig = {
     // We disable the support for legacy browsers which should reduce the polyiffing
     // and the overall bundle size for the Node.js Website client runtime
     legacyBrowsers: false,
-    // This feature reduces the Next.js memory consumption by compartimentalising
-    // the Webpack builds into smaller threads that are responsible for building
-    // smaller pieces of the website instead of all pages at onces
-    // this increases slightly build time in favor of less memory usage
-    webpackBuildWorker: true,
     // Some of our static pages from `getStaticProps` have a lot of data
     // since we pass the fully-compiled MDX page from `MDXRemote` through
     // a page's static props.
     largePageDataBytes: 128 * 100000,
-    // This allows us to use SuperJson which supports custom data types for the JSON schema
-    // @see https://github.com/blitz-js/superjson
-    swcPlugins: [['next-superjson-plugin', {}]],
     // We disable the bundling and tracing of some files on the Serverless & Edge Runtimes
     // as otherwise they would explode the bundle size (server) and the tracing time
     outputFileTracingExcludes: {

next.dynamic.mjs

@@ -2,7 +2,9 @@
 
 import { join } from 'node:path';
 import { readFileSync } from 'node:fs';
+import { VFile } from 'vfile';
 import remarkGfm from 'remark-gfm';
+import remarkHeadings from '@vcarl/remark-headings';
 import { serialize } from 'next-mdx-remote/serialize';
 import * as nextLocales from './next.locales.mjs';
 import * as nextConstants from './next.constants.mjs';
@@ -139,20 +141,34 @@ export const getStaticProps = async (source = '', filename = '') => {
   // We only attempt to serialize data if the `source` has content and `filename` has content
   // otherwise we return a 404 since this means that it is not a valid file or a file we should care about
   if (source.length && filename.length) {
+    // We create a VFile (Virtual File) to be able to access some contextual
+    // data post serialization (compilation) of the source Markdown into MDX
+    const sourceAsVirtualFile = new VFile(source);
+
     // This act as a MDX "compiler" but, lightweight. It parses the Markdown
     // string source into a React Component tree, and then it serializes it
     // it also supports Remark plugins, and MDX components
     // Note.: We use the filename extension to define the mode of execution
-    const content = await serialize(source, {
+    const { compiledSource } = await serialize(sourceAsVirtualFile, {
       parseFrontmatter: true,
       mdxOptions: {
-        remarkPlugins: [remarkGfm],
+        remarkPlugins: [remarkGfm, remarkHeadings],
         format: filename.includes('.mdx') ? 'mdx' : 'md',
       },
     });
 
+    // After the MDX gets processed with the remarkPlugins, some extra `data` that might come along
+    // the `frontmatter` comes from `serialize` built-in support to `remark-frontmatter`
+    const { headings, matter: rawFrontmatter } = sourceAsVirtualFile.data;
+
+    // This serialises the Frontmatter into a JSON object that is compatible with the
+    // `getStaticProps` supported data type for props. (No prop value can be an object or not a primitive)
+    const frontmatter = JSON.parse(JSON.stringify(rawFrontmatter));
+
     // this defines the basic props that should be passed back to the `DynamicPage` component
-    staticProps.props = { content };
+    // We only want the `compiledSource` as we use `MDXProvider` for custom components along the journey
+    // And then we want the frontmatter and heading information from the VFile `data`
+    staticProps.props = { content: compiledSource, headings, frontmatter };
     staticProps.notFound = false;
   }