cncf · chalin · Feb 25, 2025 · Feb 25, 2025 · Feb 25, 2025 · Feb 25, 2025
diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md
@@ -313,8 +313,8 @@ For example:
 - [installation check][install-check]: contains "sanity check", a term
   designated "Strongly Consider Replacing" by the [Inclusive Naming
   Initiative][inclusive-naming].
-- There is some use of language like "easy", "simple", and "just [take
-  an action]"; for example, "Creating a user is as easy as" in
+- There is some use of language like "easy", "simple", and "just [take an
+  action]"; for example, "Creating a user is as easy as" in
   [Role-based access control](https://etcd.io/docs/v3.5/op-guide/authentication/rbac/).
 
 ## Recommendations

diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/0013-litmuschaos/litmuschaos-analysis.md
@@ -4,11 +4,9 @@ tags: LitmusChaos
 created: 2024-08-02
 modified: 2024-10-09
 author: Dave Welsch (@dwelsch-esi)
+cSpell:ignore: Docusaurus rfc OSes pastable impl servicedesk md
 ---
 
-<!-- markdownlint-enable line-length -->
-<!-- cSpell:ignore Docusaurus rfc OSes pastable impl servicedesk md -->
-
 <!-- markdownlint-disable no-duplicate-heading -->
 
 ## Introduction
@@ -30,8 +28,9 @@ This document was written to analyze the current state of LitmusChaos
 documentation. It aims to provide project leaders with an informed understanding
 of potential problems in current project documentation. A second
 [implementation] document outlines an actionable plan for improvement. A third
-document is an [issues list] of issues to be added to the project documentation repository.
-These issues can be taken up by contributors to improve the documentation.
+document is an [issues list] of issues to be added to the project documentation
+repository. These issues can be taken up by contributors to improve the
+documentation.
 
 This document:
 
@@ -62,9 +61,9 @@ GitHub repo.
 
 #### Out of scope
 
-- Other LitmusChaos repos: <https://github.com/litmuschaos/>\*
+- Other LitmusChaos repos: <https://github.com/litmuschaos/>
 - Litmus Software (a completely unrelated company and product based in
-  Massachusetts): https://litmus.com/*
+  Massachusetts): <https://litmus.com/>
 
 ### How this document is organized
 
@@ -172,9 +171,9 @@ installation, configuration, and running a "first-time" experiment.
 - Formatting and organization of the instructions is inconsistent.
 - Some minor functionality does not have complete step-by-step instructions. For
   example, a link in the instructions to connect an external delegate in
-  _Schedule a chaos scenario_
-  point to the `litmusctl` reference. While relevant, this is not the same as
-  explicit instructions for connecting to a delegate.
+  _Schedule a chaos scenario_ point to the `litmusctl` reference. While
+  relevant, this is not the same as explicit instructions for connecting to a
+  delegate.
 
 <!-- markdownlint-enable line-length -->
 
@@ -292,7 +291,7 @@ complete. For complex procedures, it's OK to link to sub-procedures or (usually
 better) put preliminary tasks in the Prerequisites section.
 
 Ensure that installation, setup, and verification have a clear, linked path for
-each user role. See [New user content](#New-user-content) below.
+each user role. See [New user content](#new-user-content) below.
 
 Organize the User Guide by task. Some of the tasks will align with the current
 function-based organization, but some will not. If necessary, split it into two
@@ -604,12 +603,12 @@ websites:
 
 <!-- markdownlint-disable line-length -->
 
-| Site      | Repository                                               | Tool or Stack            |
-|-----------| -------------------------------------------------------- | ------------------------ |
-| [Project website](https://litmuschaos.io/) | https://github.com/litmuschaos/litmus-website-2          | React/Next/Tailwind/SCSS |
-| [Documentation website](https://docs.litmuschaos.io/) | https://github.com/litmuschaos/litmus-docs/              | Docusaurus/Netlify       |
-| Tutorials | https://github.com/litmuschaos/tutorials                 | Google Codelab?          |
-| [APIs][api-site] | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs                   |
+| Site                                                  | Repository                                                 | Tool or Stack            |
+| ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------ |
+| [Project website](https://litmuschaos.io/)            | <https://github.com/litmuschaos/litmus-website-2>          | React/Next/Tailwind/SCSS |
+| [Documentation website](https://docs.litmuschaos.io/) | <https://github.com/litmuschaos/litmus-docs/>              | Docusaurus/Netlify       |
+| Tutorials                                             | <https://github.com/litmuschaos/tutorials>                 | Google Codelab?          |
+| [APIs][api-site]                                      | <https://github.com/litmuschaos/litmus/tree/master/mkdocs> | MkDocs                   |
 
 <!-- markdownlint-enable line-length -->
 

diff --git a/analyses/0013-litmuschaos/litmuschaos-implementation.md b/analyses/0013-litmuschaos/litmuschaos-implementation.md
@@ -23,10 +23,10 @@ things. Few recommendations here are meant to be prescriptive. Rather,
 recommendations are based on documentation best practices as understood by the
 reviewers. The recommended implementations represent the reviewers' experience
 with how to apply those best practices. In other words, borrowing terminology
-from the lexicon of [RFCs][rfc-keywords], the changes described here should be
-understood as "recommended" or "should" at the strongest, and "optional" or
-"may" in many cases. Any "must" or "required" actions are clearly denoted as
-such, and pertain to legal requirements such as copyright and licensing issues.
+from the lexicon of [RFCs][], the changes described here should be understood as
+"recommended" or "should" at the strongest, and "optional" or "may" in many
+cases. Any "must" or "required" actions are clearly denoted as such, and pertain
+to legal requirements such as copyright and licensing issues.
 
 ## Implementation
 
@@ -129,11 +129,11 @@ There are at least four "getting started" links on the website.
 
 | Link                        | Location                                                     | Refers to                                                                                                 |
 | --------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| _Get Started_ button        | [Product landing page](https://litmuschaos.io/)              | [GitHub repo]()                                                                                           |
+| _Get Started_ button        | [Product landing page](https://litmuschaos.io/)              | [GitHub repo](https://github.com/litmuschaos/litmus)                                                      |
 | _Get Started_ button        | [Doc landing page](https://docs.litmuschaos.io/)             | [ChaosCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation)                 |
 | _Getting Started_ link      | [Doc landing page](https://docs.litmuschaos.io/)             | [What is Litmus?](https://docs.litmuschaos.io/docs/introduction/what-is-litmus)                           |
 | _Getting Started_ TOC entry | [Doc page](https://docs.litmuschaos.io/docs/) left-side menu | [ChaosCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation)                 |
-| _Getting started_ tutorial  | Tutorial site    | [Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0) |
+| _Getting started_ tutorial  | Tutorial site                                                | [Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0) |
 
 <!-- markdownlint-enable line-length -->
 
@@ -160,9 +160,10 @@ be its own page.
 
 Ensure that installation, setup, and verification have a clear workflow. If
 these instructions vary significantly between user roles, write a separate
-workflow for each user role. See [New user content](#new-user-content) below.
-Rename "Learn more" at the end of procedures and tasks to "Next steps". Explain
-who would want to do each item and why in a short paragraph.
+workflow for each user role. See
+[New user content](litmuschaos-analysis.md#new-user-content). Rename "Learn
+more" at the end of procedures and tasks to "Next steps". Explain who would want
+to do each item and why in a short paragraph.
 
 Limit on-site search to the current version of the documentation.
 
@@ -252,3 +253,5 @@ Consider adding links from the graphic elements on the project landing page.
 Update or remove the CNCF announcement in the banner menu Community drop-down.
 
 Implement analytics.
+
+[RFCs]: https://www.rfc-editor.org/rfc/rfc2119
diff --git a/analyses/0013-litmuschaos/litmuschaos-issues.md b/analyses/0013-litmuschaos/litmuschaos-issues.md
@@ -3,6 +3,8 @@ title: Litmus Chaos Issue
 tags: Litmus Chaos
 ---
 
+<!-- markdownlint-disable line-length no-duplicate-heading no-emphasis-as-heading -->
+
 This document contains a list of issues to be entered in the Litmus Chaos
 documentation repo more or less verbatim.
 
@@ -43,13 +45,13 @@ are here: <https://github.com/cncf/techdocs/tree/main/analyses> under
 
 The following repos are affected:
 
-| Repo URL                                           | Description                                     | Recommendation                                            |
-| -------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
-| https://github.com/litmuschaos/litmus-website-2    | The project website repo                        | Combine with the doc repo                                 |
-| https://github.com/litmuschaos/litmus-docs         | Documentation repo                              | Combine with website repo                                 |
-| https://github.com/litmuschaos/v1-litmus-docs      | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving.                       |
-| https://github.com/litmuschaos/website-litmuschaos | Previous website repo                           | Already archived. Include new repo URL in archive banner. |
-| https://github.com/litmuschaos/tutorials           | Tutorials repo                                  | Combine with documentation repo                           |
+| Repo URL                                             | Description                                     | Recommendation                                            |
+| ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
+| <https://github.com/litmuschaos/litmus-website-2>    | The project website repo                        | Combine with the doc repo                                 |
+| <https://github.com/litmuschaos/litmus-docs>         | Documentation repo                              | Combine with website repo                                 |
+| <https://github.com/litmuschaos/v1-litmus-docs>      | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving.                       |
+| <https://github.com/litmuschaos/website-litmuschaos> | Previous website repo                           | Already archived. Include new repo URL in archive banner. |
+| <https://github.com/litmuschaos/tutorials>           | Tutorials repo                                  | Combine with documentation repo                           |
 
 ## Issue: Removed obsolete websites
 
@@ -83,17 +85,17 @@ are here: <https://github.com/cncf/techdocs/tree/main/analyses> under
 **GraphicQL API**
 
 The following API is one of the first hits on a search of "Litmus Chaos API":
-https://litmuschaos.github.io/litmus/graphql/v2.0.0/api.html.
+<https://litmuschaos.github.io/litmus/graphql/v2.0.0/api.html>.
 
-I'm not even sure where the doc repo is (it might be in the API's repo here:
-https://github.com/litmuschaos/spectaql). It's clear this is a Litmus Chaos
-component, but not whether this documetnation is current or what it is for --
+I'm not even sure where the doc repo is (it might be in the API's repo at
+<https://github.com/litmuschaos/spectaql>). It's clear this is a Litmus Chaos
+component, but not whether this documentation is current or what it is for --
 there's no introduction or explanation of the API.
 
 **Tutorials**
 
-The Litmus Chaos Tutorial website (https://litmuschaos.github.io/tutorials/;
-repo at https://github.com/litmuschaos/tutorials) seems to have been last
+The [Litmus Chaos Tutorial website](https://litmuschaos.github.io/tutorials/)
+([repo](https://github.com/litmuschaos/tutorials)) seems to have been last
 updated in version 2. The first tutorial, "Getting Started", was last updated in
 August of 2021.
 

diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md
@@ -12,8 +12,8 @@ The goals of a CNCF technical documentation analysis are to:
 
 - Examine the current project technical documentation and website against the
   CNCF's analysis [criteria].
-- Compare the documentation against the current or proposed [project
-  maturity level].
+- Compare the documentation against the current or proposed [project maturity
+  level].
 - Recommend a program of key documentation improvements with the largest return
   on investment. These improvements are documented as _recommendations_ in the
   analysis document, and expanded in a companion

diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md
@@ -46,8 +46,8 @@ This document was written to analyze the current state of _PROJECT_
 documentation. It aims to provide project leaders with an informed understanding
 of potential problems in current project documentation. A second [impementation]
 document, , outlines an actionable plan for improvement. A third document is an
-[issues list] of issues to be added to the project documentation repository. These
-issues can be taken up by contributors to improve the documentation.
+[issues list] of issues to be added to the project documentation repository.
+These issues can be taken up by contributors to improve the documentation.
 
 This document:
 
@@ -61,23 +61,23 @@ The documentation discussed here includes the entire contents of the website,
 the technical documentation, and documentation for contributors and users on the
 _PROJECT_ GitHub repository.
 
-The _PROJECT_ website and documentation are written in [Markdown,
-ReStructured Text, other] and are compiled using the [Hugo, Docusaurus,
-Sphynx, other] static site generator with the [Docsy, other] theme and served from
-[the Netlify platform, other]. The site's code is stored on the _PROJECT_ GitHub
-repo.
+The _PROJECT_ website and documentation are written in [Markdown, ReStructured
+Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, other] static
+site generator with the [Docsy, other] theme and served from [the Netlify
+platform, other]. The site's code is stored on the _PROJECT_ GitHub repo.
 
 #### In scope
 
 - Website: _PROJECT-WEBSITE_
 - Documentation: _PROJECT-DOC-URL_
 - Website repo: _PROJECT-DOC-REPO_
-- _[Other; might include a demo server, governance site, or other relevant repositories]_
+- _[Other; might include a demo server, governance site, or other relevant
+  repositories]_
 
 #### Out of scope
 
-- Other _PROJECT_ repos: _[In general, do not include sub-projects or
-  related "ecosystem" projects]_
+- Other _PROJECT_ repos: _[In general, do not include sub-projects or related
+  "ecosystem" projects]_
 
 ### How this document is organized
 

diff --git a/docs/analytics.md b/docs/analytics.md
@@ -33,8 +33,8 @@ process below. Adapt it to your needs. Useful resources to consider include:
 In preparation for the migration, follow these steps:
 
 1. **Create an issue** over your project's website with the title "Migrate to
-   Google Analytics 4 (GA4)", and link to [Issue #108][]. For example, see the issues
-   opened for the pilot projects listed in #108.
+   Google Analytics 4 (GA4)", and link to [Issue #108][]. For example, see the
+   issues opened for the pilot projects listed in #108.
 
 2. Determine which **analytics library** your project's website is using.
 
@@ -69,8 +69,8 @@ Follow these steps:
 
     How you switch will depend on the static-site generation tooling you use.
     For details, see [Stage 2][]. If you know how to switch and it is easy to do
-    so, then switch your project to [gtag.js][], otherwise defer the switch to [stage
-    2][].
+    so, then switch your project to [gtag.js][], otherwise defer the switch to
+    [stage 2][].
 
 2.  **Open the analytics console** of your project's UA property by visiting
     [analytics.google.com](https://analytics.google.com).
@@ -179,9 +179,9 @@ code (such as custom Hugo partials) to enable GA4, consider removing the custom
 code in favor of the native support provided by your site-generator tooling.
 
 For example, for [Docsy][]-based websites, all you need to do is provide your
-project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of course,
-this may require you to upgrade the version of [Docsy][] and/or Hugo that your project
-is using.
+project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of
+course, this may require you to upgrade the version of [Docsy][] and/or Hugo
+that your project is using.
 
 [add gtag.js to your site]:
   https://developers.google.com/analytics/devguides/collection/gtagjs/

diff --git a/package.json b/package.json
@@ -16,26 +16,29 @@
     "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
     "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
     "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
-    "check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json $f || exit 1; done'",
+    "check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check@3.12.2 --config .markdown-link-check.json -p -v $f || exit 1; done'",
     "check:markdown": "npm run _check:markdown:all",
     "check:spelling": "npx cspell --no-progress -c .cspell.yml *.md",
     "check": "npm run seq -- $(npm run -s _list:check:*)",
     "fix:format": "npm run _check:format -- --write",
     "fix": "npm run seq -- $(npm -s run _list:fix:*)",
     "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ",
-    "test": "npm run check"
+    "test": "npm run check",
+    "update:pkgs": "npx npm-check-updates -u"
   },
   "author": "CNCF",
   "license": "CC-BY-4.0",
+  "NOTE": "We've pinned markdown-link-check to 3.12.2 due to a bug in 3.13.x stream, both in the devDeps below and the check:links script above. For details, see https://github.com/tcort/markdown-link-check/issues/369.",
   "devDependencies": {
-    "cspell": "^8.8.4",
-    "markdown-link-check": "^3.12.2",
-    "markdownlint": "^0.34.0",
-    "markdownlint-cli": "^0.41.0",
-    "prettier": "^3.3.2"
+    "cspell": "^8.17.5",
+    "markdown-link-check": "3.12.2",
+    "markdownlint": "^0.37.4",
+    "markdownlint-cli": "^0.44.0",
+    "npm-check-updates": "^17.1.15",
+    "prettier": "^3.5.2"
   },
   "private": true,
-  "spelling": "cSpell:ignore ACMR loglevel -",
+  "spelling": "cSpell:ignore ACMR loglevel pkgs -",
   "prettier": {
     "proseWrap": "always",
     "singleQuote": true