react-router - 如何从 Docusuarus 页脚链接到非 Docusaurus 定义的路线？

Question

我的网站文档是使用 Docusaurus 构建的，我目前使用的是最新版本 2.0.0-alpha.61。

编译后的文档保存到 /docs我网站的目录，而我网站的其余大部分都是用 GatsbyJS 构建的。所以...如果你点击/docs/something您到达了 Docusaurus 构建的页面，但如果您点击 /contact或/about-us或者其他什么，您访问了使用 GatsbyJS 构建的页面。

我的docusaurus.config.js包含:

  baseUrl: "/docs/",
...
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: require.resolve("./sidebars/index.js"),
          showLastUpdateTime: true,
          routeBasePath: "",
        },
...

以便 Docusaurus 知道它位于/docs 中。

这是我的问题:在 Docusaurus 中创建的页面页脚中，我想链接到主页上的/contact 或/about-us 等。

docusaurus.config.js 的页 footer 分允许您拥有这样的链接:

{
    label: "Github",
    href: "https://github.com/my-org/my-repo",
},

或者这个:

{
    label: "Contributing",
    to: "/docs/contributing",
}

但是，如果你这样做:

{
    label: "About Us",
    href: "/about-us",
},

您收到一条错误消息，指出 /about-us不是有效的网址。错误状态 ValidationError: "footer.links[0].items[0].href" must be a valid uri 。大概这是因为/about-us没有以 https:// 开头。我想避免定义绝对 URL，因为我希望能够消除网站和文档的 qa、staging 和 prod 环境。

如果你这样做:

{
    label: "About Us",
    to: "/about-us",
},

然后它会编译，但 Docusaurus 的 React 路由器会在单击时拦截链接，将您定向到 https://my-site.com/about-us ，但显示 Docusaurus 404“未找到”页面，因为 Docusaurus 的 React 路由器不知道/about-us 页面。如果刷新页面，您会看到来自 GatsbyJS 的相应“关于我们”页面，因为如果您直接点击该页面，Docusaurus 的 React 路由器不会妨碍您。

从 Docusaurus 页脚链接到 GatsbyJS 生成的页面的最佳方式是什么？我“swizzled”页脚，并且现在已经在我的docusaurus.config.js的位置进行了黑客攻击。链接有一个附加属性:

{
    label: "About Us",
    to: "/about-us",
    localLink: true,
},

我有一个if我的混合组件中的子句创建了 <a>标记如果 localLink是真的，否则会创建一个普通的 React 链接组件，但我不太喜欢用 Docusaurus 的 alpha 版本来混合组件。

是否有更好的方法从页脚链接到我的主页？

非常感谢!

Answer 1

我尝试向 Docusaurus 发送 submit a PR 以启用 href: block 上的相对链接，但遭到拒绝，因为他们希望 href 在 URL 中具有完全限定的域名。

因此，如果遇到此问题，您可以采取以下几种选择:

---

选项 1:将 href: 目标设置为完整 URL。这需要预先知道您的文档最终将存放在哪里。例如，如果您有一个环境变量 MY_DOMAIN=https://my.company.com ，您可以将 docusaurus.config.js 更新为:

{
  label: 'About Us',
  href: process.env.MY_DOMAIN + '/about-us',
},

请注意，如果您遵循此路径，则无法一次生成工件并将其部署到多个环境(例如 QA、staging、prod 等)。环境变量中的 URL 是静态编译的。

---

选项 2:使用带有 <Link> 语法的 React to: 组件，但目标为 _blank :

{
  label: 'About Us',
  to: '/about-us',
  target: '_blank' 
},

此选项有两个缺点。如果 baseUrl 中的 docusaurus.config.js 不是 / ，那么 baseUrl 将被添加到你的目标 URL 之前。因此，如果 baseUrl='/docs/' ，则链接将打开 /docs/about-us 。此外，链接会在新窗口中打开。仅当 baseUrl='/' 并且您同意在新窗口中打开链接时，此选项才真正适用于您。

---

选项 3: 考虑您的 baseUrl ，并改为定位 _parent 。此选项与选项 2 类似，但有两个显着差异:

{
  label: 'About Us',
  to: '../about-us',
  target: '_parent' 
},

首先，您的 to: 目标通过将您的链接驱动到目录来占用您的 baseUrl 。所以，你最终会得到 /docs/../about-us (或 /about-us )。其次，您的目标 _parent 导致 React 路由器无法捕获您的点击，因此您的浏览器窗口实际上改变了位置。因此，点击“关于我们”链接实际上会导致进入 /about-us 页面。

如果您选择选项 3，当您编译 Docusaurus 站点时，您将遇到一个问题，您的 React 路由器将声称它无法解析 /about-us (它不能，但这并不重要，因为另一个站点会处理那条路)。但它会阻止您的网站编译。要覆盖该警告，请添加

  onBrokenLinks: "ignore",

到你的docusaurus.config.js。

---

选项 4:您始终可以 swizzle 组件(例如导航栏或页脚)，并将其编辑为您喜欢的内容，从而避免任何 docusaurus.config.js 验证问题。