如何在Docusaurus所有文档页面显示‘Edit this page’链接？

问题背景 #

• 需求：在所有Docusaurus文档页面显示「Edit this page」编辑链接
• 操作：已按照官方指引在docusaurus.config.js的presets.classic.docs配置项中设置了editUrl属性
• 异常：页面可正常加载，但始终未出现「Edit this page」链接

项目配置信息 #

package.json（已编辑） #

{
  ...
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "serve": "docusaurus serve --build"
  },
  "dependencies": {
    ...
    "@docusaurus/core": "^2.0.0-beta.14",
    "@docusaurus/plugin-client-redirects": "^2.0.0-beta.14",
    "@docusaurus/preset-classic": "^2.0.0-beta.14",
    "@mdx-js/react": "^1.6.22",
    "clean": "^4.0.2",
    "clsx": "^1.1.1",
    "docusaurus-gtm-plugin": "0.0.2",
    "install": "^0.13.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "redux": "^4.0.5",
    "webpack": "^5.54.0",
    "webpack-cli": "^4.8.0"
  },
  ...
  "devDependencies": {
    "@babel/core": "^7.15.5"
  }
}

docusaurus.config.js #

module.exports = {
...
    plugins: [
        [
            require.resolve('docusaurus-gtm-plugin'),
            {
                id: 'TBD1', // GTM Container ID
            }
        ],
    ],
    presets: [
        [
            '@docusaurus/preset-classic',
            {
                docs: {
                    // It is recommended to set document id as docs home page (`docs/` path).
                    //homePageId: 'docIntro',  - deprecated
                    sidebarPath: require.resolve('./sidebars.js'),
                    // Please change this to your repo.
                    editUrl: 'https://gitlab......com/.../-/edit/master/',
                },
                blog: {
                    showReadingTime: true,
                    // Please change this to your repo.
                    editUrl: 'https://gitlab......com/.../-/edit/master/',
                },
                theme: {
                    customCss: require.resolve('./src/css/custom.css'),
                },
                sitemap: {
                    // cacheTime: 600 * 1000, // 600 sec - cache purge period
                    changefreq: 'weekly',
                    priority: 0.5,
                },
            },
        ],
    ]
};

示例截图 #

可能的原因及解决方案 #

1. 早期Beta版本存在bug #

你使用的是Docusaurus 2.0.0-beta.14，属于早期测试版本，editUrl配置不生效是已知的潜在问题之一。
解决方案：升级到最新稳定版，执行以下命令：

npm uninstall @docusaurus/core @docusaurus/preset-classic @docusaurus/plugin-client-redirects
npm install @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/plugin-client-redirects@latest

2. editUrl路径格式错误 #

GitLab的编辑链接需要指向文档所在目录的根路径，Docusaurus会自动将当前文档的相对路径拼接在editUrl后面。如果你的文档都存放在项目根目录的docs/文件夹下，当前配置的editUrl末尾缺少docs/，会导致拼接后的路径无效，部分场景下会隐藏编辑链接。
解决方案：修正editUrl为：

editUrl: 'https://gitlab......com/.../-/edit/master/docs/',

3. 自定义主题组件覆盖了默认逻辑 #

如果之前使用docusaurus swizzle命令修改过@docusaurus/theme-classic的DocPage或EditThisPage组件，可能不小心移除了编辑链接的显示逻辑。
解决方案：还原默认组件：

docusaurus swizzle @docusaurus/theme-classic DocPage --revert
docusaurus swizzle @docusaurus/theme-classic EditThisPage --revert

4. 单个文档禁用了编辑链接 #

检查文档的frontmatter（文件顶部的YAML配置），如果存在editUrl: false或hide_edit_button: true，会覆盖全局配置，隐藏编辑链接。
解决方案：移除对应文档frontmatter中的禁用配置。

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