web-infra-dev · SoonIter · Oct 20, 2025 · Timeless0911 · Oct 22, 2025
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -34,6 +34,9 @@
     "./shiki-transformers": {
       "types": "./dist/shiki-transformers.d.ts",
       "default": "./dist/shiki-transformers.js"
+    },
+    "./_private/react": {
+      "default": "./dist/_private/react/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -74,16 +77,19 @@
     "hast-util-heading-rank": "^3.0.0",
     "html-to-text": "^9.0.5",
     "lodash-es": "^4.17.21",
+    "mdast-util-mdx": "^3.0.0",
     "mdast-util-mdxjs-esm": "^2.0.1",
     "medium-zoom": "1.1.0",
     "picocolors": "^1.1.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-lazy-with-preload": "^2.2.1",
+    "react-reconciler": "0.33.0",
     "react-router-dom": "^6.30.1",
     "rehype-external-links": "^3.0.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.1",
     "shiki": "^3.12.2",
     "tinyglobby": "^0.2.15",
     "tinypool": "^1.1.1",
@@ -102,6 +108,7 @@
     "@types/node": "^22.8.1",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
+    "@types/react-reconciler": "^0.32.1",
     "execa": "8.0.1",
     "mdast-util-directive": "^3.1.0",
     "mdast-util-mdx-expression": "^2.0.1",

diff --git a/packages/core/rslib.config.ts b/packages/core/rslib.config.ts
@@ -24,6 +24,22 @@ export default defineConfig({
   lib: [
     generateEntry('./src/runtime.ts'),
     generateEntry('./src/theme.ts'),
+    {
+      bundle: false,
+      dts: false,
+      format: 'esm',
+      syntax: 'es2022',
+      source: {
+        entry: {
+          index: './src/node/ssg-md/react/*.ts',
+        },
+      },
+      output: {
+        distPath: {
+          root: './dist/_private/react',
+        },
+      },
+    },
     {
       format: 'esm',
       syntax: 'es2022',

diff --git a/packages/core/src/node/PluginDriver.ts b/packages/core/src/node/PluginDriver.ts
@@ -1,8 +1,10 @@
-import type {
-  PageIndexInfo,
-  RouteMeta,
-  RspressPlugin,
-  UserConfig,
+import {
+  addLeadingSlash,
+  addTrailingSlash,
+  type PageIndexInfo,
+  type RouteMeta,
+  type RspressPlugin,
+  type UserConfig,
 } from '@rspress/shared';
 import { haveNavSidebarConfig } from './auto-nav-sidebar';
 import type { RouteService } from './route/RouteService';
@@ -108,7 +110,17 @@ export class PluginDriver {
     }
   }
 
+  private async normalizeConfig() {
+    this.#config.ssg ??= true;
+    this.#config.llms ??= false;
+    this.#config.base = addTrailingSlash(
+      addLeadingSlash(this.#config.base ?? '/'),
+    );
+  }
+
   async modifyConfig() {
+    this.normalizeConfig();
+
     let config = this.#config;
 
     for (let i = 0; i < this.#plugins.length; i++) {

diff --git a/packages/core/src/node/auto-nav-sidebar/utils.ts b/packages/core/src/node/auto-nav-sidebar/utils.ts
@@ -24,6 +24,7 @@ export async function extractInfoFromFrontmatterWithAbsolutePath(
   overviewHeaders: number[] | undefined;
   context: string | undefined;
   tag: string | undefined;
+  description: string | undefined;
 }> {
   const fileHandle = await fs.open(absolutePath, 'r');
   try {
@@ -112,6 +113,7 @@ export async function extractInfoFromFrontmatterWithAbsolutePath(
       overviewHeaders: frontmatter.overviewHeaders,
       context: frontmatter.context,
       tag: frontmatter.tag,
+      description: frontmatter.description,
     };
   } finally {
     await fileHandle.close();

diff --git a/packages/core/src/node/build.ts b/packages/core/src/node/build.ts
@@ -17,7 +17,9 @@ export async function build(options: BuildOptions) {
   // 1. create PluginDriver
   const pluginDriver = await PluginDriver.create(config, configFilePath, true);
   const modifiedConfig = await pluginDriver.modifyConfig();
-  const ssgConfig = Boolean(modifiedConfig.ssg ?? true);
+  const enableSSG = Boolean(
+    (modifiedConfig.ssg || modifiedConfig.llms) ?? true,
+  );
 
   // 2. create RouteService
   const additionalPages = await pluginDriver.addPages();
@@ -42,15 +44,15 @@ export async function build(options: BuildOptions) {
       modifiedConfig,
       pluginDriver,
       routeService,
-      ssgConfig,
+      enableSSG,
     );
     await rsbuild.build();
   } finally {
     await checkLanguageParity(config);
   }
   await pluginDriver.afterBuild();
 
-  if (!ssgConfig) {
+  if (!enableSSG) {
     hintSSGFalse();
   }
 }
diff --git a/packages/core/src/node/constants.ts b/packages/core/src/node/constants.ts
@@ -52,6 +52,13 @@ export const SSR_SERVER_ENTRY = path.join(
   'ssrServerEntry.js',
 );
 
+export const SSG_MD_SERVER_ENTRY = path.join(
+  PACKAGE_ROOT,
+  'dist',
+  'runtime',
+  'ssrMdServerEntry.js',
+);
+
 export const OUTPUT_DIR = 'doc_build';
 
 export const APP_HTML_MARKER = '<!--<?- DOC_CONTENT ?>-->';
@@ -64,3 +71,6 @@ export const PUBLIC_DIR = 'public';
 // Prevent the risk of naming conflicts with the user's folders
 export const NODE_SSG_BUNDLE_FOLDER = '__ssg__';
 export const NODE_SSG_BUNDLE_NAME = 'rspress-ssg-entry.cjs';
+
+export const NODE_SSG_MD_BUNDLE_FOLDER = '__ssg_md__';
+export const NODE_SSG_MD_BUNDLE_NAME = 'rspress-ssg-md-entry.cjs';
diff --git a/packages/core/src/node/initRsbuild.ts b/packages/core/src/node/initRsbuild.ts
@@ -21,9 +21,12 @@ import {
   isProduction,
   NODE_SSG_BUNDLE_FOLDER,
   NODE_SSG_BUNDLE_NAME,
+  NODE_SSG_MD_BUNDLE_FOLDER,
+  NODE_SSG_MD_BUNDLE_NAME,
   OUTPUT_DIR,
   PACKAGE_ROOT,
   PUBLIC_DIR,
+  SSG_MD_SERVER_ENTRY,
   SSR_CLIENT_ENTRY,
   SSR_SERVER_ENTRY,
   TEMPLATE_PATH,
@@ -45,6 +48,7 @@ import { socialLinksVMPlugin } from './runtimeModule/socialLinks';
 import type { FactoryContext } from './runtimeModule/types';
 import { rsbuildPluginCSR } from './ssg/rsbuildPluginCSR';
 import { rsbuildPluginSSG } from './ssg/rsbuildPluginSSG';
+import { rsbuildPluginSSGMD } from './ssg-md/rsbuildPluginSSGMD';
 import {
   detectReactVersion,
   resolveReactAlias,
@@ -127,6 +131,7 @@ async function createInternalBuildConfig(
     detectCustomIcon(CUSTOM_THEME_DIR),
     resolveReactAlias(reactVersion, false),
     enableSSG ? resolveReactAlias(reactVersion, true) : Promise.resolve({}),
+    resolveReactAlias(reactVersion, true),
     resolveReactRouterDomAlias(),
   ]);
 
@@ -182,7 +187,7 @@ async function createInternalBuildConfig(
           ...siteDataVMPlugin(context),
         },
       }),
-      enableSSG
+      enableSSG && config.ssg
         ? rsbuildPluginSSG({
             routeService,
             config,
@@ -191,6 +196,12 @@ async function createInternalBuildConfig(
             routeService,
             config,
           }),
+      enableSSG && config.llms
+        ? rsbuildPluginSSGMD({
+            routeService,
+            config,
+          })
+        : null,
     ],
     server: {
       port:
@@ -300,6 +311,8 @@ async function createInternalBuildConfig(
     },
     tools: {
       bundlerChain(chain, { CHAIN_ID, environment }) {
+        const isSsg = environment.name === 'node';
+        const isSsgMd = environment.name === 'node_md';
         const jsModuleRule = chain.module.rule(CHAIN_ID.RULE.JS);
 
         const swcLoaderOptions = jsModuleRule
@@ -327,6 +340,7 @@ async function createInternalBuildConfig(
             docDirectory: userDocRoot,
             routeService,
             pluginDriver,
+            isSsgMd,
           })
           .end();
 
@@ -355,13 +369,20 @@ async function createInternalBuildConfig(
           .test(/\.rspress[\\/]runtime[\\/]virtual-global-styles/)
           .merge({ sideEffects: true });
 
-        if (environment.name === 'node') {
+        if (isSsg) {
           chain.output.filename(
             `${NODE_SSG_BUNDLE_FOLDER}/${NODE_SSG_BUNDLE_NAME}`,
           );
           chain.output.chunkFilename(`${NODE_SSG_BUNDLE_FOLDER}/[name].cjs`);
           // For perf
           chain.output.set('asyncChunks', false);
+        } else if (isSsgMd) {
+          chain.output.filename(
+            `${NODE_SSG_MD_BUNDLE_FOLDER}/${NODE_SSG_MD_BUNDLE_NAME}`,
+          );
+          chain.output.chunkFilename(`${NODE_SSG_MD_BUNDLE_FOLDER}/[name].cjs`);
+          // For perf
+          chain.output.set('asyncChunks', false);
         }
       },
     },
@@ -384,6 +405,7 @@ async function createInternalBuildConfig(
           ],
           define: {
             'process.env.__SSR__': JSON.stringify(false),
+            'process.env.__SSR_MD__': JSON.stringify(false),
           },
         },
         output: {
@@ -393,7 +415,7 @@ async function createInternalBuildConfig(
           },
         },
       },
-      ...(enableSSG
+      ...(enableSSG && config.ssg
         ? {
             node: {
               resolve: {
@@ -408,6 +430,46 @@ async function createInternalBuildConfig(
                 },
                 define: {
                   'process.env.__SSR__': JSON.stringify(true),
+                  'process.env.__SSR_MD__': JSON.stringify(false),
+                },
+              },
+              performance: {
+                printFileSize: {
+                  compressed: true,
+                },
+              },
+              output: {
+                emitAssets: false,
+                target: 'node',
+                minify: false,
+              },
+            },
+          }
+        : {}),
+      ...(enableSSG && config.llms
+        ? {
+            node_md: {
+              resolve: {
+                alias: {
+                  ...reactSSRAlias,
+                  ...reactRouterDomAlias,
+                },
+              },
+              tools: {
+                rspack: {
+                  optimization: {
+                    moduleIds: 'named',
+                    chunkIds: 'named',
+                  },
+                },
+              },
+              source: {
+                entry: {
+                  index: SSG_MD_SERVER_ENTRY,
+                },
+                define: {
+                  'process.env.__SSR__': JSON.stringify(true),
+                  'process.env.__SSR_MD__': JSON.stringify(true),
                 },
               },
               performance: {

diff --git a/packages/core/src/node/mdx/loader.ts b/packages/core/src/node/mdx/loader.ts
@@ -12,13 +12,23 @@ export default async function mdxLoader(
 
   const options = this.getOptions();
   const filepath = this.resourcePath;
-  const { config, docDirectory, routeService, pluginDriver } = options;
+  const {
+    config,
+    docDirectory,
+    routeService,
+    pluginDriver,
+    isSsgMd = false,
+  } = options;
 
   const crossCompilerCache = config?.markdown?.crossCompilerCache ?? true;
 
   try {
     // TODO wrong but good enough for now (example: "build --watch")
-    if (crossCompilerCache && process.env.NODE_ENV === 'production') {
+    if (
+      crossCompilerCache &&
+      process.env.NODE_ENV === 'production' &&
+      !isSsgMd
+    ) {
       const compileResult = await compileWithCrossCompilerCache({
         source,
         filepath,
@@ -37,6 +47,7 @@ export default async function mdxLoader(
         pluginDriver,
         routeService,
         addDependency: this.addDependency,
+        isSsgMd,
       });
       callback(null, compileResult);
     }