【GEO 优化】为文档图片补充 alt 属性，提升 img 标签语义性

一、背景

为提升 openEuler 文档在搜索引擎与生成式 AI 引擎中的可发现性与引用准确率（GEO），文档中心正在对发布到 docs.openeuler.org 的内容进行语义化优化。文档中的图片最终渲染为 <img> 标签，但 alt 属性普遍缺失或无意义，导致：

1. 搜索引擎与 AI 引擎无法理解图片内容：爬虫与生成式 AI（ChatGPT、DeepSeek 等）无法"看图"，alt 是其理解图片的唯一文本信号。alt 缺失直接导致图片搜索无法收录、AI 问答无法引用文档中的图示信息；
2. 无障碍缺失：屏幕阅读器（视障用户）遇到无 alt 的图片只能朗读文件名或直接跳过，图片承载的关键信息（架构图、操作截图）完全丢失；
3. 加载失败时无任何替代提示。

二、需要做什么

为 docs/zh/ 与 docs/en/ 下、所有被 _toc.yaml 引用并发布到文档中心的 .md 文件中的图片补充描述性 alt：

• Markdown 图片：![这里写 alt](./figures/xxx.png)，方括号内容即 alt；
• HTML 标签：<img> 上补充 alt 属性；
• 以下模式均视为 alt 缺失，需逐一修复：

![](./figures/RA-arch-1.png)                          ← 空 alt
![img](./figures/install-summary.png)                 ← 无意义占位
![image](./figures/topo.png)                          ← 无意义占位
![图1](./figures/deploy.png)                          ← 仅编号
![zh-cn_image_0000001372249333](./images/xxx.png)     ← 转换工具生成的文件名式占位
![xxx.png](./figures/xxx.png)                         ← 文件名回显
<img src="./figures/topo.png" width="500">            ← HTML 标签缺 alt 属性

• 仅补充 alt，不改动图片本身、图片路径及正文内容（内容勘误等请另行提交 PR）；
• 中英文文档的 alt 分别使用各自语言撰写；
• alt 由各仓 markdown 源文件直接透传为 <img> 的 alt 属性，无需网站侧工程改造。

三、alt 撰写规范

基本原则：

1. 描述图片传达的信息，让不看图的人也能获取关键内容；避免以 图片：、图：、截图： 开头（alt 本身已隐含"这是一张图片"）；
2. 简洁：中文一般不超过 30 字，复杂架构图可放宽至 50 字左右；
3. 结合上下文：说明该图在当前操作步骤或论述中的作用，而非泛泛描述画面；
4. 不堆砌关键词：alt 与页面主题自然相关即可，关键词堆砌会被搜索引擎判定为作弊。

分场景示例：

技术文档中的图片绝大多数承载信息（架构、操作、结果），都应撰写描述性 alt；仅分隔线、背景装饰类图片保留空 alt。

四、示例

Markdown 修改示例：

<!-- 修改前 -->
系统整体架构如下图所示。

![](./figures/RA-arch-1.png)

<!-- 修改后 -->
系统整体架构如下图所示。

![RAM-A 整体架构：管理面通过 RPC 接口连接内核态模块与远端存储后端](./figures/RA-arch-1.png)

HTML 标签修改示例：

<!-- 修改前 -->
<img src="./figures/topo.png" width="500">

<!-- 修改后 -->
<img src="./figures/topo.png" width="500" alt="集群组网拓扑：三个计算节点通过交换机与存储节点互联">

五、注意事项

1. alt 内容与图片下方的图注（如有）语义一致即可，不必逐字重复；图注渲染在 <img> 标签外部，搜索引擎与屏幕阅读器无法将其与图片关联，因此不能用图注替代 alt；
2. 命令输出类截图若正文已提供可复制的命令或代码块，alt 概括其展示目的即可，不必复述全部输出；
3. 历史图片若无法判断内容，结合上下文概括描述；
4. 修改时注意不要破坏 markdown 图片语法（方括号、圆括号需配对，图片路径保持不变）；
5. 同一仓库多版本目录（如 docs/zh/24.03_LTS_SP2/、docs/zh/master/）中的图片请一并处理。

如本仓库文档不涉及图片请忽略此issue，如有疑问欢迎在本 issue 下讨论。感谢配合！