From 8c1291f63393b6bfca33f8fc83ee2ae4eae66c45 Mon Sep 17 00:00:00 2001 From: Dominic Yin Date: Wed, 30 Sep 2020 14:53:08 +0800 Subject: [PATCH] Add zh trans of linkchecker --- .../linkchecker/README.md | 161 ++++++++++++++++++ content/zh/docs/home/_index.md | 2 +- 2 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 content/zh/docs/doc-contributor-tools/linkchecker/README.md diff --git a/content/zh/docs/doc-contributor-tools/linkchecker/README.md b/content/zh/docs/doc-contributor-tools/linkchecker/README.md new file mode 100644 index 0000000000..016907c2eb --- /dev/null +++ b/content/zh/docs/doc-contributor-tools/linkchecker/README.md @@ -0,0 +1,161 @@ + +# 内置链接检查工具 + + +你可以使用 [htmltest](https://github.com/wjdp/htmltest) 来检查 [`/content/en/`](https://git.k8s.io/website/content/en/) 下面的失效链接。这在重构章节内容、移动页面或者重命名文件或页眉时非常有用。 + + +## 工作原理 + + +`htmltest` 会扫描 kubernetes website 仓库构建生成的 HTML 文件。通过执行 `make` 命令进行了下列操作： + + +- 构建站点并输出 HTML 到本地 `kubernetes/website` 仓库下的 `/public` 目录中 +- 拉取 Docker 镜像 `wdjp/htmltest` +- 挂载本地 `kubernetes/website` 仓库到 Docker 容器中 +- 扫描 `/public` 目录下生成的文件并将遇到的失效链接通过命令行打印出来 + + +## 哪些链接不会检查 + + +该链接检查器扫描生成的 HTML 文件，而非原始的 Markdown. 该 htmltest 工具依赖于一个配置文件，[`.htmltest.yml`](https://git.k8s.io/website/.htmltest.yml)，来决定检查哪些内容。 + +该链接检查器扫描以下内容： + + +- 所有由 [`/content/en/docs`](https://git.k8s.io/website/content/en/docs/) 目录下的 Markdown 文件生成的内容，但不包括： + - 生成的 API 参考，例如 https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ +- 所有的内部链接，但不包括： + - 空白锚点 (`` 或 `[title](#)`) 以及空白目标地址 (`` 或 `[title]()`) + - 指向图片或其他媒体文件的内部链接 + + +该链接检查器不会扫描以下内容： + + +- 包含在顶部和侧边导航栏的链接，以及页脚链接或者页面的 `` 部分中的链接，例如 CSS 样式表、脚本以及元信息的链接。 +- 顶级页面及其子页面，例如： `/training`, `/community`, `/case-studies/adidas` +- 博客文章 +- API 参考文档，例如：https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/ +- 本地化内容 + + +## 先决条件以及安装说明 + + +必须安装： +* [Docker](https://docs.docker.com/get-docker/) +* [make](https://www.gnu.org/software/make/) + + +## 运行链接检查器 + + +运行链接检查器需要： + + +1. 进入本地 `kubernetes/website` 仓库的根目录下。 + +2. 执行如下命令： + + ``` + make docker-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 + hash does not exist --- tasks/access-kubernetes-api/custom-resources/index.html --> #preserving-unknown-fields +``` + + +这是一系列失效链接。该日志附带了每个页面下的失效链接。 + +在这部分输出中，包含失效链接的文件是 `tasks/access-kubernetes-api/custom-resources.md`. + +该工具给出了一个理由：`hash does not exist`. 在大部分情况下，你可以忽略这个。 + +目标链接是 `#preserving-unknown-fields`. + +修复这个问题的一种方式是： + + +1. 转到含有失效链接的 Markdown 文件。 +2. 使用文本编辑器全文搜索失效链接的 URL（通常使用 Ctrl+F 或 Command+F）`#preserving-unknown-fields`. +3. 修复该链接。对于一个失效的锚点（或者 _anchor_ ）链接，检查该主题是否已更名或者移除。 + + +运行 htmltest 来验证失效链接是否已修复。 \ No newline at end of file diff --git a/content/zh/docs/home/_index.md b/content/zh/docs/home/_index.md index d0e81e59d9..51ceacb973 100644 --- a/content/zh/docs/home/_index.md +++ b/content/zh/docs/home/_index.md @@ -13,7 +13,7 @@ menu: title: "文档" weight: 20 post: > -

通过概念、教程和参考文档了解如何使用 Kubernetes。你甚至可以帮助贡献文档！

+

通过概念、教程和参考文档了解如何使用 Kubernetes。你甚至可以帮助贡献文档！

# description: > # Kubernetes is an open source container orchestration engine for automating deployment, scaling, and management of containerized applications. The open source project is hosted by the Cloud Native Computing Foundation. description: >