使用remark-gfm时脚注未被正确解析转换为对应HTML标签问题求助

常见原因 #

• 版本不兼容：react-markdown和remark-gfm的版本没有对应适配，remark-gfm v2及以上版本依赖remark v14+，对应需要react-markdown v7及以上版本，低版本react-markdown内置的remark版本过低，无法正确解析新版remark-gfm的脚注逻辑
• 脚注语法不规范：脚注定义项存在缩进、与正文之间未保留空行，会被解析为普通文本或代码块
• 内容被转义：传入的markdown内容中的[^]符号被提前转义为HTML实体字符，无法被插件识别
• 插件配置错误：remark-gfm的脚注功能被手动关闭，或者存在其他remark/rehype插件拦截了脚注的解析逻辑

解决步骤 #

1. 匹配依赖版本
   首先确认package.json中的依赖版本符合要求，不符合的话执行升级命令：

# npm
npm install react-markdown@latest remark-gfm@latest
# yarn
yarn add react-markdown@latest remark-gfm@latest

2. 显式开启脚注配置
   在引入remark-gfm时显式声明开启脚注功能，避免默认配置不生效的问题：

import ReactMarkdown from "react-markdown";                                      
import remarkGfm from "remark-gfm";

// 组件调用时的配置
<ReactMarkdown 
  children={markdown_content_here} 
  remarkPlugins={[
    [remarkGfm, {
      footnotes: true // 显式开启脚注功能
    }]
  ]} 
/>

3. 校验输入内容

• 确认传入的markdown内容没有被HTML转义，[^1]、[^1]:等标识为原始文本
• 脚注定义项必须顶格书写，和正文内容之间保留至少一个空行

4. 排查插件冲突
   如果同时使用了其他remark/rehype插件，临时注释其他插件后测试脚注是否正常解析，排查是否存在插件冲突问题。

可用参考示例 #

import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'

const mdContent = `
测试文本1 [^1]
测试文本2 [^2]

[^1]: 这是第一条脚注内容
[^2]: 这是第二条脚注内容
`

export default function MarkdownRender() {
  return <ReactMarkdown remarkPlugins={[[remarkGfm, {footnotes: true}]]}>{mdContent}</ReactMarkdown>
}

内容的提问来源于stack exchange，提问作者yldm