Fix all links in docs and analyses, and rename resources

- Fixes all paths that do not contain hashes (the link checker can't handle hashes) - Renames `resources` to `templates` and adjusts template files names, dropping the `-template` suffix - Ignores all `.tremor.rs` links since they are no longer valid -- they should have implemented redirects Signed-off-by: Patrice Chalin <[email protected]>
cncf · May 31, 2024 · 7cf041e · 7cf041e
1 parent 55eb6c9
commit 7cf041e
Show file tree

Hide file tree

Showing 27 changed files with 180 additions and 176 deletions.
diff --git a/.markdown-link-check.json b/.markdown-link-check.json
@@ -5,6 +5,12 @@
     },
     {
       "pattern": "^#"
+    },
+    {
+      "pattern": "^https://(www|docs).tremor.rs"
+    },
+    {
+      "pattern": "\\?no-link-check$"
     }
   ],
   "timeout": "3s",

diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md
@@ -26,8 +26,9 @@ The assessment is divided into three sections:
 - **Website:** branding, website structure, and maintainability
 
 Within each section you receive a rating on different criteria. The full
-definition of each criteria is defined in [the criteria](criteria.md). We
-recommend reading each criterion’s definition.
+definition of each criteria is defined in
+[the criteria](../docs/analysis/criteria.md). We recommend reading each
+criterion’s definition.
 
 ## Project documentation
 
@@ -44,8 +45,8 @@ recommend reading each criterion’s definition.
 
   - Documentation is feature complete!
   - A clear "About" or "What is Contour?" page is missing. It partially exists
-    on (Architecture)[https://projectcontour.io/docs/v1.13.1/architecture/] and
-    (Philosophy)[https://projectcontour.io/resources/philosophy/], but it's hard
+    on [Architecture](https://projectcontour.io/docs/v1.13.1/architecture) and
+    [Philosophy](https://projectcontour.io/resources/philosophy), but it's hard
     to navigate for a new user.
   - Task and concept documentation for individual features (configurations and
     deployment options) are both feature complete.

diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md
@@ -1,7 +1,6 @@
 # Notary Project Docs Assessment
 
-Date: 2021-07-31  
-Project: [Notary Project](https://github.com/notaryproject/)
+Date: 2021-07-31 Project: [Notary Project](https://github.com/notaryproject/)
 
 ## Introduction
 
@@ -29,7 +28,8 @@ This assessment is divided into two sections:
 - **Contributor documentation:** for new and existing contributors to the
   project
 
-Each section rates content based on different [criteria](criteria.md).
+Each section rates content based on different
+[criteria](../docs/analysis/criteria.md).
 
 Normally, a **website** section would also be a part of a document assessment,
 but as there isn't a website for the Notary Project yet, the website assessment
@@ -218,7 +218,7 @@ developed?
       https://github.com/notaryproject/notaryproject/issues/77)
 - [ ] Develop a maintenance plan for the documentation and its repository
 - [ ] Follow the
-      [CNCF website guidelines checklist](https://github.com/cncf/techdocs/blob/main/howto/website-guidelines-checklist.md)
+      [CNCF website guidelines checklist](../docs/website-guidelines-checklist.md)
       for other required elements
 
 _Note_:

diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md
@@ -27,8 +27,9 @@ The assessment is divided into three sections:
 - **Website:** branding, website structure, and maintainability
 
 Within each section you receive a rating on different criteria. The full
-definition of each criteria is defined in [the criteria](criteria.md). We
-recommend reading each criterion’s definition.
+definition of each criteria is defined in
+[Criteria](../docs/analysis/criteria.md). We recommend reading each criterion’s
+definition.
 
 ## Project documentation
 

diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md
@@ -24,7 +24,8 @@ The assessment is divided into three sections:
   project
 - **Website:** branding, website structure, and maintainability
 
-Each section rates content based on different [criteria](criteria.md).
+Each section rates content based on different
+[criteria](../docs/analysis/criteria.md).
 
 ## Project documentation
 

diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md
@@ -25,7 +25,8 @@ The assessment is divided into three sections:
   project
 - **Website:** branding, website structure, and maintainability
 
-Each section rates content based on different [criteria](criteria.md).
+Each section rates content based on different
+[criteria](../docs/analysis/criteria.md).
 
 ## Project documentation
 
@@ -154,7 +155,7 @@ Scale:
 
 - [This file](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh)
   is _very_ fragile, as it points to specific files at their
-  `https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh` and
+  <https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh> and
   seems to have the potential to make the site build succeed but with
   unpredictable results.
   - Consider implementing [Hugo Modules](https://gohugo.io/hugo-modules/) to
@@ -166,7 +167,7 @@ Scale:
 **Content creation processes**:
 
 - Put
-  [this information](https://github.com/fluxcd/website/blob/main/content/en/docs/contributing/docs/some-background.md#running-the-site-locally)
+  [this information](https://github.com/fluxcd/website/blob/main/content/en/docs/contributing/docs/some-background.md#running-the-site-locally?no-link-check)
   directly in the README.md of the website repository, because people are lazy.
   Kudos on trying to keep everything in one place, however!
 
@@ -200,7 +201,7 @@ Scale:
   [Community repository](https://github.com/fluxcd/community).
 - Project governance is [clearly documented](https://fluxcd.io/governance/). The
   community repository also includes information on
-  [Oversight](https://github.com/fluxcd/community/blob/main/OVERSIGHT.md),
+  [governance](https://github.com/fluxcd/community/blob/main/GOVERNANCE.md),
   [Community roles](https://github.com/fluxcd/community/blob/main/community-roles.md),
   and more.
 
@@ -242,7 +243,7 @@ Scale:
   fragility, particularly once the original code owners leave the organization.
 
 - Flux meets and exceeds the
-  [website requirements](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#minimal-website-requirements)
+  [website requirements](../docs/analysis/criteria.md#minimal-website-requirements)
   for its maturity level, save for the single sourcing requirement as noted
   above.
 

diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md
@@ -26,7 +26,8 @@ The assessment is divided into three sections:
   project
 - **Website:** branding, website structure, and maintainability
 
-Each section rates content based on different [criteria](criteria.md).
+Each section rates content based on different
+[criteria](../docs/analysis/criteria.md).
 
 ## Project documentation
 
@@ -56,7 +57,7 @@ are mentioned in brief, great work!
 **New user content**:
 
 We have a great, clearly labelled
-[Getting Started](https://gateway-api.sigs.k8s.io/v1alpha2/guides/getting-started/)
+[Getting Started](https://gateway-api.sigs.k8s.io/v1alpha2/guides/getting-started/?no-link-check)
 page, which is awesome! However, the getting started guide is fairly high level
 and doesn't answer some of the following questions:
 
@@ -97,7 +98,7 @@ as well as where to find them.
 - **Prepared a miro board:
   [https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)**
 
-  ![information_architecture](/images/gapi_info_arch.png)
+  ![information_architecture](../images/gapi_info_arch.png)
 
 - There are improvements we could make:
   - With the collection of guided, step-by-step instructions (tasks, hands-on

diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md
@@ -6,9 +6,8 @@ tags: porter
 # Notes
 
 meeting notes:
-https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw/edit?usp=sharing  
-website: https://getporter.org/  
-repos:
+https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw/edit?usp=sharing
+website: https://getporter.org/ repos:
 
 - https://github.com/getporter/porter (main site), site content is in docs/
   folder
@@ -45,7 +44,8 @@ The assessment is divided into three sections:
   project
 - **Website:** branding, website structure, and maintainability
 
-Each section rates content based on different [criteria](criteria.md).
+Each section rates content based on different
+[criteria](../docs/analysis/criteria.md).
 
 ## Project documentation
 

diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md
@@ -47,11 +47,11 @@ Backstage GitHub repo.
 - Website: https://backstage.io
 - Documentation: https://backstage.io/docs
 - Contributor documentation:
-  - https://github.com/backstage/backstage/README.md
-  - https://github.com/backstage/backstage/CONTRIBUTING.md
+  - https://github.com/backstage/backstage/blob/master/README.md
+  - https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md
 - Website configuration (Docusaurus):
-  https://github.com/backstage/backstage/microsite
-- Website content: https://github.com/backstage/backstage/docs
+  https://github.com/backstage/backstage/blob/master/microsite
+- Website content: https://github.com/backstage/backstage/blob/master/docs
 
 **Out of scope:**
 
@@ -581,19 +581,20 @@ Improve compliance in these areas:
 
 [backstage-backstage]: https://github.com/backstage/backstage
 [backstage-community]: https://backstage.io/community
-[backstage-contrib]: https://github.com/backstage/backstage/CONTRIBUTING.md
+[backstage-contrib]:
+  https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md
 [backstage-demo]:
   https://demo.backstage.io/catalog?filters%5Bkind%5D=component&filters%5Buser%5D=owned
-[backstage-discussion]: https://github.com/backstage/backstage/discussions
+[backstage-discussion]: https://discord.gg/backstage-687207715902193673
 [backstage-doc-contrib]:
-  https://backstage.io/docs/getting-started/getting-involved#write-documentation-or-improve-the-website
+  https://backstage.io/docs/contribute/getting-involved#write-documentation-or-improve-the-website
 [backstage-doc-deployment]: https://backstage.io/docs/deployment/
 [backstage-doc-getting-started]: https://backstage.io/docs/getting-started/
 [backstage-doc-rn]: https://backstage.io/docs/releases/v1.17.0
 [backstage-github-community]: https://github.com/backstage/community
 [backstage-github-project]: https://github.com/backstage
 [backstage-governance]:
-  https://github.com/backstage/backstage/blob/master/GOVERNANCE.md
+  https://github.com/backstage/community/blob/main/GOVERNANCE.md
 [backstage-insights-summary]: ./backstage-insights-summary.md
 [backstage-issues]: https://github.com/backstage/backstage/issues
 [backstage-io-overview-benefits]:
@@ -603,11 +604,9 @@ Improve compliance in these areas:
 [backstage-microsite]:
   https://github.com/backstage/backstage/tree/master/microsite
 [clotributor]: https://clotributor.dev/
-[cncf-doc-criteria]: ../criteria.md
-[cncf-doc-criteria]:
-  https://github.com/cncf/techdocs/blob/main/assessments/criteria.md
-[cncf-docs-howto]:
-  https://github.com/cncf/techdocs/blob/main/assessments/howto.md
+[cncf-doc-criteria]: ../../docs/analysis/criteria.md
+[cncf-doc-criteria]: ../../docs/analysis/criteria.md
+[cncf-docs-howto]: ../../docs/analysis/howto.md
 [cncf-maturity-stages]:
   https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations
 [cncf-servicedesk]: https://servicedesk.cncf.io
@@ -628,7 +627,7 @@ Improve compliance in these areas:
 
 [contrib-doc-rec]: #recommendations-contributor-documentation
 [contributor-doc]: #contributor-documentation
-[doc-survey]: ./Backstage%20doc%20survey.csv
+[doc-survey]: backstage-doc-survey.csv
 [implementation]: #implementation
 [info-arch-recommend]: #recommendations
 [proj-doc-comments]: #comments-project-documentation

diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md
@@ -58,20 +58,20 @@ Readers interested only in actionable improvements can skip to the
 [implementation recommendations](./in-toto-implementation.md). For more context,
 read the recommendations for each of the three areas of analysis:
 
-- [Project documentation recommendations](./assessments#recommendations)
+- [Project documentation recommendations](#recommendations-1)
 
-- [Contributor documentation recommendations](./assessments#recommendations-1)
+- [Contributor documentation recommendations](#recommendations-2)
 
-- [Website recommendations](./assessments#recommendations-2)
+- [Website recommendations](#recommendations-3)
 
 Readers interested in the current state of the documentation and the reasoning
 behind the recommendations should start with the analyses:
 
-- [Project documentation](./assessments#project-documentation-analysis)
+- [Project documentation](#project-documentation-analysis)
 
-- [Contributor documentation](./assessments#contributor-documentation-analysis)
+- [Contributor documentation](#contributor-documentation-analysis)
 
-- [Website](./assessments#website-analysis)
+- [Website](#website-analysis)
 
 # Analysis and Recommendations
 
@@ -138,7 +138,7 @@ sync.
 The Contributing and Governance files do not mention changes or additions to
 documentation as potential areas of contribution.
 
-### Recommendations
+### Recommendations 1
 
 **Information Architecture**
 
@@ -235,7 +235,7 @@ contribution (such as docs).
 **Project governance documentation**: Clearly described and discoverable on
 GOVERNANCE page.
 
-### Recommendations
+### Recommendations 2
 
 **Communication methods documented**
 
@@ -333,7 +333,7 @@ correctly.
 **Intra-site / local search**: There is no site map or search mechanism; the
 only navigation is through a minimal menu bar.
 
-### Recommendations
+### Recommendations 3
 
 **Meets min website req. (for Incubating)**, **Intra-site / local search**
 

diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md
@@ -13,7 +13,7 @@ repurposed as the new overall **Doc home page**.
 
 - [ ] To be immediately useful, the landing page should provide a _top-level
       roadmap_ to existing docs. See
-      [Survey of existing doc](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md)
+      [Survey of existing doc](survey-of-existing-doc.md)
 
   This is a necessary step in raising the maturity level of this project. The
   roadmap should initially describe and provide access to:
@@ -72,9 +72,9 @@ A basic intro, possibly suitable for evaluators, is already linked directly from
 the [home page About tab](https://in-toto.io/in-toto/). The short intro links to
 the
 [latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md),
-which contains a more comprehensive overview. (NOTE: The
-[PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf)
-is broken. This should be fixed or removed.)
+which contains a more comprehensive overview. (NOTE: The PDF link to the stable
+spec, `https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf`, is broken.
+This should be fixed or removed.)
 
 - [ ] Initially, transfer the tech overview content from the Specification into
       a top-level Technical Overview document in RTD, and link as "Read more..."

diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md
@@ -3,9 +3,9 @@
 ## Organizational principles
 
 Review the
-[CNCF website design guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md)
-for project home page and architecture recommendations. Consult with CNCF
-TechDocs or other technical documentation specialists to develop an appropriate
+[CNCF website design guidelines](../../docs/website-guidelines-checklist.md) for
+project home page and architecture recommendations. Consult with CNCF TechDocs
+or other technical documentation specialists to develop an appropriate
 information architecture based on different user roles and their specific tasks
 and information needs.
 
@@ -76,7 +76,7 @@ following general plan.
    menu.
 
    b. Create a **Getting Started** page on the web site from the existing README
-   content in the [main repo](https://github.com/in-toto/in-toto.README.md).
+   content in the [main repo](https://github.com/in-toto/in-toto).
 
    c. Link **Getting Started** as the first menu item in the **Get started**
    menu (currently the first item is a link to a demo).
@@ -85,7 +85,7 @@ following general plan.
    the website, as:
 
    - [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview)
-     (compare content to https://in-toto.io/in-toto/README and current website
+     (compare content to <https://in-toto.io/in-toto> and current website
      About - create versions of increasing depth to address to specific
      audiences)
    - [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology)
@@ -132,8 +132,8 @@ following general plan.
    the git repo structure.
 
    1.1 Create a _top-level roadmap_ to
-   [existing docs](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md)
-   at the location decided on for the Doc home page.
+   [existing docs](survey-of-existing-doc.md) at the location decided on for the
+   Doc home page.
 
    1.2 Move the Description and pointer to the Python Reference implementation
    to an **Implementations** section, and move the RTD reference docs for it
@@ -179,9 +179,9 @@ following general plan.
    from the [home page About tab](https://in-toto.io/in-toto/). The short intro
    links to the
    [latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md),
-   which contains a more comprehensive overview. (NOTE: The
-   [PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf)
-   is broken. This should be fixed or removed.)
+   which contains a more comprehensive overview. (NOTE: The PDF link to the
+   stable spec, `https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf` is
+   broken. This should be fixed or removed.)
 
    3.1 Initially, transfer the tech overview content from the Specification into
    a top-level Technical Overview document in RTD, and link as "Read more..."