Docusaurus带.md后缀的Markdown文件链接失效,需兼容本地编辑器
Docusaurus兼容带.md后缀的Markdown链接解决方案
最优方案:自定义Remark插件自动转换链接后缀
无需修改原Markdown文件,通过Docusaurus的Remark插件在构建阶段自动移除相对链接的.md后缀,同时保留本地编辑器的兼容性:
- 安装依赖:
npm install unist-util-visit --save-dev
- 修改项目根目录的
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); } }); }, ], }, }, ], ],
- 重启Docusaurus开发服务,此时带
.md后缀的相对链接(如[Name](./File2.md))会被自动转换为Docusaurus可识别的无后缀路径,本地Markdown编辑器打开时链接依然正常跳转。
备选方案:使用Markdown参考链接拆分定义
如果不想配置插件,可通过参考链接拆分路径定义,兼顾两边需求:
<!-- 正文使用参考链接 --> [查看File2](file2-link) <!-- 文档末尾定义参考链接(本地编辑器识别带.md的路径) --> [file2-link]: ./File2.md "File2文档"
注:该方案需要手动调整所有链接,适合文档数量较少的场景。
内容的提问来源于stack exchange,提问作者Rishi
相关产品推荐
相关产品推荐

