用途:处理 Elastic Docs V3 中页面移动、重命名、删除或结构调整后产生的 URL 失效问题,在重定向文件中维护规则。触发场景包括 .md 文件被移动、重命名或删除,用户要求创建重定向,或结构调整影响已发布 URL。
主要能力:支持简单重定向(默认保留锚点)、用 ! 或 anchors: '!' 去除全部锚点、锚点映射(可把某锚点置空以丢弃)、跨仓库重定向(repo-name://path 语法)、以及用 many: 处理旧页面内容拆分到多个新页面的复杂情况,可为不同锚点指定不同目标,并用 {} 作为兜底匹配。
使用方式:重定向配置在内容集 docset.yml 或 _docset.yml 同级的 redirects.yml 或 _redirects.yml 中,路径均相对该文件位置,若不存在需创建。步骤为:找到重定向文件;确定旧路径与新路径;选择重定向类型;在 redirects 顶层键下添加条目;检索并更新仓库中指向旧路径的内部链接、跨仓库链接和 toctree 条目;最后汇总所做改动。可用 docs-builder diff validate 在本地验证,该验证也会在拉取请求中自动运行。
适用场景:Elastic Docs V3 内容集内的页面迁移与重构。限制:重定向仅在 Elastic Docs V3 内容集内有效,不能指向外部 URL;仅同页锚点重命名不应新增重定向条目,而应更新仍指向旧锚点的内部链接。建议始终用单引号包裹 YAML 路径,条目按旧路径字母排序,删除页面必须添加重定向,批量移动需逐页添加,不确定时宁可添加。