You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

Docusaurus带.md后缀的Markdown文件链接失效,需兼容本地编辑器

Docusaurus兼容带.md后缀的Markdown链接解决方案

最优方案:自定义Remark插件自动转换链接后缀

无需修改原Markdown文件,通过Docusaurus的Remark插件在构建阶段自动移除相对链接的.md后缀,同时保留本地编辑器的兼容性:

  1. 安装依赖:
npm install unist-util-visit --save-dev
  1. 修改项目根目录的docusaurus.config.js,在presets的docs配置中添加自定义Remark插件:
presets: [
  [
    '@docusaurus/preset-classic',
    {
      docs: {
        // 保留你原有的docs配置,比如sidebarPath、routeBasePath等
        remarkPlugins: [
          () => (tree) => {
            const visit = require('unist-util-visit');
            // 遍历所有Markdown链接节点
            visit(tree, 'link', (node) => {
              // 仅处理相对路径的.md文件链接,避免影响外部HTTP链接
              const isRelativeMdLink = 
                (node.url.startsWith('./') || node.url.startsWith('../')) && 
                node.url.endsWith('.md');
              if (isRelativeMdLink) {
                // 移除尾部的.md后缀
                node.url = node.url.slice(0, -3);
              }
            });
          },
        ],
      },
    },
  ],
],
  1. 重启Docusaurus开发服务,此时带.md后缀的相对链接(如[Name](./File2.md))会被自动转换为Docusaurus可识别的无后缀路径,本地Markdown编辑器打开时链接依然正常跳转。

备选方案:使用Markdown参考链接拆分定义

如果不想配置插件,可通过参考链接拆分路径定义,兼顾两边需求:

<!-- 正文使用参考链接 -->
[查看File2](file2-link)

<!-- 文档末尾定义参考链接(本地编辑器识别带.md的路径) -->
[file2-link]: ./File2.md "File2文档"

注:该方案需要手动调整所有链接,适合文档数量较少的场景。

内容的提问来源于stack exchange,提问作者Rishi

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.08.22 07:54:19