Publish analyses in Docus, fix links, rewrite cross-plugin links (#351)

Author: chalin

.htmltest.yml

@@ -3,13 +3,14 @@ CacheExpires: 4500h # ~ 6 months
 DirectoryPath: build
 TestFilesConcurrently: true
 IgnoreDirs:
+  # We don't fix broken links on old analysis pages.
+  # - analyses/202[0-5]/
 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
-  - /analyses/
+  # Old analysis pages are not updated. Ignore broken links:
+  - ^https://(docs|www).tremor.rs/
+  - ^https://knative.dev/docs/(concepts|reference|relnotes)/
+  - ^https://knative.dev/development/concepts/serving-resources/revisions/
+  - ^https://vitess.io/docs/21.0/

.markdownlintignore

@@ -0,0 +1,10 @@
+# Paths excluded from markdownlint (see `markdownlint --help` → --ignore-path).
+# Patterns follow .gitignore semantics (see markdownlint-cli).
+
+# Dependencies and build output
+node_modules/
+build/
+.docusaurus/
+
+# Scratch / local
+tmp/

README.md

@@ -3,15 +3,15 @@
 This site contains resources provided by the CNCF Technical Documentation team,
 including:
 
-- [Docs](docs/) about building websites and developing technical documentation,
+- [Docs](/docs/) about building websites and developing technical documentation,
   including recommended tools, best practices, how-tos, and evaluation
   checklists. It provides specific guidelines for:
   - Setting up and maintaining a documentation website.
   - Writing technical documentation for a project.
   - Seeking assistance from the CNCF TechDocs community.
-  - [Analyzing project documentation](docs/analysis/).
-- [Analyses](analyses/): a collection of documentation analyses of CNCF projects
-  performed by the TechDocs team.
+  - [Analyzing project documentation](/docs/analysis/).
+- [Analyses](/analyses/): a collection of documentation analyses of CNCF
+  projects performed by the TechDocs team.
 
 ## TechDocs Q&A
 
@@ -29,7 +29,7 @@ every month at 8am Pacific time][date-time].
 
 The TechDocs team can help CNCF projects analyze and improve their
 documentation. For details, see the TechDocs
-[assistance program](docs/assistance.md).
+[assistance program](/docs/assistance.md).
 
 ## CNCF TechDocs team
 
@@ -46,8 +46,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

analyses/2021/contour/analysis.md

@@ -4,6 +4,8 @@ tags: [contour]
 cSpell:ignore: Horgan celestehorgan hashlinks
 ---
 
+<!-- markdownlint-disable line-length no-duplicate-heading -->
+
 # Docs assessment
 
 ## Introduction

analyses/2021/fluxcd/analysis.md

@@ -4,6 +4,8 @@ tags: [fluxcd]
 cSpell:ignore: celestehorgan Horgan
 ---
 
+<!-- markdownlint-disable no-duplicate-heading -->
+
 # Assessment template
 
 Prepared by: Celeste Horgan

analyses/2021/krator/analysis.md

@@ -4,6 +4,8 @@ tags: [krator]
 cSpell:ignore: Krator celestehorgan CODEOWNERS
 ---
 
+<!-- markdownlint-disable line-length no-duplicate-heading -->
+
 # Krator Docs assessment
 
 ## Introduction

analyses/2021/kubernetes-gateway-api/analysis.md

@@ -4,6 +4,9 @@ tags: [kubernetes-gateway-api]
 cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes
 ---
 
+<!-- markdownlint-disable line-length -->
+<!-- markdownlint-disable ul-style descriptive-link-text no-duplicate-heading no-trailing-punctuation -->
+
 # Assessment: Project Kubernetes Gateway API
 
 Prepared by: Meha Bhalodiya
@@ -103,7 +106,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](../docs/images/gapi_info_arch.png)
+  ![information_architecture](../../../docs/images/gapi_info_arch.png)
 
 - There are improvements we could make:
   - With the collection of guided, step-by-step instructions (tasks, hands-on

analyses/2021/notary/analysis.md

@@ -4,6 +4,8 @@ tags: [notary]
 cSpell:ignore: docset notaryproject celestehorgan
 ---
 
+<!-- markdownlint-disable no-duplicate-heading no-emphasis-as-heading -->
+
 # Notary Project Docs Assessment
 
 Date: 2021-07-31 Project: [Notary Project](https://github.com/notaryproject/)

analyses/2021/tremor/analysis.md

@@ -4,6 +4,8 @@ tags: [tremor]
 cSpell:ignore: Horgan onramps offramps LLDB Wayfair
 ---
 
+<!-- markdownlint-disable no-emphasis-as-heading -->
+
 # Assessment: Project Tremor
 
 Prepared by: Celeste Horgan Date: July 2021