[CI] Update packages and run checks and fixes (#287)

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
+- There is some use of language like "easy", "simple", and "just [take an
-  an action]"; for example, "Creating a user is as easy as" in
+  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

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.
+document is an [issues list] of issues to be added to the project documentation
-These issues can be taken up by contributors to improve the 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_
+  _Schedule a chaos scenario_ point to the `litmusctl` reference. While
-  point to the `litmusctl` reference. While relevant, this is not the same as
+  relevant, this is not the same as explicit instructions for connecting to a
-  explicit instructions for connecting to a delegate.
+  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            |
+| Site                                                  | Repository                                                 | Tool or Stack            |
-|-----------| -------------------------------------------------------- | ------------------------ |
+| ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------ |
-| [Project website](https://litmuschaos.io/) | https://github.com/litmuschaos/litmus-website-2          | React/Next/Tailwind/SCSS |
+| [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       |
+| [Documentation website](https://docs.litmuschaos.io/) | <https://github.com/litmuschaos/litmus-docs/>              | Docusaurus/Netlify       |
-| Tutorials | https://github.com/litmuschaos/tutorials                 | Google Codelab?          |
+| Tutorials                                             | <https://github.com/litmuschaos/tutorials>                 | Google Codelab?          |
-| [APIs][api-site] | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs                   |
+| [APIs][api-site]                                      | <https://github.com/litmuschaos/litmus/tree/master/mkdocs> | MkDocs                   |
 
 <!-- markdownlint-enable line-length -->
 

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
+from the lexicon of [RFCs][], the changes described here should be understood as
-understood as "recommended" or "should" at the strongest, and "optional" or
+"recommended" or "should" at the strongest, and "optional" or "may" in many
-"may" in many cases. Any "must" or "required" actions are clearly denoted as
+cases. Any "must" or "required" actions are clearly denoted as such, and pertain
-such, and pertain to legal requirements such as copyright and licensing issues.
+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.
+workflow for each user role. See
-Rename "Learn more" at the end of procedures and tasks to "Next steps". Explain
+[New user content](litmuschaos-analysis.md#new-user-content). Rename "Learn
-who would want to do each item and why in a short paragraph.
+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

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                                            |
+| 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-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/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/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/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                           |
+| <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:
+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
+<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 --
+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/;
+The [Litmus Chaos Tutorial website](https://litmuschaos.github.io/tutorials/)
-repo at https://github.com/litmuschaos/tutorials) seems to have been last
+([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.
 

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
+- Compare the documentation against the current or proposed [project maturity
-  maturity level].
+  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

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 list] of issues to be added to the project documentation repository.
-issues can be taken up by contributors to improve the documentation.
+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,
+The _PROJECT_ website and documentation are written in [Markdown, ReStructured
-ReStructured Text, other] and are compiled using the [Hugo, Docusaurus,
+Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, other] static
-Sphynx, other] static site generator with the [Docsy, other] theme and served from
+site generator with the [Docsy, other] theme and served from [the Netlify
-[the Netlify platform, other]. The site's code is stored on the _PROJECT_ GitHub
+platform, other]. The site's code is stored on the _PROJECT_ GitHub repo.
-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
+- Other _PROJECT_ repos: _[In general, do not include sub-projects or related
-  related "ecosystem" projects]_
+  "ecosystem" projects]_
 
 ### How this document is organized
 

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
+   Google Analytics 4 (GA4)", and link to [Issue #108][]. For example, see the
-   opened for the pilot projects listed in #108.
+   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
+    so, then switch your project to [gtag.js][], otherwise defer the switch to
-    2][].
+    [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,
+project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of
-this may require you to upgrade the version of [Docsy][] and/or Hugo that your project
+course, this may require you to upgrade the version of [Docsy][] and/or Hugo
-is using.
+that your project is using.
 
 [add gtag.js to your site]:
   https://developers.google.com/analytics/devguides/collection/gtagjs/

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",
+    "cspell": "^8.17.5",
-    "markdown-link-check": "^3.12.2",
+    "markdown-link-check": "3.12.2",
-    "markdownlint": "^0.34.0",
+    "markdownlint": "^0.37.4",
-    "markdownlint-cli": "^0.41.0",
+    "markdownlint-cli": "^0.44.0",
-    "prettier": "^3.3.2"
+    "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