Kubernetes网站内部链接检查工具使用指南

Kubernetes网站内部链接检查工具使用指南

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website

工具概述

在维护Kubernetes官方文档网站时，确保所有内部链接的有效性是文档质量保障的重要环节。本文将详细介绍如何使用内置工具检查Kubernetes文档中的失效链接，特别针对/content/en/目录下的英文文档。

工具原理

该链接检查工具基于htmltest实现，其工作流程如下：

1. 首先会构建网站，在本地仓库的/public目录生成HTML文件
2. 自动拉取专用的Docker镜像
3. 将本地仓库挂载到Docker容器中
4. 扫描/public目录下的HTML文件并输出失效链接报告

检查范围说明

包含的检查内容

• 所有/content/en/docs/目录下Markdown生成的HTML内容
• 所有内部链接（排除空链接和媒体文件链接）

排除的检查内容

• 导航栏、页脚等模板中的链接
• 页面部分的资源链接（CSS、JS等）
• 顶级页面及其子页面（如/training、/community等）
• 博客文章
• API参考文档
• 非英语本地化内容

环境准备

使用前需要安装以下依赖：

1. Docker环境
2. GNU make工具

使用步骤

1. 进入Kubernetes网站项目根目录
2. 执行命令：

   make container-internal-linkcheck
   

结果解读

工具输出的典型错误示例如下：

tasks/access-kubernetes-api/custom-resources/index.html
  hash does not exist --- tasks/access-kubernetes-api/custom-resources/index.html --> #preserving-unknown-fields

这表示在custom-resources.md文件中存在一个指向#preserving-unknown-fields的锚点链接失效。

修复建议

遇到链接失效问题时，建议采取以下步骤：

1. 定位到报错的Markdown文件
2. 使用文本编辑器搜索失效的链接目标（如#preserving-unknown-fields）
3. 检查该锚点是否被重命名或删除
4. 更新链接指向正确的锚点或内容
5. 重新运行检查工具验证修复效果

最佳实践

1. 在重命名文件或章节标题时，建议先运行链接检查
2. 移动文件位置时，注意更新所有引用该文件的链接
3. 定期运行检查工具，确保文档链接健康状态
4. 对于API参考等排除检查的内容，建议建立单独的检查机制

通过合理使用这个链接检查工具，可以有效提升Kubernetes文档的质量和用户体验。

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website