From f2f95fbb3807fde1c9b1b4fef2ed999051cede85 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 18:43:05 +0000 Subject: [PATCH 1/7] Chore: Fix all broken links outlined in issue description Signed-off-by: thisisobate --- analyses/2023/etcd/etcd-analysis.md | 4 ++-- analyses/2025/knative/issues.md | 4 ++-- docs/analysis/templates/analysis.md | 8 ++++---- docs/index.md | 4 ++-- docs/repo-setup.md | 4 ++-- docs/website-guidelines-checklist.md | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/analyses/2023/etcd/etcd-analysis.md b/analyses/2023/etcd/etcd-analysis.md index a9d7818..15d4e71 100644 --- a/analyses/2023/etcd/etcd-analysis.md +++ b/analyses/2023/etcd/etcd-analysis.md @@ -55,7 +55,7 @@ Netlify platform. The site's code is stored on the etcd GitHub repo. **Out of scope:** -- Other etcd repos: https://github.com/etcd-io/* +- Other etcd repos: https://github.com/etcd-io/ ## How this document is organized @@ -299,7 +299,7 @@ The website has a Those maintainer **responsible for approving** documentation PRs are listed as "approvers". -The website repo [README](../../README.md) is out of date. For example, +The website repo [README](https://github.com/etcd-io/website/blob/main/README.md) is out of date. For example, instructions for building the website state that the local build starts the server on `localhost:8888`. It's actually `localhost:1313`. diff --git a/analyses/2025/knative/issues.md b/analyses/2025/knative/issues.md index c3314a1..3e74e1a 100644 --- a/analyses/2025/knative/issues.md +++ b/analyses/2025/knative/issues.md @@ -196,7 +196,7 @@ here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. Related material in the current doc: -- https://github.com/knative/install +- https://knative.dev/docs/install/ Suggested changes: @@ -665,7 +665,7 @@ start by looking at the [mkdocs config file]. https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date [Install Knative using quickstart]: https://knative.dev/docs/install/quickstart-install/ -[Installing Knative]: https://github.com/knative/install +[Installing Knative]: https://knative.dev/docs/install/ [Installing the Knative CLI]: https://knative.dev/docs/client/install-kn/ [Knative Broker for Apache Kafka]: https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index e6103fa..cf539c2 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -104,7 +104,7 @@ The accompanying [implementation] document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues] and entered as GitHub [project-doc-website]/issues. +into a series of issues and entered on GitHub `PROJECT-DOC-WEBSITE/issues`. ### How to use this document @@ -115,9 +115,9 @@ Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation](./?TODO=ADD-URL) -- [Contributor documentation](./?TODO=ADD-URL) -- [Website and documentation infrastructure](./?TODO=ADD-URL) +- [Project documentation](#project-documentation) +- [Contributor documentation](#contributor-documentation) +- [Website and documentation infrastructure](#website-and-infrastructure) Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria] specification. diff --git a/docs/index.md b/docs/index.md index 6d837e3..4fca64e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,8 +52,8 @@ Consultants and volunteers also contribute to CNCF TechDocs efforts. ## Licenses -- Documentation: [CC-BY-4.0](LICENSE) -- Code: [Apache-2.0](LICENSE-CODE) +- Documentation: [CC-BY-4.0](https://github.com/cncf/techdocs/blob/main/LICENSE) +- Code: [Apache-2.0](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE) [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours diff --git a/docs/repo-setup.md b/docs/repo-setup.md index bf7003c..c6bb6f3 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -39,10 +39,10 @@ For documentation this means you must: ```markdown # License - $PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE). + $PROJECT_NAME is licensed under an [Apache 2.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE). The #PROJECT_NAME documentation is licensed under a - [CC-BY-4.0 license](./LICENSE-docs). + [CC-BY-4.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE). ``` 2. Add both the CC-BY-4.0 `LICENSE-docs` and Apache 2.0 `LICENSE` files to the diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index f4ba814..9c7d425 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -5,7 +5,7 @@ title: Website guidelines & checklist # Website guidelines & checklist Per the -[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/main/website-guidelines.md), +[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/main/policies-guidance/website-guidelines.md), the following should be present:
_Note_, not all of these are applicable to all projects From 6ac866b88f06ba7741bf2b6a19bc6ddea9215814 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 18:46:54 +0000 Subject: [PATCH 2/7] chore: format files Signed-off-by: thisisobate --- analyses/2023/etcd/etcd-analysis.md | 7 ++++--- docs/repo-setup.md | 3 ++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/analyses/2023/etcd/etcd-analysis.md b/analyses/2023/etcd/etcd-analysis.md index 15d4e71..46fdf2a 100644 --- a/analyses/2023/etcd/etcd-analysis.md +++ b/analyses/2023/etcd/etcd-analysis.md @@ -299,9 +299,10 @@ The website has a Those maintainer **responsible for approving** documentation PRs are listed as "approvers". -The website repo [README](https://github.com/etcd-io/website/blob/main/README.md) is out of date. For example, -instructions for building the website state that the local build starts the -server on `localhost:8888`. It's actually `localhost:1313`. +The website repo +[README](https://github.com/etcd-io/website/blob/main/README.md) is out of date. +For example, instructions for building the website state that the local build +starts the server on `localhost:8888`. It's actually `localhost:1313`. ### Inclusive language diff --git a/docs/repo-setup.md b/docs/repo-setup.md index c6bb6f3..670bc10 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -39,7 +39,8 @@ For documentation this means you must: ```markdown # License - $PROJECT_NAME is licensed under an [Apache 2.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE). + $PROJECT_NAME is licensed under an + [Apache 2.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE-CODE). The #PROJECT_NAME documentation is licensed under a [CC-BY-4.0 license](https://github.com/cncf/techdocs/blob/main/LICENSE). From 4a3e15fb48333472cab29740b8fdb2755db10d20 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 18:55:12 +0000 Subject: [PATCH 3/7] chore: fix markdown error Signed-off-by: thisisobate --- docs/analysis/templates/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index cf539c2..3b70f3c 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -550,8 +550,8 @@ The numeric rating values used in this document are as follows [criteria]: ../criteria.md [implementation]: ./implementation.md [issues list]: ./issues-list.md -[project-doc-website]: ./?_PROJECT-DOC-URL_ -[project-website]: ./?_PROJECT-WEBSITE_ +[project-doc-website]: _PROJECT-DOC-URL_ +[project-website]: _PROJECT-WEBSITE_ [Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website guidelines]: ../../website-guidelines-checklist.md From f6d408699d69c5f97cbd0c33cd0d8414e4dbcfd2 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 19:09:37 +0000 Subject: [PATCH 4/7] chore: fix markdown error Signed-off-by: thisisobate --- docs/analysis/templates/analysis.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 3b70f3c..7cce334 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -547,11 +547,12 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -[criteria]: ../criteria.md -[implementation]: ./implementation.md -[issues list]: ./issues-list.md -[project-doc-website]: _PROJECT-DOC-URL_ -[project-website]: _PROJECT-WEBSITE_ -[Rating (1-5)]: #rating-values -[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 -[website guidelines]: ../../website-guidelines-checklist.md +- Criteria: [criteria](../criteria.md) +- Implementation: [implementation](./implementation.md) +- Issues List: [issues list](./issues-list.md) +- Project-doc-url: _PROJECT-DOC-URL_ +- Project-website: _PROJECT-WEBSITE_ +- Rating: [Rating (1-5)](#rating-values) +- Rfc-spec: [rfc-spec](https://www.rfc-editor.org/rfc/rfc2119) +- Website guidelines: + [website guidelines](../../website-guidelines-checklist.md) From d7947133478491549abdd8e292849684a857d293 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 19:48:43 +0000 Subject: [PATCH 5/7] chore: fix markdown error again Signed-off-by: thisisobate --- docs/analysis/templates/analysis.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index 7cce334..f37e7b7 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -547,12 +547,10 @@ The numeric rating values used in this document are as follows 4. Meets or exceeds standards 5. Exemplary -- Criteria: [criteria](../criteria.md) -- Implementation: [implementation](./implementation.md) -- Issues List: [issues list](./issues-list.md) -- Project-doc-url: _PROJECT-DOC-URL_ -- Project-website: _PROJECT-WEBSITE_ -- Rating: [Rating (1-5)](#rating-values) -- Rfc-spec: [rfc-spec](https://www.rfc-editor.org/rfc/rfc2119) -- Website guidelines: - [website guidelines](../../website-guidelines-checklist.md) +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-website]: _PROJECT-WEBSITE_ +[Rating (1-5)]: #rating-values +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 +[website guidelines]: ../../website-guidelines-checklist.md From bcbdaacb0c1bcb29f23b9bd6a2a50a6ef970938c Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 19:59:40 +0000 Subject: [PATCH 6/7] chore: fix link checker in CI Signed-off-by: thisisobate --- .htmltest.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.htmltest.yml b/.htmltest.yml index 84e17fd..ea46cd5 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -7,6 +7,8 @@ IgnoreInternalURLs: # list of paths IgnoreURLs: # list of regexes of URLs or path to be ignored - ^https?://localhost - \?no-link-check + - _PROJECT-WEBSITE_ + - _PROJECT-DOC-URL_ # FIXME: temporary ignore rules - assistance\.md - LICENSE From edffc65aa1f2094bdcc1bdf4b4509f5643d04537 Mon Sep 17 00:00:00 2001 From: thisisobate Date: Tue, 17 Mar 2026 22:38:33 +0000 Subject: [PATCH 7/7] chore: add backsticks to link Signed-off-by: thisisobate --- analyses/2023/etcd/etcd-analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/2023/etcd/etcd-analysis.md b/analyses/2023/etcd/etcd-analysis.md index 46fdf2a..f8a0614 100644 --- a/analyses/2023/etcd/etcd-analysis.md +++ b/analyses/2023/etcd/etcd-analysis.md @@ -55,7 +55,7 @@ Netlify platform. The site's code is stored on the etcd GitHub repo. **Out of scope:** -- Other etcd repos: https://github.com/etcd-io/ +- Other etcd repos: `https://github.com/etcd-io/*` ## How this document is organized