feat(plugin-llms): support mdFiles.remarkPlugins (#2516)

Author: SoonIter

packages/plugin-llms/src/normalizeMdFile.ts

@@ -7,7 +7,7 @@ import type { Root } from 'hast';
 import remarkMdx from 'remark-mdx';
 import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
-import { type Plugin, unified } from 'unified';
+import { type PluggableList, type Plugin, unified } from 'unified';
 import { SKIP, visit } from 'unist-util-visit';
 import type { VFile } from 'vfile';
 
@@ -48,8 +48,9 @@ function normalizeMdFile(
   base: string,
   mdxToMd: boolean,
   isMd: boolean,
+  remarkPlugins: PluggableList,
 ): Promise<VFile> {
-  return unified()
+  const compiler = unified()
     .use(remarkParse)
     .use(isMd ? noopPlugin : remarkMdx)
     .use(remarkFileCodeBlock, { filepath })
@@ -63,11 +64,13 @@ function normalizeMdFile(
       },
       __base: base,
     } satisfies Parameters<typeof remarkLink>[0])
-    .use(remarkStringify)
-    .process({
-      value: content,
-      path: filepath,
-    });
+    .use(remarkPlugins)
+    .use(remarkStringify);
+
+  return compiler.process({
+    value: content,
+    path: filepath,
+  });
 }
 
 export { normalizeMdFile };

packages/plugin-llms/src/plugin.ts

@@ -48,6 +48,7 @@ const rsbuildPluginLlms = ({
       },
       mdFiles = {
         mdxToMd: false,
+        remarkPlugins: [],
       },
       llmsFullTxt = {
         name: 'llms-full.txt',
@@ -149,8 +150,13 @@ const rsbuildPluginLlms = ({
                 filepath,
                 routeServiceRef.current!,
                 baseRef.current,
-                typeof mdFiles !== 'boolean' ? mdFiles?.mdxToMd : false,
+                typeof mdFiles !== 'boolean'
+                  ? (mdFiles?.mdxToMd ?? false)
+                  : false,
                 isMD,
+                typeof mdFiles !== 'boolean'
+                  ? (mdFiles?.remarkPlugins ?? [])
+                  : [],
               )
             ).toString();
           } catch (e) {
@@ -278,8 +284,15 @@ function organizeBySidebar(sidebar: Sidebar, pages: PageIndexInfo[]) {
   const orderList = flatSidebar(currSidebar);
 
   pages.sort((a, b) => {
-    const aIndex = orderList.findIndex(order => matchPath(order, a.routePath));
-    const bIndex = orderList.findIndex(order => matchPath(order, b.routePath));
+    let aIndex = orderList.findIndex(order => matchPath(order, a.routePath));
+    // if not in sidebar, put it to last
+    if (aIndex === -1) {
+      aIndex = Number.MAX_SAFE_INTEGER;
+    }
+    let bIndex = orderList.findIndex(order => matchPath(order, b.routePath));
+    if (bIndex === -1) {
+      bIndex = Number.MAX_SAFE_INTEGER;
+    }
     return aIndex - bIndex;
   });
 }
@@ -300,9 +313,6 @@ function getDefaultOptions(
         llmsFullTxt: {
           name: 'llms-full.txt',
         },
-        include({ page }) {
-          return page.lang === l;
-        },
       };
     }
     return {

packages/plugin-llms/src/types.ts

@@ -5,6 +5,7 @@ import type {
   RouteService,
   Sidebar,
 } from '@rspress/core';
+import type { PluggableList } from 'unified';
 
 /**
  * @default { name: "llms.txt" }
@@ -21,9 +22,15 @@ export interface LlmsTxt {
 
 export interface MdFiles {
   /**
+   * Whether to convert mdx to md.
    * @default false
    */
-  mdxToMd: boolean;
+  mdxToMd?: boolean;
+  /**
+   * Allow users to customize remarkPlugins and edit the content of generated md files.
+   * @default []
+   */
+  remarkPlugins?: PluggableList;
 }
 
 /**
@@ -48,8 +55,7 @@ export interface Options {
   llmsFullTxt?: false | LlmsFullTxt;
   /**
    * Whether to include some routes from llms.txt.
-   * @param context
-   * @default (context) => context.page.lang === config.lang
+   * @default undefined
    */
   include?: (context: { page: PageIndexInfo }) => boolean;
   /**

website/docs/en/plugin/official-plugins/llms.mdx

@@ -101,7 +101,8 @@ interface LlmsTxt {
 }
 
 interface MdFiles {
-  mdxToMd: boolean;
+  mdxToMd?: boolean;
+  remarkPlugins?: PluggableList;
 }
 
 interface LlmsFullTxt {
@@ -233,21 +234,29 @@ Rspress is a static site generator based on Rsbuild and it can generate llms.txt
 
 ```ts
 export interface MdFiles {
-  mdxToMd: boolean;
+  mdxToMd?: boolean;
+  remarkPlugins?: PluggableList;
 }
 ```
 
-- **Default**: `{ mdxToMd: false }`
+- **Default**: `{ mdxToMd: false, remarkPlugins: [] }`
 
-Whether to generate a markdown file for the corresponding route, when set to `false`, the markdown file for the corresponding route will not be generated.
+Whether to generate a markdown file for the corresponding route. When set to `false`, the markdown file for the corresponding route will not be generated.
 
 #### mdxToMd
 
-- Type: `boolean`
-- Default: `false`
+- **Type**: `boolean`
+- **Default**: `false`
 
 Whether to convert mdx content to md content. If enabled, mdx files will be converted to md files through a set of default strategies, but there may be some information loss.
 
+#### remarkPlugins
+
+- **Type**: `PluggableList`
+- **Default**: `[]`
+
+You can pass in custom remark plugins to modify the Markdown content.
+
 ### llmsFullTxt
 
 - **Type**: `false | LlmsFullTxt`
@@ -349,23 +358,24 @@ Text on the copy button, has higher priority than `textByLang`.
 - **Type**: `LlmsViewOptionsProps`
 
 ```ts
+type Option =
+  | {
+      title: string;
+      icon?: React.ReactNode;
+      onClick?: () => void;
+    }
+  | {
+      title: string;
+      href: string;
+      icon?: React.ReactNode;
+    }
+  | 'markdownLink'
+  | 'chatgpt'
+  | 'claude';
+
 interface LlmsViewOptionsProps
   extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  options?: Array<
-    | {
-        title: string;
-        icon?: React.ReactNode;
-        onClick?: () => void;
-      }
-    | {
-        title: string;
-        icon?: React.ReactNode;
-        href: string;
-      }
-    | 'markdownLink'
-    | 'chatgpt'
-    | 'claude'
-  >;
+  options?: Option[];
   textByLang?: Record<string, string>;
   text?: string;
 }
@@ -394,7 +404,7 @@ type Option =
 
 - **Default**: `['markdownLink', 'chatgpt', 'claude']`
 
-Customize the options in the dropdown menu, supports "Copy Markdown Link", [ChatGPT](https://chatgpt.com/) and [Claude](https://claude.ai) by default.
+Customize the options in the dropdown menu. By default, supports "Copy Markdown Link", [ChatGPT](https://chatgpt.com/) and [Claude](https://claude.ai).
 
 #### textByLang
 

website/docs/zh/plugin/official-plugins/llms.mdx

@@ -101,7 +101,8 @@ interface LlmsTxt {
 }
 
 interface MdFiles {
-  mdxToMd: boolean;
+  mdxToMd?: boolean;
+  remarkPlugins?: PluggableList;
 }
 
 interface LlmsFullTxt {
@@ -232,11 +233,12 @@ Rspress is a static site generator based on Rsbuild and it can generate llms.txt
 
 ```ts
 export interface MdFiles {
-  mdxToMd: boolean;
+  mdxToMd?: boolean;
+  remarkPlugins?: PluggableList;
 }
 ```
 
-- **默认值**: `{ mdxToMd: false }`
+- **默认值**: `{ mdxToMd: false, remarkPlugins: [] }`
 
 是否生成对应路由的 markdown 文件，当设置为 `false` 时，不会生成对应路由的 markdown 文件。
 
@@ -247,6 +249,13 @@ export interface MdFiles {
 
 是否将 mdx 内容转换为 md 内容，如果启用，会将 mdx 文件通过一组默认策略转换为 md 文件，但可能会有一定的信息丢失。
 
+#### remarkPlugins
+
+- **类型**: `PluggableList`
+- **默认值**: `[]`
+
+用户可以传入自定义的 remark plugins 来对 Markdown 的内容做一些修改。
+
 ### llmsFullTxt
 
 - **类型**: `false | LlmsFullTxt`