跳到主要内容
版本:2.2.0

📦 plugin-client-redirects

用于生成客户端重定向的 Docusaurus 插件。

这个插件会在你的静态网站中写入额外的 HTML 页面,通过 JavaScript 将用户重定向到已有的 Docusaurus 页面。

仅生产环境

这个插件在开发过程中始终不工作,只在生产环境中启用,因为它会在构建输出上工作。

注意

如果可行,你最好用服务端重定向。

在用这个插件前,你应该确定你的托管商是否确实不提供此功能。

安装流程

npm install --save @docusaurus/plugin-client-redirects

配置

接受的字段:

选项类型默认值描述
fromExtensionsstring[][]重定向后从路径中去除的扩展名。
toExtensionsstring[][]重定向后添加到路径中的扩展名。
redirectsRedirectRule[][]重定向规则列表。
createRedirectsCreateRedirectsFnundefined用于创建重定向规则的回调。 Docusaurus 会用每一个它创建的路径来调用这个回调,然后用它的返回值来输出更多路径。
备注

插件也会读取 siteConfig.onDuplicateRoutes 配置,在有多个文件被输出到同一路径时调整日志等级。

类型

RedirectRule

type RedirectRule = {
to: string;
from: string | string[];
};
备注

"From" 和 "to" 的概念是这个插件的核心。 "From" 指你想要创建的路径,也就是会被写入的额外 HTML 文件;"to" 指你想要重定向到的路径,一般是 Docusaurus 已经知道的路径。

这就是为什么你可以对于同一个 "to" 有多个 "from":我们会创建多个 HTML 文件,它们全部重定向到同一个目标。 另一方面,一个 "from" 永远不会有多于一个 "to":写入的 HTML 文件必须有唯一确定的目标。

CreateRedirectsFn

// 参数 `path` 是一个 Docusaurus 已经创建的路径。 它可以
// 被看作是 "to",而你的返回值就是 "from"。 返回 falsy 的
// 值,就不会为当前路径创建任何重定向页面。
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

示例配置

这是一个示例配置:

docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (如果后者存在的话)
redirects: [
// /docs/oldDoc -> /docs/newDoc
{
to: '/docs/newDoc',
from: '/docs/oldDoc',
},
// 将多个旧路径重定向到新路径
{
to: '/docs/newDoc2',
from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
},
],
createRedirects(existingPath) {
if (existingPath.includes('/community')) {
// 将 /docs/team/X 重定向到 /community/X,/docs/support/X 重定向到 /community/X
return [
existingPath.replace('/community', '/docs/team'),
existingPath.replace('/community', '/docs/support'),
];
}
return undefined; // 返回 falsy 值,不创建重定向
},
},
],
],
};