# PR #23516 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[docs] add deprecation notice banner to legacy documentation site
- 合并时间：2026-04-23 11:17
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/23516

---

# 执行摘要
本 PR 为旧版文档网站（https://sgl-project.github.io）添加弃用通知横幅，通过 JavaScript 和 CSS 实现前端提示，并更新 CI 脚本以允许相关文件修改，属于常规文档维护工作，风险较低。

# 功能与动机
动机是引导用户从旧版文档网站迁移至新站点（https://docs.sglang.io），提升用户体验和维护效率。根据 PR body，添加横幅是为了明确弃用时间表，同时添加 `LEGACY_DOCS_ALLOWLIST` 以绕过 pre-commit 钩子，便于后续维护。

# 实现拆解

1. **新增 JavaScript 横幅逻辑**：在 `docs/_static/js/deprecation_banner.js` 中定义两个核心函数：
 - `buildNewDocsUrl()`：根据当前 URL 构建新文档站点链接。
 - `addDeprecationBanner()`：创建并插入横幅元素到页面顶部。
   ```javascript
   // 示例代码片段：构建新 URL 逻辑
   function buildNewDocsUrl() {
       var href = window.location.href;
       if (href === oldOrigin || href.indexOf(oldOrigin + "/") === 0) {
           return href.replace(oldOrigin, newOrigin); // 替换旧域名
       }
       return newOrigin + window.location.pathname + window.location.search + window.location.hash; // 基于路径构建
   }
   ```
2. **更新 Sphinx 配置**：修改 `docs/conf.py`，在 `html_js_files` 中添加 `js/deprecation_banner.js`，确保脚本被加载。
3. **添加 CSS 样式**：在 `docs/_static/css/custom_log.css` 中定义 `.sglang-docs-deprecation-banner` 类，设置背景色、边框和链接样式，确保横幅视觉突出。
4. **调整 CI 脚本**：修改 `scripts/ci/check_no_docs_changes.py`，添加 `LEGACY_DOCS_ALLOWLIST` 允许列表，包含横幅相关文件，避免 pre-commit 检查阻塞维护。

## 关键源码片段

### `docs/_static/js/deprecation_banner.js`

新增核心 JavaScript 逻辑，负责构建新文档 URL 和添加弃用横幅，是功能实现的关键。

```javascript
(function () {
    "use strict";

    var oldOrigin = "https://sgl-project.github.io";
    var newOrigin = "https://docs.sglang.io";

    function buildNewDocsUrl() {
        var href = window.location.href;
        // 如果当前 URL 匹配旧版站点，则替换为新站点 URL
        if (href === oldOrigin || href.indexOf(oldOrigin + "/") === 0) {
            return href.replace(oldOrigin, newOrigin);
        }
        // 否则，基于路径构建新 URL
        return newOrigin + window.location.pathname + window.location.search + window.location.hash;
    }

    function addDeprecationBanner() {
        // 避免重复添加横幅
        if (document.getElementById("sglang-docs-deprecation-banner")) {
            return;
        }

        var link = document.createElement("a");
        link.href = buildNewDocsUrl(); // 设置链接到新文档站点
        link.textContent = link.href;

        var banner = document.createElement("div");
        banner.id = "sglang-docs-deprecation-banner";
        banner.className = "sglang-docs-deprecation-banner";
        banner.setAttribute("role", "status");
        banner.setAttribute("aria-live", "polite");

        var prefix = document.createTextNode(
            "This legacy documentation site will be deprecated soon. Please use the new SGLang documentation at "
        );
        var suffix = document.createTextNode(".");

        banner.appendChild(prefix);
        banner.appendChild(link);
        banner.appendChild(suffix);

        // 将横幅插入到页面顶部
        document.body.insertBefore(banner, document.body.firstChild);
    }

    // 在 DOM 加载完成后添加横幅
    if (document.readyState === "loading") {
        document.addEventListener("DOMContentLoaded", addDeprecationBanner);
    } else {
        addDeprecationBanner();
    }
})();

```

# 评论区精华
Review 中无实质技术讨论，仅由 wisclmy0611 批准，表明变更被直接接受，无争议点。

# 风险与影响
- **技术风险**：横幅 JavaScript 依赖标准 DOM API，但可能在不支持某些特性的旧浏览器中失效；CSS 样式可能与现有文档主题冲突；CI 脚本变更若未充分测试，可能意外影响其他文档文件的检查流程。
- **影响范围**：用户访问旧版网站时将看到醒目提示，促进迁移；系统前端添加了轻量级交互元素；团队维护更便捷，允许特定文件绕过限制。

# 关联脉络
与近期文档相关 PR（如 #23437 添加重定向、#23486 更新模型文档）一脉相承，反映团队在文档迁移和维护上的持续投入，旨在提升文档质量和用户体验。