Docusaurus中如何创建全局共享链接模板实现DRY文档管理？

核心方案：用JS/JSON文件集中定义链接，正确导入使用 #

方法1：使用JS文件管理链接 #

1. 在docs目录下创建links.js，集中定义所有内部链接：

export const DOC_LINKS = {
  intro: '/docs/intro',
  advancedSettings: '/docs/advanced/settings',
  videoTutorial: '/docs/tutorials/video-guide'
};

2. 在目标MDX文件中正确导入并使用：

// 注意相对路径要准确，若links.js和当前md文件同目录，用./links.js
import { DOC_LINKS } from './links.js';

请查看[用户手册简介]({DOC_LINKS.intro})，进阶操作可参考[高级设置指南]({DOC_LINKS.advancedSettings})。

方法2：使用JSON文件管理链接 #

1. 创建links.json文件：

{
  "intro": "/docs/intro",
  "videoTutorial": "/docs/tutorials/video-guide"
}

2. 在MDX文件中导入使用：

import DOC_LINKS from './links.json';

[视频教程]({DOC_LINKS.videoTutorial})会演示完整操作流程。

解决你遇到的两个问题 #

1. 模块找不到：

   • 检查导入路径是否正确：必须用相对路径（如./links.js），绝对路径会导致模块解析失败；
   • 确保文件名和扩展名完整，不要省略.js/.json。

2. 链接无法解析：

   • MDX中嵌入变量链接必须用{变量名}包裹，直接写[文本](DOC_LINKS.intro)会被当作普通字符串解析，正确写法是[文本]({DOC_LINKS.intro})。

进阶：适配站点BaseUrl #

如果你的站点配置了baseUrl，可以用Docusaurus内置的useBaseUrl确保链接正确：

import { DOC_LINKS } from './links.js';
import useBaseUrl from '@docusaurus/useBaseUrl';

这是[用户手册简介]({useBaseUrl(DOC_LINKS.intro)})。

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