# PR #43546 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Docs] Fix the duplicate doc icon issue
- 合并时间：2026-05-28 00:09
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/43546

---

# 执行摘要

- 一句话：修复文档生成时重复 GitHub 图标问题
- 推荐动作：可以快速合入。无需精读，但可作为学习 MkDocs 预处理顺序影响的好例子。

# 功能与动机

在 Troubleshooting 页面中，`Failed to infer device type` 部分的 `the code` 链接显示了两个重复的 GitHub 图标。经排查，是由于 `url_schemes.py` 中先处理相对文件链接生成了 GitHub URL，随后 GitHub 链接正则又匹配到该 URL 并再次添加图标。

# 实现拆解

1. 在 `docs/mkdocs/hooks/url_schemes.py` 的 `_process_links` 函数中，将原本先调用 `relative_link.sub(replace_relative_link, markdown)` 再调用 `github_link.sub(replace_github_link, markdown)` 的顺序交换，即先处理 GitHub 链接，再处理相对文件链接。
2. 同时第二笔 commit 还原了第一笔中对 `REPO` 正则的修改（该变更涉及另一行改动，非核心修复），最终仅保留顺序调整。

关键文件：
- `docs/mkdocs/hooks/url_schemes.py`（模块 文档构建；类别 source；类型 core-logic）: 唯一修改文件，调换了两个 preprocessor 的执行顺序以修复重复图标问题。

关键符号：未识别

## 关键源码片段

### `docs/mkdocs/hooks/url_schemes.py`

唯一修改文件，调换了两个 preprocessor 的执行顺序以修复重复图标问题。

```python
# 变更前：先处理相对链接，后处理 GitHub 链接
# 这会导致相对链接生成的 GitHub URL 被再次匹配，出现重复图标
markdown = relative_link.sub(replace_relative_link, markdown)
markdown = github_link.sub(replace_github_link, markdown)

# 变更后：先处理 GitHub 链接，后处理相对链接
# 相对链接生成的 GitHub URL 不会再被第二次处理
markdown = github_link.sub(replace_github_link, markdown)
markdown = relative_link.sub(replace_relative_link, markdown)

```

# 评论区精华

该 PR 审核简单，只有 hmellor 批准，没有 review 评论。gemini-code-assist 自动总结指出变更内容：REPO 正则限制性增强（后被还原）和 reorder 操作。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。仅交换了两个正则替换的顺序，不影响其他逻辑。测试重建文档后确认图标显示正常。
- 影响：仅影响 MkDocs 构建的文档中涉及同时包含相对文件链接和 GitHub 链接的页面。使图标显示正确，不会有重复图标。
- 风险标记：低风险变更

# 关联脉络

- 暂无明显关联 PR