👀原来是这样的！！在Markdown嵌套React组件markdown 中插入 React 组件，有两种方式，第一种是

站长

2024年10月06日 18:49 · 阅读数 22

前言

上篇文章分享了如何将 markdown 渲染到页面上，这篇文章分享将 markdown 中的代码块变成真正的 React 组件

markdown 中插入 React 组件，有两种方式，第一种是代码块：

## 这是第一个代码块
```ts
import React from 'react';

const Demo1 = ()=>{
  return <div>Demo1</div>
}

export default Demo1
``

第二种是 code 标签：

<code src="./FooCompo.tsx"></code>

这种情况适用于代码块中的代码过于复杂，单独提取到一个 tsx 文件中，会有更好的体验

处理代码块

思路：

将代码块中的代码提取出来，生成一个 tsx 文件。

上篇文章提到，在 vite 插件中，会将 markdown 文件转换成 js 文件。我们将提取出来的 tsx 文件再 import 进来，插入到原先 React 代码块的位置，就可以了

思路分成两步：

替换代码块，生成 tsx 文件，将代码块替换成 React 组件标签
将生成的 tsx 文件中 React 组件， import 进来

第一步

需要写一个 rehype 插件来实现。创建`switchCode.ts`文件：

import { visit } from "unist-util-visit";

type ElementType = {
  tagName: string;
  properties: Record<string, string>;
  children?: (ElementType & { value: string })[];
};

export type SwitchCodeOptionsType = Partial<ElementType> & {
  handleCode?: (
    index: number,
    node: ElementType & { children: ElementType[] }
  ) => Partial<ElementType> | null;
};

const switchCode = (options: SwitchCodeOptionsType) => {
  let index = 0;
  return () => {
    const {
      tagName = "code",
      properties = {},
      children = [],
      handleCode = () => ({ tagName: "code", properties: {} }),
    } = options;

    return (tree: import("unist").Node) => {
      visit(tree, "element", (node: any) => {
        if (node.tagName == "code" && node.children.length > 0) {
          const res = handleCode(index++, node);
          
          if(!res) return;
          
          const assignedOptions = {
            tagName,
            properties,
            children,
            ...res,
          };

          node.tagName = assignedOptions.tagName;

          node.properties = {
            ...node.properties,
            ...assignedOptions.properties,
          };

          node.children = assignedOptions.children || [];
        }
      });
    };
  };
};

export default switchCode;

switchCode 的目的是在遍历文档语法树时，找到 code 标签，并允许用户通过 handleCode 函数自定义对这些 code 标签的处理。返回的函数可以直接作为处理 Markdown 或 HTML 的插件，进行进一步的代码转化或渲染定制。

如果不想用 handleCode 函数，也可以直接传入想要替换的 tagName 或者 properties。

详细解读：

这个函数接收一个 SwitchCodeOptionsType 类型的参数，并返回一个函数，该函数会接收一个语法树（tree）并遍历其中的 code 标签元素。
使用了 unist-util-visit 库中的 visit 函数，来遍历语法树中所有 tagName 为 "element" 的节点。
每当发现一个 code 元素且其 children 数组非空时，它会：
调用 handleCode，并传递当前索引和节点。
返回的结果（res）会与传入的默认选项（tagName、properties、children）合并，用于替换原来的节点属性。
替换后的属性会更新当前节点的 tagName、properties 和 children。
如果用户没有提供 handleCode，默认行为是返回一个包含 code 标签和空属性的对象。通过这个默认函数，可以确保代码在没有自定义处理逻辑的情况下也能正常工作。

想要替换成什么标签，需要调用方决定

将插件嵌入到 markdown 处理流程：

const markdown2html = (
  code: string,
  options: {
    codeBlock: SwitchCodeOptionsType;
  }
) => {
  const { codeBlock } = options;
  return (
    remark()
      .use(remarkGfm)
      .use(remarkRehype, { allowDangerousHtml: true })
      .use(rehypeRaw)
      .use(switchCode(codeBlock)) // 接收传入的插件配置项
      .use(rehypeStringify, {
        allowDangerousHtml: true,
      })
      .process(code)
  );
};

在 vite 插件中，传入具体的配置项：

import { TempPath } from "../config";

const firstCharUpperCase = (str: string) => {
  return str.substring(0, 1).toUpperCase() + str.substring(1).toLowerCase();
};

const handleTagName = (tagName: string) => {
  return tagName.toLowerCase();
};

const switchTagName = (tagNames: string[], code: string) => {
  code = code.replace(
    new RegExp(`${tagNames.map((item) => item.toLowerCase()).join("|")}`, "g"),
    (match: string) => {
      return firstCharUpperCase(match);
    }
  );

  return code;
};

const VitePluginMarkdown = (): Plugin => {
  return {
    name: "vite-plugin-markdown",
    async transform(code, id) {
      if (id.endsWith(".md")) {
        
        ...
        
        const htmlFile = await markdown2html(code, {
          // 传入配置项
          codeBlock: {
            handleCode(index, node) {
              const mdName = path.basename(id);
              const filename = handleTagName(
                `${mdName.replace(".md", "")}_demo_${index}`
              );
              const filePath = path.resolve(TempPath, "./" + filename + ".tsx");
              fs.writeFileSync(filePath, node.children[0].value, "utf-8");

              return {
                tagName: filename,
                children: [],
              };
            },
          },
        });

        ...
      }
    },
  };
};

export default VitePluginMarkdown;

在调用 markdown2html 时，传入了配置项。handleCode 主要的操作：

获取 Markdown 文件名 mdName，并生成一个唯一的组件名称（如 filename_demo_0）。
将代码块的内容写入临时的 TypeScript 文件 (filename_demo_0.tsx)，文件存放在 TempPath 路径下。
返回新的节点信息，将 code 标签替换为动态生成的组件标签（组件名 filename）。
同时清空 children 数组，因为代码块的内容已经被保存到生成的 .tsx 文件中，不再需要作为节点内容。
使用 switchTagName 将代码中的组件名称转换为首字母大写的形式，确保符合 React 组件的命名规范。

临时文件夹，默认放在node_module/.temp中

config.ts:

import path from "path";
import checkDirIsExist from "./util/checkDirIsExist";

export const TempPath = path.resolve(__dirname, "../node_modules/.temp");

checkDirIsExist(TempPath); // 检查路径是否存在，如果不存在，就创建

第二步

在上面已经将代码块替换成了组件标签，接下来要做的就是给组件标签添加 import，不然后面的 esbuild 编译会将组件标签当成普通的 html 标签。


const dynamicComponents: Record<string, string> = {
  showcode: "@src/components/ShowCode",
};

const htmlFile = await markdown2html(code, {
  codeBlock: {
    handleCode(index, node) {
      ...

      dynamicComponents[filename] = filePath;

      ...
    },
  },
});

let _code = `
    import React from 'react';
    ${Object.entries(dynamicComponents)
      .map(([name, path]) => {
        return `import ${firstCharUpperCase(name)} from '${path}'`;
      })
      .join(";\n")}

    export default function(){
      return <>
        ${htmlFile.value}
      </>
    }
`;

解释：

在 rehype 插件中，将生成的组件名称和对应的文件路径存储在 dynamicComponents 对象中，用于动态导入。
在组装字符串时，动态导入之前提取的代码块生成的组件。这样 esbuild 就认识替换后的 React 标签了

完整代码：

import { Plugin } from "vite";
import markdown2html from "../markdown/markdown2html";
import esbuildTransform from "../esbuild/esbuildTransform";
import path from "path";
import fs from "fs";
import { TempPath } from "../config";
const firstCharUpperCase = (str: string) => {
  return str.substring(0, 1).toUpperCase() + str.substring(1).toLowerCase();
};

const handleTagName = (tagName: string) => {
  return tagName.toLowerCase();
};

const switchTagName = (tagNames: string[], code: string) => {
  code = code.replace(
    new RegExp(`${tagNames.map((item) => item.toLowerCase()).join("|")}`, "g"),
    (match: string) => {
      return firstCharUpperCase(match);
    }
  );

  return code;
};

const VitePluginMarkdown = (): Plugin => {
  return {
    name: "vite-plugin-markdown",
    async transform(code, id) {
      if (id.endsWith(".md")) {
        const dynamicComponents: Record<string, string> = {
          showcode: "@src/components/ShowCode",
        };

        const htmlFile = await markdown2html(code, {
          codeBlock: {
            handleCode(index, node) {
              const mdName = path.basename(id);
              const filename = handleTagName(
                `${mdName.replace(".md", "")}_demo_${index}`
              );
              const filePath = path.resolve(TempPath, "./" + filename + ".tsx");
              fs.writeFileSync(filePath, node.children[0].value, "utf-8");
              dynamicComponents[filename] = filePath;

              return {
                tagName: filename,
                children: [],
              };
            },
          },
        });

        let _code = `
          import React from 'react';
          ${Object.entries(dynamicComponents)
            .map(([name, path]) => {
              return `import ${firstCharUpperCase(name)} from '${path}'`;
            })
            .join(";\n")}

          export default function(){
            return <>
              ${htmlFile.value}
            </>
          }
        `;

        _code = switchTagName(Object.keys(dynamicComponents), _code);

        const esbuildRes = await esbuildTransform(_code);

        return {
          code: esbuildRes.code,
        };
      }
    },
  };
};

export default VitePluginMarkdown;

标签名称需要特别处理，因为 rehype 处理得到的标签名称首字母都是小写的，而 React 组件标签又要求首字母一定要大写。

所以这里就做了约定，在 rehype 标签替换中，标签名称一律小写。而在 esbuild 编译之前，一律将标签名称替换成首字母大写，同时 import 进来的组件名称也是如此。

保存，刷新浏览器看看效果：

👀原来是这样的！！在Markdown嵌套React组件markdown 中插入 React 组件，有两种方式，第一种是

对比下 md 文件的内容：

# Foo

这是一个测试的markdown文件

## 这是第一个代码块
```ts
import React from 'react';

const Demo1 = ()=>{
  return <div>Demo1</div>
}

export default Demo1
``

没问题，很成功

处理 code 标签

## 这是第二个代码块

<code src="./FooCompo.tsx"/>

FooCompo.tsx是和 Foo.md 放在同一目录的文件：

👀原来是这样的！！在Markdown嵌套React组件markdown 中插入 React 组件，有两种方式，第一种是

处理 code 标签的思路和代码块的思路差不多，都是将标签替换成 React 组件的标签，然后在 vite 插件中 import 对应的 React 组件

不同的地方在于 code 标签对应的 React 组件已经创建好了，只要根据 src 属性找到对应组件引入进来就好

第一步

修改 rehype 插件：

visit(tree, "element", (node: any) => {
  if (node.tagName == "code") {
    ...
  }
});

删除了node.children.length > 0的判断逻辑，因为 code 标签内部可以没有内容。为了更通用的考虑，这样的判断逻辑应该放在调用端

修改 remark 流程：

const markdown2html = (
  code: string,
  options: {
    codeBlock: SwitchCodeOptionsType;
    codeTag: SwitchCodeOptionsType;
  }
) => {
  const {codeBlock, codeTag}  = options;

  return remark()
    .use(remarkGfm)
    .use(remarkRehype, { allowDangerousHtml: true })
    .use(rehypeRaw)
    .use(switchCode(codeBlock))
    .use(swicthCode(codeTag))
    .use(rehypeStringify, { allowDangerousHtml: true })
    .process(code);
}

添加了一个新的配置项 codeTag，用来处理 code 标签。每添加一个新功能，就要修改代码，并且codeBlock和codeTag两者都是必传，这样不够灵活，开发体验不佳

可以改改：

const markdown2html = (
  code: string,
  options: {
    codeBlock?: SwitchCodeOptionsType; // optional
    codeTag?: SwitchCodeOptionsType; // optional
  }
) => {
  
  let tempProcess = remark()
    .use(remarkGfm)
    .use(remarkRehype, { allowDangerousHtml: true })
    .use(rehypeRaw);

  
  Object.entries(options).forEach(([key,value])=>{
    value && (tempProcess = tempProcess.use(switchCode(value)))
  })
  
  return tempProcess
    .use(rehypeStringify, {
      allowDangerousHtml: true,
    })
    .process(code);
};

将codeBlock和codeTag改成了可选项，并且内部将静态添加的逻辑改成了动态的

第二步

修改 vite 插件：

const htmlFile = await markdown2html(code, {
          codeBlock: {
            handleCode(index, node) {
+++           if (node.children.length > 0) {
                const mdName = path.basename(id);
                ...
                return {
                  tagName: filename,
                  children: [],
                };
+++           }
+++         return null;
            },
          },
        });

首先，在codeBlock 中的 handleCode，添加 node 的判断条件

然后添加 codeTag 的处理逻辑：

const htmlFile = await markdown2html(code, {
  codeBlock: {
    ...
      },
  codeTag: {
    handleCode(index, node) {
      if (
        node.tagName == "code" &&
        node.properties.src &&
        node.properties.src.startsWith(".")
      ) {
        const mdName = path.basename(id);
        const filename = handleTagName(
              `${mdName.replace(".md", "")}_demo_tag_${index}`
        );
        const compoPath = path.resolve(
          path.dirname(id),
          node.properties.src
        );
        if(!fs.existsSync(compoPath)) return null;
                
        dynamicComponents[filename] = compoPath;

        return {
          tagName: filename,
        };
      }
      return null;
    },
  },
});

主要逻辑：

判断 code 的 tag 是否符合标准，目前只支持相对路径的引入
通过 md 文档的路径，和 tag 标签中的 src 路径，找到真实的组件路径compoPath
判断 compoPath 是否存在，如果不存在，就不对当前 code 做处理
保存 import 的信息
返回 React 组件标签名。这里的标签名是根据 md 文件名生成的，与引用的 React 组件真实名称无关，所以这里只支持默认导出（export default）

修改完毕，看看效果：

👀原来是这样的！！在Markdown嵌套React组件markdown 中插入 React 组件，有两种方式，第一种是

完美展示

完整代码

rehype 插件`switchCode.ts`:

import { visit } from "unist-util-visit";

type ElementType = {
  tagName: string;
  properties: Record<string, string>;
  children?: (ElementType & { value: string })[];
};

export type SwitchCodeOptionsType = Partial<ElementType> & {
  handleCode?: (
    index: number,
    node: ElementType & { children: ElementType[] }
  ) => Partial<ElementType> | null;
};

const switchCode = (options: SwitchCodeOptionsType) => {
  let index = 0;
  return () => {
    const {
      tagName = "code",
      properties = {},
      children = [],
      handleCode = () => ({ tagName: "code", properties: {} }),
    } = options;

    return (tree: import("unist").Node) => {
      visit(tree, "element", (node: any) => {
        if (node.tagName == "code" && node.children.length > 0) {
          const res = handleCode(index++, node);
          
          if(!res) return;
          
          const assignedOptions = {
            tagName,
            properties,
            children,
            ...res,
          };

          node.tagName = assignedOptions.tagName;

          node.properties = {
            ...node.properties,
            ...assignedOptions.properties,
          };

          node.children = assignedOptions.children || [];
        }
      });
    };
  };
};

export default switchCode;

处理 markdown 的流程代码：

import rehypeRaw from "rehype-raw";
import rehypeStringify from "rehype-stringify";
import { remark } from "remark";
import remarkGfm from "remark-gfm";
import remarkRehype from "remark-rehype";
import switchCode, { SwitchCodeOptionsType } from "./plugin/switchCode";

const markdown2html = (
  code: string,
  options: {
    codeBlock?: SwitchCodeOptionsType;
    codeTag?: SwitchCodeOptionsType;
  }
) => {
  let tempProcess = remark()
    .use(remarkGfm)
    .use(remarkRehype, { allowDangerousHtml: true })
    .use(rehypeRaw);

  Object.entries(options).forEach(([key, value]) => {
    value && (tempProcess = tempProcess.use(switchCode(value)));
  });

  return tempProcess
    .use(rehypeStringify, {
      allowDangerousHtml: true,
    })
    .process(code);
};

export default markdown2html;

vite 插件VitePluginMarkdown.ts:

import { Plugin } from "vite";
import markdown2html from "../markdown/markdown2html";
import esbuildTransform from "../esbuild/esbuildTransform";
import path from "path";
import fs from "fs";
import { TempPath } from "../config";
const firstCharUpperCase = (str: string) => {
  return str.substring(0, 1).toUpperCase() + str.substring(1).toLowerCase();
};

const handleTagName = (tagName: string) => {
  return tagName.toLowerCase();
};

const switchTagName = (tagNames: string[], code: string) => {
  code = code.replace(
    new RegExp(`${tagNames.map((item) => item.toLowerCase()).join("|")}`, "g"),
    (match: string) => {
      return firstCharUpperCase(match);
    }
  );

  return code;
};

const VitePluginMarkdown = (): Plugin => {
  return {
    name: "vite-plugin-markdown",
    async transform(code, id) {
      if (id.endsWith(".md")) {
        const dynamicComponents: Record<string, string> = {
          showcode: "@src/components/ShowCode",
        };

        const htmlFile = await markdown2html(code, {
          codeBlock: {
            handleCode(index, node) {
              if (node.children.length > 0) {
                const mdName = path.basename(id);
                const filename = handleTagName(
                  `${mdName.replace(".md", "")}_demo_${index}`
                );
                const filePath = path.resolve(
                  TempPath,
                  "./" + filename + ".tsx"
                );
                fs.writeFileSync(filePath, node.children[0].value, "utf-8");
                dynamicComponents[filename] = filePath;

                return {
                  tagName: filename,
                  children: [],
                };
              }
              return null;
            },
          },
          codeTag: {
            handleCode(index, node) {
              if (
                node.tagName == "code" &&
                node.properties.src &&
                node.properties.src.startsWith(".")
              ) {
                console.log(node);
                const mdName = path.basename(id);
                const filename = handleTagName(
                  `${mdName.replace(".md", "")}_demo_tag_${index}`
                );
                const compoPath = path.resolve(
                  path.dirname(id),
                  node.properties.src
                );

                if (!fs.existsSync(compoPath)) return null;

                dynamicComponents[filename] = compoPath;

                return {
                  tagName: filename,
                };
              }
              return null;
            },
          },
        });

        let _code = `
          import React from 'react';
          ${Object.entries(dynamicComponents)
            .map(([name, path]) => {
              return `import ${firstCharUpperCase(name)} from '${path}'`;
            })
            .join(";\n")}

          export default function(){
            return <>
              ${htmlFile.value}
            </>
          }
        `;

        _code = switchTagName(Object.keys(dynamicComponents), _code);

        const esbuildRes = await esbuildTransform(_code);

        return {
          code: esbuildRes.code,
        };
      }
    },
  };
};

export default VitePluginMarkdown;

项目地址：GitHub - zenoskongfu/markdown-doc

总结

这篇文章讲述了如何讲代码块变成 React 组件，并将其嵌入到 markdown 文档中，也是借用 rehype 插件和 vite 插件，代码不难，最后效果也不错

有一个问题：如果有些代码块不需要变成组件呢？只想展示代码呢，应该怎么做？还有，现在代码块和 code 标签处理方式有些割裂，其实两者的功能是相同，那处理方式能不能统一一下呢，

下篇文章来分享这些内容

转载自:https://juejin.cn/post/7418063388049588260