[CI & docs] Rework of analysis docs + improved checks (#256)

.github/workflows/format-check.yml

@@ -14,5 +14,16 @@ jobs:
           node-version-file: .nvmrc
           cache: npm
           cache-dependency-path: package.json
-      - name: Check file format
+      - run: npm run check:format
-        run: npm run check:format
+
+  markdown-linter:
+    name: MARKDOWN linter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: package.json
+      - run: npm run check:markdown

.markdownlint.yaml

@@ -0,0 +1,5 @@
+# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+# and https://github.com/DavidAnson/markdownlint/blob/main/README.md
+
+list-marker-space: false
+no-inline-html: false

README.md

@@ -13,27 +13,29 @@ team. The repo contains the following directories:
 
 The full-time staff of the CNCF Tech Docs team is:
 
+<!-- markdownlint-disable line-length -->
+
 | GitHub ID                                          | Role                                  |
 | -------------------------------------------------- | ------------------------------------- |
 | [@chalin](https://github.com/chalin)               | Senior technical writer               |
 | [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer |
 | [@thisisobate](https://github.com/thisisobate)     | Developer advocate                    |
 
+<!-- markdownlint-enable line-length -->
 <!-- cSpell:ignore chalin nate thisisobate -->
 
 Various consultants and volunteers also contribute to CNCF Tech Docs projects.
 
 ## Office hours
 
-The CNCF tech docs team holds office hours on the
+The CNCF tech docs team holds office hours on the [fourth Wednesday of every
-[fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours).
+month at 8am Pacific time][date-time].
 
 Office hours started on 30 September 2020.
 
 ### Meeting link
 
-Zoom link:
+- [Zoom meeting 95471930872]
-https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e
 
 ### Meeting notes
 
@@ -51,3 +53,8 @@ documentation. For details, see the TechDocs
 The `docs/` directory contains collected resources for building websites and
 developing documentation, including recommended tools and practices, how-tos,
 and evaluation checklists.
+
+[date-time]:
+  https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours
+[Zoom meeting 95471930872]:
+  https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e

analyses/README.md

@@ -15,7 +15,7 @@ The goals of a CNCF technical documentation analysis are to:
   investment. These improvements are documented as _recommendations_ in the
   analysis document and expanded in a companion
   [implementation plan](../docs/analysis/templates/implementation.md) and
-  [issues backlog](../docs/analysis/templates/umbrella-issue.md).
+  [issues backlog](../docs/analysis/templates/issues-list.md).
 
 ## Audience
 

docs/analysis/README.md

@@ -1,11 +1,7 @@
 # TechDoc Analysis
 
-## Contents
+This section contains instructions and criteria for completing a documentation
+analysis, including a [how-to](./howto.md) guide and analysis
+[criteria](./criteria.md)
 
-This directory contains instructions and criteria for completing a documentation
+For templates, see [templates](./templates/).
-analysis, including a [how-to][] guide and analysis [criteria][].
-
-Templates for the analyses are in the resources directory.
-
-[how-to]: ./howto.md
-[criteria]: ./criteria.md

docs/analysis/criteria.md

@@ -23,7 +23,7 @@ documentation. We evaluate on the following:
 
 Examples:
 
-- https://prometheus.io/docs/
+- <https://prometheus.io/docs>
 
 ### New user content
 
@@ -41,7 +41,7 @@ specifically for them. We evaluate on the following:
 
 Examples:
 
-- https://falco.org/docs/getting-started/
+- <https://falco.org/docs/getting-started/>
 
 ### Content maintainability & site mechanics
 
@@ -57,7 +57,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://kubernetes.io/docs/
+- <https://kubernetes.io/docs/>
 
 ### Content creation processes
 
@@ -74,9 +74,9 @@ We evaluate on the following:
 
 Examples:
 
-- https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly
+- <https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md> (clearly
   documented maintainers)
-- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md
+- <https://thanos.io/tip/contributing/how-to-contribute-to-docs.md>
 
 ### Inclusive language
 
@@ -107,7 +107,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://prometheus.io/community/
+- <https://prometheus.io/community/>
 
 ### Beginner friendly issue backlog
 
@@ -121,7 +121,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://github.com/opentracing/opentracing.io/issues (all of open tracing’s
+- <https://github.com/opentracing/opentracing.io/issues> (all of open tracing’s
   backlogs are well maintained!)
 
 ### New contributor getting started content
@@ -138,7 +138,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://github.com/helm/community
+- <https://github.com/helm/community>
 
 ### Project governance documentation
 
@@ -165,7 +165,8 @@ problems, keeping source files in two places:
 - makes it more complicated to generate the documentation from source files
 
 Ideally, all website files should be in the **website repo** itself.
-Alternatively, files should be brought into the website repo via [git submodules][].
+Alternatively, files should be brought into the website repo via
+[git submodules](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules).
 
 If a project chooses to keep source files in multiple repos, they need a clearly
 documented strategy for managing mirrored files and new contributions.
@@ -257,7 +258,7 @@ We evaluate on the following:
 
 Examples:
 
-- https://helm.sh/
+- <https://helm.sh/>
 
 ### Case studies/social proof
 
@@ -275,9 +276,9 @@ We evaluate on the following:
 
 Examples:
 
-- https://www.fluentd.org/testimonials (user testimonials)
+- <https://www.fluentd.org/testimonials> (user testimonials)
-- https://goharbor.io/ (logo wall)
+- <https://goharbor.io/> (logo wall)
-- https://blog.rook.io/ (blog)
+- <https://blog.rook.io/> (blog)
 
 ### SEO, Analytics and site-local search
 
@@ -314,7 +315,7 @@ We evaluate on the following:
 
 Examples:
 
-- http://kubernetes.io
+- <https://kubernetes.io>
 
 ### Other
 

docs/analysis/howto.md

@@ -2,75 +2,78 @@
 
 ## Audience
 
-This document is for members of the CNCF TechDocs team, including contractors or
+This document is for members of the CNCF TechDocs team and others who wish to
-consultants, who need to conduct or assist with an analysis of a CNCF
+conduct or assist with an analysis of a CNCF open-source project's technical
-open-source project's technical documentation.
+documentation.
 
 ## Purpose
 
 The goals of a CNCF technical documentation analysis are to:
 
 - Examine the current project technical documentation and website against the
-  CNCF's analysis framework, as described in the doc analysis
+  CNCF's analysis [criteria].
-  [criteria](./criteria.md).
+- Compare the documentation against the current or proposed [project
-- Compare the documentation against the current or proposed maturity level for
+  maturity level].
-  the overall project.
+- Recommend a program of key documentation improvements with the largest return
-- Recommends a program of key improvements with the largest return on
+  on investment. These improvements are documented as _recommendations_ in the
-  investment. These improvements are documented as _recommendations_ in the
+  analysis document, and expanded in a companion
-  analysis document and expanded in a companion
   [implementation plan](./templates/implementation.md) and
-  [issues backlog](./templates/umbrella-issue.md).
+  [issues list](./templates/issues-list.md).
 
 ## Doing a Tech Docs Analysis
 
-The tech docs analysis consists of some repository bookkeeping (Prerequisites),
+The tech docs analysis consists of some repository bookkeeping (prerequisites),
 then of three overall tasks:
 
-1. Write the analysis document: Evaluate the existing project documentation with
+1. Write the analysis document: evaluate the existing project documentation with
-   respect to the project maturity level (or proposed maturity level, if the
+   respect to the [project maturity level] or proposed maturity level, if the
-   analysis is associated with an upgrade request). Identify gaps with CNCF
+   analysis is associated with a project upgrade request. Identify gaps with
-   criteria. Write general recommendations to close the largest and most
+   CNCF [criteria]. Write general recommendations to close the largest and most
-   important gaps.
+   important identified issues.
-2. Write the implementation plan: Decompose the recommendations to specific
+2. Write a implementation plan: decompose recommendations in to specific
    improvement suggestions. These can be additions or revisions to the docs;
    reorganization; website infrastructure changes; or any other work that will
-   close the gaps. Make suggestions specific (if you propose reorganizing a
+   close address issues. Make suggestions specific enough (for example, if you
-   section, for example, provide an outline) but provide enough information that
+   propose reorganizing a section then provide an outline) without being overly
-   a contributor could solve the problem differently if they have a different
+   constraining so that a contributor could solve the problem differently if
-   idea (make it clear that your proposed outline is only one possible
+   they have a different solution. For example, make it clear that your proposed
-   reorganization, e.g.).
+   outline is only one possible reorganization.
-3. Write the issue backlog.
+3. Write an issue backlog.
 
-Finally, there are follow-up steps including creating GitHub issues and a pull
+Finally, there are follow-up steps including:
-request, and getting approval from project maintainers.
+
+- Creating GitHub issues and a pull request
+- Getting approval from project maintainers
 
 ### Prerequisites
 
-This process assumes you have some familiarity with GitHub repositories and pull
+This section assumes you are familiar with GitHub repositories and pull requests
-requests (PRs).
+(PRs). If you need a refresher, see
+[Get started](https://docs.github.com/en/get-started) from the GitHub docs.
+
+Project analyses are kept in the
+[CNCF tech docs repository](https://github.com/cncf/techdocs). Clone and prepare
+for
 
 1. Clone the [CNCF tech docs repository](https://github.com/cncf/techdocs).
-1. Create a branch for the analysis.
+2. Create a branch for the analysis.
-1. In the new branch, create a directory for the analysis in the CNCF tech docs
+3. In the new branch, create a directory for the analysis in the CNCF tech docs
-   /analysis directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the
+   [analyses] directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the
    next index available in the directory (check for PRs as well, if someone else
    is working on tech doc analyses), and where _PROJECT_ is a short but not
    abbreviated project name. For example, for Kubernetes _PROJECT_ would be
    _kubernetes_, not _k8s_.
-1. Copy and rename the analysis doc templates from the
+4. Copy all the doc analysis [templates].
-   `/analysis/analysis-tools` directory as follows: `analysis-template.md` >
-   `_PROJECT_-analysis.md`; `implementation-template.md` >
-   `_PROJECT_-implementation.md`; and `umbrella-issue-template.md` >
-   `_PROJECT_-issues.md`.
 
 ### Writing the Analysis document
 
-Edit `_PROJECT_-analysis.md` and follow these steps to complete the first step,
+Follow the steps outlined below as a part of writing the project's analysis
-the analysis:
+document. Record your findings in the project's
+[analysis.md](./templates/analysis.md) file.
 
-1. Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs
+1. Define the **scope** of the analysis. Edit "Scope of analysis" to reflect
-   and repositories included and excluded from the analysis.
+   URLs and repositories included and excluded from the analysis.
-1. Review the in-scope URLs and repositories for compliance with the rubric
+2. Review the in-scope URLs and repositories for compliance with the rubric
    criteria. Note any gaps, as well as any areas that exceed criteria or are
    exceptionally well executed. I find it easiest to do this separately for each
    of the three areas of concern (project doc, contributor doc, website), making
@@ -81,11 +84,11 @@ the analysis:
    level (or proposed maturity level, if the analysis is part of a petition for
    upgrade). Write comments to note the most important gaps and best-executed
    features of the documentation.
-1. Assign ratings to each criterion based on your comments and compliance with
+3. Assign ratings to each criterion based on your comments and compliance with
    the maturity level expectations in the rubric. The ratings are
    self-explanatory. Keep in mind that "needs improvement" or "meets standards"
    is with respect to the current (or proposed) maturity level.
-1. Write recommendations. The template implies that you'll do this for every
+4. Write recommendations. The template implies that you'll do this for every
    criterion; the "Recommendations" headings mirror the "Comments" headings.
    However, if some alternative framework makes more sense, use that. For
    example, it might be that two or three of the product documentation criteria
@@ -205,7 +208,14 @@ interested parties to get feedback on the analysis and implementation plan.
 
 ### Creating GitHub issues
 
-Enter the backlog issues from the issues document into the project documentation
+Create issues in the project documentation GitHub repository for:
-GitHub repository using the format in the umbrella-issues-template.md and
+
-issues-template.md files. Create one GitHub issue per backlog issue, and create
+- Each issues in the [issues list].
-an umbrella issue that contains a checklist item for each issue.
+- An umbrella issue that provides a context for the previously created
+  individual issues.
+
+[analyses]: ../../analyses/
+[criteria]: ./criteria.md
+[project maturity level]: https://www.cncf.io/project-metrics
+[templates]: ./templates/
+[issues list]: ./templates/issues-list.md

docs/analysis/templates/README.md

@@ -1,6 +1,6 @@
 # TechDoc Analysis Templates
 
-This directory contains templates for analyzing a CNCF project's documentation.
+This section contains templates for analyzing a CNCF project's documentation.
 
 Use the templates in this directory to perform a documentation analysis for
 CNCF. These materials provide:
@@ -12,6 +12,5 @@ CNCF. These materials provide:
 - Emphasis on effective documentation that serves all users associated with the
   project.
 
-Resources for completing a documentation analysis, including a
+For guidance in completing a documentation analysis, see
-[how-to](../howto.md) guide and analysis [criteria](../criteria.md), are in the
+[Analysis how-to](../howto.md) and [criteria](../criteria.md) pages.
-`docs` directory.

docs/analysis/templates/analysis.md

@@ -6,22 +6,31 @@ modified: YYYY-MM-DD
 author: _NAME_ (@_HANDLE_)
 ---
 
-<!-- TO USE THIS TEMPLATE: Search and replace:
+<!-- markdownlint-disable no-duplicate-heading -->
-_PROJECT_           with the project name
-YYYY-MM-DD          with the creation and modification dates of the analysis document
-_NAME_              with the name of the analysis author
-@_HANDLE_           with the GitHub handle of the analysis author
-_PROJECT-WEBSITE_   with the landing page of the project's information website
-_PROJECT-DOC-URL_   with the main page of the technical documentation for the current project revision; this might be on the main website server, for example as _PROJECT-WEBSITE_/doc
-_PROJECT-DOC-REPO_  with the repository where the project technical documentation is stored; this might be its own repo or a directory in the project main repo
 
-See howto.md for a discussion of the analysis procedure.
+## About this template
 
--->
+TO USE THIS TEMPLATE, search and replace the named IDs:
 
-# Introduction
+- `_PROJECT_`: project name
+- `YYYY-MM-DD`: creation and modification dates of the analysis document
+- `_NAME_`: name of the analysis author
+- `@_HANDLE_`: GitHub handle of the analysis author
+- `_PROJECT-WEBSITE_`: landing page of the project's information website
+- `_PROJECT-DOC-URL_`: main page of the technical documentation for the current
+  project revision; this might be on the main website server, for example as
+  _PROJECT-WEBSITE_/doc
+- `_PROJECT-DOC-REPO_`: repository where the project technical documentation is
+  stored; this might be its own repo or a directory in the project main repo
 
-This document analyzes the effectiveness and completeness of the
+For the analysis procedure, see [Analysis how-to](../howto.md).
+
+> Note: delete this "About this template" section after you have customized this
+> template for a specific project.
+
+## Introduction
+
+This document is an analyzes the effectiveness and completeness of the
 [_PROJECT_][project-website] open source software (OSS) project's documentation
 and website. It is funded by the CNCF Foundation as part of its overall effort
 to incubate, grow, and graduate open source cloud native software projects.
@@ -31,15 +40,14 @@ prerequisite for program graduation. The documentation analysis is the first
 step of a CNCF process aimed at assisting projects with their documentation
 efforts.
 
-## Purpose
+### Purpose
 
 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 document,
+of potential problems in current project documentation. A second [impementation]
-`_PROJECT_-impementation.md`, outlines an actionable plan for improvement. A
+document, , outlines an actionable plan for improvement. A third document is an
-third document, `_PROJECT_-issues.md`, enumerates a backlog of issues to be
+[issues list] of issues to be added to the project documentation repository. These
-added to the project documentation repository. These issues can be taken up by
+issues can be taken up by contributors to improve the documentation.
-contributors to improve the documentation.
 
 This document:
 
@@ -47,7 +55,7 @@ This document:
 - Compares existing documentation against the CNCF’s standards
 - Recommends a program of key improvements with the largest return on investment
 
-## Scope of analysis
+### Scope of analysis
 
 The documentation discussed here includes the entire contents of the website,
 the technical documentation, and documentation for contributors and users on the
@@ -59,19 +67,19 @@ Sphynx, other] static site generator with the [Docsy, other] theme and served fr
 [the Netlify platform, other]. The site's code is stored on the _PROJECT_ GitHub
 repo.
 
-**In scope:**
+#### 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]_
 
-**Out of scope:**
+#### Out of scope
 
 - Other _PROJECT_ repos: _[In general, do not include sub-projects or
   related "ecosystem" projects]_
 
-## How this document is organized
+### How this document is organized
 
 This document is divided into three sections that represent three major areas of
 concern:
@@ -84,38 +92,36 @@ concern:
   includes branding, website structure, and maintainability
 
 Each section begins with summary ratings based on a rubric with appropriate
-[criteria][criteria-doc] for the section, then proceeds to:
+[criteria] for the section, then proceeds to:
 
 - **Comments**: observations about the existing documentation, with a focus on
   how it does or does not help _PROJECT_ users achieve their goals.
 - **Recommendations**: suggested changes that would improve the effectiveness of
   the documentation.
 
-An accompanying document, [`_PROJECT_-implementation.md`][implementation-doc],
+The accompanying [implementation] document breaks the recommendations down into
-breaks the recommendations down into concrete actions that can be implemented by
+concrete actions that can be implemented by project contributors. Its focus is
-project contributors. Its focus is on drilling down to specific, achievable work
+on drilling down to specific, achievable work that can be completed in
-that can be completed in constrained blocks of time. Ultimately, the
+constrained blocks of time. Ultimately, the implementation items are decomposed
-implementation items are decomposed into a series of [issues][issues-doc] and
+into a series of [issues] and entered as GitHub [project-doc-website]/issues.
-entered as GitHub [issues][project-doc-website]/issues.
 
-## How to use this document
+### How to use this document
 
 Readers interested only in actionable improvements should skip this document and
-read the [implementation plan][implementation-doc] and [issues
+read the **[implementation] plan** and **[issues] list**.
-list][issues-doc].
 
 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][project-heading]
+- [Project documentation](?TODO=ADD-URL)
-- [Contributor documentation][contributor-heading]
+- [Contributor documentation](?TODO=ADD-URL)
-- [Website and documentation infrastructure][website-heading]
+- [Website and documentation infrastructure](?TODO=ADD-URL)
 
 Examples of CNCF documentation that demonstrate the analysis criteria are linked
-from the [criteria][criteria-doc] specification.
+from the [criteria] specification.
 
-### Recommendations, requirements, and best practices
+#### Recommendations, requirements, and best practices
 
 This analysis measures documentation against CNCF project maturity standards,
 and suggests possible improvements. In most cases there is more than one way to
@@ -127,47 +133,39 @@ 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.
 
-# Project documentation
+## Project documentation
 
-<!-- Pick the CNCF maturity level of the project: -->
+> AUTHOR NOTE: Pick the CNCF maturity level of the project:
 
 _PROJECT_ is a **graduated** project of CNCF. This means that the project should
-have [_very high_][criteria-doc] standards for documentation.
+have [_very high_][criteria] standards for documentation.
 
-<!-- or -->
+> AUTHOR NOTE: or
 
 _PROJECT_ is an **incubating** project of CNCF. This means that the project
-should be [_developing_][criteria-doc] professional-quality documentation
+should be [_developing_][criteria] professional-quality documentation alongside
-alongside the project code.
+the project code.
 
-| Criterion                  | Rating (1-5)   |
+| Criterion                  | [Rating (1-5)] |
 | -------------------------- | -------------- |
-| Information architecture   | (rating value) |
+| Information architecture   | [rating (1-5)] |
-| New user content           | (rating value) |
+| New user content           | [rating (1-5)] |
-| Content maintainability    | (rating value) |
+| Content maintainability    | [rating (1-5)] |
-| Content creation processes | (rating value) |
+| Content creation processes | [rating (1-5)] |
-| Inclusive language         | (rating value) |
+| Inclusive language         | [rating (1-5)] |
 
-<!-- Rating values:
+### Comments
-1 - not present
-2 - needs improvement
-3 - meets standards
-4 - meets or exceeds standards
-5 - exemplary
--->
 
-## Comments
+> AUTHOR NOTE: make any overall comments about the Project Documentation here.
-
-<!--
-Make any overall comments about the Project Documentation here.
--->
 
 The following sections contain brief assessments of each element of the Project
 Documentation rubric.
 
-<!-- For each heading below, discuss how well the in-scope items, and especially the technical documentation, meet these criteria. (Criteria are copied from criteria.md) -->
+> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and
+> especially the technical documentation, meet these criteria. (Criteria are
+> copied from criteria.md)
 
-### Information architecture
+#### Information architecture
 
 The overall structure (pages/subpages/sections/subsections) of your project
 documentation. We evaluate on the following:
@@ -186,7 +184,7 @@ documentation. We evaluate on the following:
 - If the product exposes an API, is there a complete reference?
 - Is content up to date and accurate?
 
-### New user content
+#### New user content
 
 New users are the most avid users of documentation, and need content
 specifically for them. We evaluate on the following:
@@ -200,7 +198,7 @@ specifically for them. We evaluate on the following:
   top of your information architecture?
 - Is there easily copy-pastable sample code or other example content?
 
-### Content maintainability & site mechanics
+#### Content maintainability & site mechanics
 
 As a project scales, concerns like localized (translated) content and versioning
 become large maintenance burdens, particularly if you don’t plan for them.
@@ -212,7 +210,7 @@ We evaluate on the following:
   directory structure? Is a localization framework present?
 - Do you have a clearly documented method for versioning your content?
 
-### Content creation processes
+#### Content creation processes
 
 Documentation is only as useful as it is accurate and well-maintained, and
 requires the same kind of review and approval processes as code.
@@ -225,7 +223,7 @@ We evaluate on the following:
 - Who reviews and approves documentation pull requests?
 - Does the website have a clear owner/maintainer?
 
-### Inclusive language
+#### Inclusive language
 
 Creating inclusive project communities is a key goal for all CNCF projects.
 
@@ -236,60 +234,55 @@ We evaluate on the following:
   [Inclusive Naming Initiative](https://inclusivenaming.org) website?
 - Does the project use language like "simple", "easy", etc.?
 
-## Recommendations
+### Recommendations
 
-<!-- Write general recommendations based on the comments from the previous section. -->
+> AUTHOR NOTE: Write general recommendations based on the comments from the
+> previous section.
 
-### Information architecture
+#### Information architecture
 
-### New user content
+#### New user content
 
-### Content maintainability & site mechanics
+#### Content maintainability & site mechanics
 
-### Content creation processes
+#### Content creation processes
 
-### Inclusive language
+#### Inclusive language
 
-# Contributor documentation
+## Contributor documentation
 
-<!-- Pick the CNCF maturity level of the project: -->
+> AUTHOR NOTE: Pick the CNCF maturity level of the project:
 
 _PROJECT_ is a **graduated** project of CNCF. This means that the project should
-have [_very high_][criteria-doc] standards for documentation.
+have [_very high_][criteria] standards for documentation.
 
-<!-- or -->
+> AUTHOR NOTE: or
 
 _PROJECT_ is an **incubating** project of CNCF. This means that the project
-should be [_developing_][criteria-doc] professional-quality documentation
+should be [_developing_][criteria] professional-quality documentation alongside
-alongside the project code.
+the project code.
 
-| Criterion                                 | Rating (1-5)   |
+| Criterion                                 | [Rating (1-5)] |
 | ----------------------------------------- | -------------- |
-| Communication methods documented          | (rating value) |
+| Communication methods documented          | [rating (1-5)] |
-| Beginner friendly issue backlog           | (rating value) |
+| Beginner friendly issue backlog           | [rating (1-5)] |
-| “New contributor” getting started content | (rating value) |
+| “New contributor” getting started content | [rating (1-5)] |
-| Project governance documentation          | (rating value) |
+| Project governance documentation          | [rating (1-5)] |
 
-<!-- Rating values:
+### Comments
-1 - not present
-2 - needs improvement
-3 - meets standards
-4 - meets or exceeds standards
-5 - exemplary
--->
 
-## Comments
+> AUTHOR NOTE: make any overall comments about the Contributor Documentation
-
+> here.
-<!--
-Make any overall comments about the Contributor Documentation here.
--->
 
 The following sections contain brief assessments of each element of the
 Contributor Documentation rubric.
 
-<!-- For each heading below, discuss how well the in-scope items meet these criteria. Keep in mind that much of the contributor documentation might be contained in the documentation repository. (Criteria are copied from criteria.md) -->
+> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet
+> these criteria. Keep in mind that much of the contributor documentation might
+> be contained in the documentation repository. (Criteria are copied from
+> criteria.md)
 
-### Communication methods documented
+#### Communication methods documented
 
 One of the easiest ways to attract new contributors is making sure they know how
 to reach you.
@@ -303,7 +296,7 @@ We evaluate on the following:
   join those meetings?
 - Are mailing lists documented?
 
-### Beginner friendly issue backlog
+#### Beginner friendly issue backlog
 
 We evaluate on the following:
 
@@ -313,7 +306,7 @@ We evaluate on the following:
 - Are issues well-documented (i.e., more than just a title)?
 - Are issues maintained for staleness?
 
-### New contributor getting started content
+#### New contributor getting started content
 
 Open source is complex and projects have many processes to manage that. Are
 processes easy to understand and written down so that new contributors can jump
@@ -325,7 +318,7 @@ We evaluate on the following:
 - Is there a document specifically for new contributors/your first contribution?
 - Do new users know where to get help?
 
-### Project governance documentation
+#### Project governance documentation
 
 One of the CNCF’s core project values is open governance.
 
@@ -333,68 +326,65 @@ We evaluate on the following:
 
 - Is project governance clearly documented?
 
-## Recommendations
+### Recommendations
 
-<!-- Write general recommendations based on the comments from the previous section. -->
+> AUTHOR NOTE: Write general recommendations based on the comments from the
+> previous section.
 
-### Communication methods documented
+#### Communication methods documented
 
-### Beginner friendly issue backlog
+#### Beginner friendly issue backlog
 
-### New contributor getting started content
+#### New contributor getting started content
 
-### Project governance documentation
+#### Project governance documentation
 
-# Website and infrastructure
+## Website and infrastructure
 
-<!-- Pick the CNCF maturity level of the project: -->
+> AUTHOR NOTE: Pick the CNCF maturity level of the project:
 
 _PROJECT_ is a **graduated** project of CNCF. This means that the project should
-have [_very high_][criteria-doc] standards for documentation.
+have [_very high_][criteria] standards for documentation.
 
-<!-- or -->
+> AUTHOR NOTE: or
 
 _PROJECT_ is an **incubating** project of CNCF. This means that the project
-should be [_developing_][criteria-doc] professional-quality documentation
+should be [_developing_][criteria] professional-quality documentation alongside
-alongside the project code.
+the project code.
 
-| Criterion                                   | Rating (1-5)   |
+| Criterion                                   | [Rating (1-5)] |
 | ------------------------------------------- | -------------- |
-| Single-source for all files                 | (rating value) |
+| Single-source for all files                 | [rating (1-5)] |
-| Meets min website req. (for maturity level) | (rating value) |
+| Meets min website req. (for maturity level) | [rating (1-5)] |
-| Usability, accessibility, and design        | (rating value) |
+| Usability, accessibility, and design        | [rating (1-5)] |
-| Branding and design                         | (rating value) |
+| Branding and design                         | [rating (1-5)] |
-| Case studies/social proof                   | (rating value) |
+| Case studies/social proof                   | [rating (1-5)] |
-| SEO, Analytics, and site-local search       | (rating value) |
+| SEO, Analytics, and site-local search       | [rating (1-5)] |
-| Maintenance planning                        | (rating value) |
+| Maintenance planning                        | [rating (1-5)] |
-| A11y plan & implementation                  | (rating value) |
+| A11y plan & implementation                  | [rating (1-5)] |
-| Mobile-first plan & impl.                   | (rating value) |
+| Mobile-first plan & impl.                   | [rating (1-5)] |
-| HTTPS access & HTTP redirect                | (rating value) |
+| HTTPS access & HTTP redirect                | [rating (1-5)] |
-| Google Analytics 4 for production only      | (rating value) |
+| Google Analytics 4 for production only      | [rating (1-5)] |
-| Indexing allowed for production server only | (rating value) |
+| Indexing allowed for production server only | [rating (1-5)] |
-| Intra-site / local search                   | (rating value) |
+| Intra-site / local search                   | [rating (1-5)] |
-| Account custodians are documented           | (rating value) |
+| Account custodians are documented           | [rating (1-5)] |
 
-<!-- Rating values:
+### Comments
-1 - not present
-2 - needs improvement
-3 - meets standards
-4 - meets or exceeds standards
-5 - exemplary
--->
 
-## Comments
+> AUTHOR NOTE: make any overall comments about the Website and documentation
-
+> infrastructure here.
-<!--
-Make any overall comments about the Website and documentation infrastructure here.
--->
 
 The following sections contain brief assessments of each element of the Website
 and documentation infrastructure rubric.
 
-<!-- For each heading below, discuss how well the in-scope items meet these criteria. Keep in mind that much of the website infrastructure criteria depend on the tools (static site generator, website framework and hosting, analytics tools, etc.) and processes (project CI, release procedures, goverance, etc.) used to produce the documentation. (Criteria are copied from criteria.md) -->
+> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet
+> these criteria. Keep in mind that much of the website infrastructure criteria
+> depend on the tools (static site generator, website framework and hosting,
+> analytics tools, etc.) and processes (project CI, release procedures,
+> goverance, etc.) used to produce the documentation. (Criteria are copied from
+> criteria.md)
 
-### Single-source requirement
+#### Single-source requirement
 
 Source files for _all website pages_ should reside in a single repo. Among other
 problems, keeping source files in two places:
@@ -411,27 +401,30 @@ submodules][git-submodules].
 If a project chooses to keep source files in multiple repos, they need a clearly
 documented strategy for managing mirrored files and new contributions.
 
-### Minimal website requirements
+#### Minimal website requirements
 
 Listed here are the minimal website requirements for projects based on their
 [maturity level][maturity-level], either incubating or graduated. (These are the
 only two levels for which a tech docs analysis can be requested.)
 
+<!-- markdownlint-disable line-length -->
+
 | Criterion                     | Incubating Requirement                                  | Graduated Requirement                     |
-| ---------------------------------------- | ------------------------------------------------------- | ----------------------------------------- |
+| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- |
-| [Website guidelines][website-guidelines] | All guidelines satisfied                                | All guidelines satisfied                  |
+| [Website guidelines]          | All guidelines satisfied                                | All guidelines satisfied                  |
-| [Docs analysis][analysis-doc] (this)     | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed           |
+| **Docs analysis** (this)      | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed           |
 | **Project doc**: stakeholders | Roles identified and doc needs documented               | All stakeholder need identified           |
 | **Project doc**: hosting      | Hosted directly                                         | Hosted directly                           |
 | **Project doc**: user docs    | Comprehensive, addressing most stakeholder needs        | Fully addresses needs of key stakeholders |
 
+<!-- markdownlint-enable line-length -->
+
 [git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
-[website-guidelines]: ../../website-guidelines-checklist.md
 [maturity-level]:
   https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations
 [cncf-servicedesk]: https://servicedesk.cncf.io
 
-### Usability, accessibility and devices
+#### Usability, accessibility and devices
 
 Most CNCF websites are accessed from mobile and other non-desktop devices at
 least 10-20% of the time. Planning for this early in your website's design will
@@ -456,7 +449,7 @@ It is up to each project to set their own guidelines.
 
 [accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility
 
-### Branding and design
+#### Branding and design
 
 CNCF seeks to support enterprise-ready open source software. A key aspect of
 this is branding and marketing.
@@ -468,7 +461,7 @@ We evaluate on the following:
 - Is the brand used across the website consistently?
 - Is the website’s typography clean and well-suited for reading?
 
-### Case studies/social proof
+#### Case studies/social proof
 
 One of the best ways to advertise an open source project is to show other
 organizations using it.
@@ -482,7 +475,7 @@ We evaluate on the following:
 - Are there community talks for the project and are they present on the website?
 - Is there a logo wall of users/participating organizations?
 
-### SEO, Analytics and site-local search
+#### SEO, Analytics and site-local search
 
 SEO helps users find your project and it's documentation, and analytics helps
 you monitor site traffic and diagnose issues like page 404s. Intra-site search,
@@ -502,7 +495,7 @@ We evaluate on the following:
 - Are the current custodian(s) of the following accounts clearly documented:
   analytics, Google Search Console, site-search (such as Google CSE or Algolia)
 
-### Maintenance planning
+#### Maintenance planning
 
 Website maintenance is an important part of project success, especially when
 project maintainers aren’t web developers.
@@ -515,43 +508,49 @@ We evaluate on the following:
 - Are site build times reasonable?
 - Do site maintainers have adequate permissions?
 
-### Other
+#### Other
 
 - Is your website accessible via HTTPS?
 - Does HTTP access, if any, redirect to HTTPS?
 
-## Recommendations
+### Recommendations
 
-<!-- Write general recommendations based on the comments from the previous section. -->
+> AUTHOR NOTE: Write general recommendations based on the comments from the
+> previous section.
 
-### Single-source requirement
+#### Single-source requirement
 
-### Minimal website requirements
+#### Minimal website requirements
 
-### Usability, accessibility and devices
+#### Usability, accessibility and devices
 
-### Branding and design
+#### Branding and design
 
-### Case studies/social proof
+#### Case studies/social proof
 
-### SEO, Analytics and site-local search
+#### SEO, Analytics and site-local search
 
-### Maintenance planning
+#### Maintenance planning
 
-### Other
+#### Other
 
-<!--- References --->
+#### References and notes
 
-[project-website]: #?_PROJECT-WEBSITE_
+##### Rating values
-[project-doc-website]: #?_PROJECT-DOC-URL_
+
-[criteria-doc]: ../criteria.md
+The numeric rating values used in this document are as follows
-[implementation-template]: ./implementation.md
+
-[issues-template]: ./issue-template.md
+1. Not present
-[umbrella-template]: ./umbrella-issue.md
+2. Needs improvement
-[implementation-doc]: #?_PROJECT_-implementation.md
+3. Meets standards
-[issues-doc]: #?_PROJECT_-issues.md
+4. Meets or exceeds standards
-[project-heading]: #project-documentation
+5. Exemplary
-[contributor-heading]: #contributor-documentation
+
-[website-heading]: #website
+[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
+[website guidelines]: ../../website-guidelines-checklist.md

docs/analysis/templates/implementation.md

@@ -3,15 +3,17 @@ title: Implementing _PROJECT_ Doc Improvements
 tags: _PROJECT_
 ---
 
-# Introduction
+<!-- markdownlint-disable no-duplicate-heading -->
+
+## Introduction
 
 This document provides actionable suggestions for improving the _PROJECT_
 technical documentation.
 
 For an analysis and general discussion of recommendations on _PROJECT_ technical
-documentation, see [_PROJECT_-analysis.md][].
+documentation, see [analysis.md](analysis.md).
 
-## Recommendations, requirements, and best practices
+### Recommendations, requirements, and best practices
 
 This analysis measures documentation against CNCF project maturity standards and
 suggests possible improvements. In most cases there is more than one way to do
@@ -26,20 +28,22 @@ such, and pertain to legal requirements such as copyright and licensing issues.
 
 The top-level documentation recommendations for this project are:
 
-<!-- Provide a summary or outline of the recommendations. Depending on the analysis findings, recommended actions might be organized into two or three high-level items that contain multiple actions, or might just be a list of independent changes. For examples, see a completed implementation plan such as 0008-Backstage or 0010-etcd. -->
+> AUTHOR NOTE: Provide a summary or outline of the recommendations. Depending on
+> the analysis findings, recommended actions might be organized into two or
+> three high-level items that contain multiple actions, or might just be a list
+> of independent changes. For examples, see a completed implementation plan such
+> as 0008-Backstage or 0010-etcd.
 
-# High-level action 1
+## High-level action 1
 
-## Issue 1
+### Issue 1
 
-## Issue 2
+### Issue 2
 
-# High-level action 2
+## High-level action 2
 
-## Issue 1
+### Issue 1
 
-## Issue 2
+### Issue 2
-
-<!--- References --->
 
 [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119

docs/analysis/templates/issue.md

@@ -3,39 +3,53 @@ title: _PROJECT_ Issue
 tags: _PROJECT_
 ---
 
-<!-- This template provides one possible format for the individual issues filed in the Issues of a project repository. Within the CNCF tech docs repo, include all issues in one document, `_PROJECT_-issues.md`. See any completed analysis for an example. -->
+> AUTHOR NOTE: This template provides one possible format for the individual
+> issues filed in the Issues of a project repository. Within the CNCF tech docs
+> repo, include all issues in one document, `_PROJECT_-issues.md`. See any
+> completed analysis for an example.
 
-# Overview
+## Overview
 
-<!-- Summarize the documentation changes prescribed by this issue. -->
+> AUTHOR NOTE:
+>
+> - Summarize the documentation changes prescribed by this issue.
+> - For the audience, provide the user role to which the issue is most
+>   applicable.
 
-Audience: <!-- Provide the user role to which the issue is most applicable. -->
+Audience:
 
 Type:
 
-<!-- What type of documentation topic the change affects. One of Task, Reference, or Conceptual. -->
+> AUTHOR NOTE: What type of documentation topic the change affects. One of Task,
+> Reference, or Conceptual.
 
-# Context
+## Context
 
-<!-- This is boilerplate text linking back to the doc analysis. -->
+> AUTHOR NOTE: This is boilerplate text linking back to the doc analysis.
 
 This issue tracks recommended changes resulting from an analysis of the etcd
 documentation commissioned by CNCF. The analysis and supporting documents are
 here: <https://github.com/cncf/techdocs/tree/main/analyses> under
 `00NN-project`.
 
-# Possible Implementation
+## Possible Implementation
 
-<!-- Include a bullet list of links to pages that are affected by the change: -->
+> AUTHOR NOTE: Include a bullet list of links to pages that are affected by the
+> change:
 
 Related material in the current doc:
 
 - For example,
   `https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials`
 
-<!-- Describe in detail a suggested way to achieve the goals of the issue. This should be specific enough to provide a contributor with a recipe for making the change; however, the contributor should feel free to solve the problem differently if they have an idea how it should be done. -->
+> AUTHOR NOTE: Describe in detail a suggested way to achieve the goals of the
+> issue. This should be specific enough to provide a contributor with a recipe
+> for making the change; however, the contributor should feel free to solve the
+> problem differently if they have an idea how it should be done.
+>
+> An EXAMPLE is provided next.
 
-Suggested changes: <!-- (example) -->
+Suggested changes:
 
 Use the following outline to write a procedure for each task:
 

docs/analysis/templates/issues-list.md

@@ -0,0 +1,52 @@
+---
+title: _PROJECT_ Umbrella Issue and Issues List
+tags: _PROJECT_
+---
+
+## Overview
+
+> AUTHOR NOTES:
+>
+> - Provide an outline or high-level description of the recommended changes.
+>   Note any general patterns that occur throughout the documentation, such as a
+>   lack of step-by-step procedures.
+>
+> -Items might be disjoint and unrelated; that's OK. If there are high-level
+> items that must be broken down into smaller issues, use the high-level items
+> to organize the issues in this plan. Otherwise, list issues in order from the
+> analysis document. This is an improvement plan, not a legal brief.
+>
+> - The following is boilerplate language to include in the umbrella issue in
+>   the repo:
+
+This issue tracks recommended changes resulting from an analysis of the
+_PROJECT_ documentation commissioned by CNCF. The analysis and supporting
+documents are here: <https://github.com/cncf/techdocs/tree/main/analyses> under
+`00NN-project`.
+
+The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo:
+<https://github.com/cncf/techdocs/issues>
+
+## Umbrella issue
+
+> AUTHOR NOTE: Link to the umbrella issue in the project's documentation repo
+
+## Issues
+
+This is a list of issues representing the recommended work on the _PROJECT_
+website and technical documentation.
+
+> AUTHOR NOTE: Consider using the [issue](issue.md) template.
+
+### Issue: Item 1
+
+> AUTHOR NOTE: Summarize the documentation changes prescribed by this issue. Use
+> enough detail to estimate the scope of the issue. Fine-grained detail can go
+> in the issue itself. In the GitHub umbrella issue, link to the sub-issue using
+> a Markdown checkbox as shown below.
+
+- [ ] `https://github.com/_PROJECT_/repo/issues/NNN`
+
+### Issue: Item 2
+
+> AUTHOR NOTE: ... and so on.

docs/analysis/templates/umbrella-issue.md

@@ -1,35 +0,0 @@
----
-title: _PROJECT_ Umbrella Issue
-tags: _PROJECT_
----
-
-# Overview
-
-<!-- Provide an outline or high-level description of the recommended changes. Note any general patterns that occur throughout the documentation, such as a lack of step-by-step procedures. -->
-
-<!-- Items might be disjoint and unrelated; that's OK. If there are high-level items that must be broken down into smaller issues, use the high-level items to organize the issues in this plan. Otherwise, list issues in order from the analysis document. This is an improvement plan, not a legal brief. -->
-
-<!-- The following is boilerplate language to include in the umbrella issue in the repo: -->
-
-This issue tracks recommended changes resulting from an analysis of the
-_PROJECT_ documentation commissioned by CNCF. The analysis and supporting
-documents are here: <https://github.com/cncf/techdocs/tree/main/analyses> under
-`00NN-project`.
-
-The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo:
-<https://github.com/cncf/techdocs/issues>
-
-# Issues
-
-This is a list of issues representing the recommended work on the _PROJECT_
-website and technical documentation.
-
-## Issue: Item 1
-
-<!-- Summarize the documentation changes prescribed by this issue. Use enough detail to estimate the scope of the issue. Fine-grained detail can go in the issue itself. In the GitHub umbrella issue, link to the sub-issue using a Markdown checkbox as shown below. -->
-
-- [ ] `https://github.com/_PROJECT_/repo/issues/NNN`
-
-## Issue: Item 2
-
-<!-- ... and so on. -->

docs/analytics.md

@@ -95,8 +95,8 @@ Follow these steps:
       site tag. Perform the remaining steps from your GA4 console.
     - Select **Admin** > **Data stream**
     - Select the (only) data stream to view its details.
-    - 📋 **Copy the **measurement ID\*\*\*\*, you'll need it later, and paste it
+    - 📋 **Copy the _measurement ID_**, you'll need it later, and paste it into
-      into the appropriate row of the [status table][].
+      the appropriate row of the [status table][].
 
 5.  Rename your UA property by adding the `- UA` suffix. From the UA console:
 
@@ -189,7 +189,6 @@ is using.
   https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics
 [analytics.js]: https://support.google.com/analytics/answer/10268458
 [connected]: https://support.google.com/analytics/answer/9973999
-[etcd.io issue #595]: https://github.com/etcd-io/website/issues/595
 [docsy]: https://www.docsy.dev
 [docusaurus]: https://docusaurus.io/
 [ga4-dev]: https://developers.google.com/analytics/devguides/migration
@@ -199,8 +198,6 @@ is using.
 [gtag.js]: https://support.google.com/analytics/answer/10220869
 [issue #108]: https://github.com/cncf/techdocs/issues/108
 [migration-help]: https://support.google.com/analytics/answer/10759417
-[opentelemetry.io/layouts/partials/google-analytics.html]:
-  https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html
 [stage 2]: #stage-2---configure-the-ga4-id-as-the-main-analytics-id
 [status table]:
   https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA

docs/repo-setup.md

@@ -29,38 +29,35 @@ For documentation this means you must:
 1. Add copyright notices for both the code and the docs to the repository's
    `README` and the website's footer
 
-For the repository:
+   For the repository:
 
-```
+   ```markdown
-# License
+   # License
 
-$PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE).
+   $PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE).
 
-The #PROJECT_NAME documentation is licensed under a [CC-BY-4.0 license](./LICENSE-docs).
+   The #PROJECT_NAME documentation is licensed under a
-```
+   [CC-BY-4.0 license](./LICENSE-docs).
+   ```
 
-For the footer:
+   For the footer, see
-
+   [cncf/hugo-netlify-starter](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html)
-- [`cncf/hugo-netlify-starter`](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html)
    contains a basic implementation, where the year and project name are
    parameterized.
 
 2. Add both the CC-BY-4.0 `LICENCE-docs` and Apache 2.0 `LICENCE` files to the
-   root directory of the documentation
+   root directory of the documentation. For a plain text versions of both, see
-   - Plain text versions of both
+   [cncf/project-template](https://github.com/cncf/project-template)
-     [here](https://github.com/cncf/project-template)
 
-For more information:
+For more information, see:
 
-- Read
+- [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md)
-  [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md)
+- [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy)
-- And the
-  [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy)
 
 ## README
 
 All docs repositories should have a README file that includes build
 instructions. Look at [Longhorn's](https://github.com/longhorn/website) for an
 example, and the
-[`cncf/project-template`](https://github.com/cncf/project-template) for
+[cncf/project-template](https://github.com/cncf/project-template) for
 boilerplate.

docs/searching-documentation.md

@@ -1,5 +1,7 @@
 # Documentation Search
 
+<!-- markdownlint-disable no-duplicate-heading -->
+
 This page describes some common alternatives for static site search.
 
 - [Google search](#programmable-search-engine-by-google)

docs/versioning-documentation.md

@@ -1,5 +1,7 @@
 # Technical Documentation Versioning with Hugo & Netlify
 
+<!-- markdownlint-disable no-emphasis-as-heading -->
+
 Technical Documents Versioning is an intersection of:
 
 **Changes** + **Language** + **Navigation** + **Search**
@@ -78,7 +80,7 @@ site.
 Each version of the documentation is placed in its own folder. This is probably
 the easiest way to start versioning.
 
-```
+```text
 content
 └── docs
     ├── _index.md
@@ -160,8 +162,7 @@ Scores high on:
 
 Same style of dropdown function as above, but made simpler because of the
 configuration:
-
+<https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html>
-https://kubernetes.io `website/layouts/partials/navbar-version-selector.html`
 
 ```html
 <div
@@ -181,7 +182,7 @@ Pursley et al. (2020, L4-L9)<sup>[4](#footnote4)</sup>
 The dropdown example is made simpler because the config is more complex and
 because the server setup is more complex.
 
-https://kubernetes.io `website/config.toml`
+<https://github.com/kubernetes/website/blob/main/hugo.toml>
 
 ```toml
 [[params.versions]]

docs/website-guidelines-checklist.md

@@ -8,8 +8,7 @@ all projects
 - [ ] 1. Website should be [hosted in an open source repo](./repo-setup.md)
   - [ ] Hosted in the same organization as the main project
   - [ ] Setup [DCO](https://github.com/apps/dco) or CLA (DCO recommended)
-         CNCF's IP policy
+        [CNCF's IP policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy)
-        (https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy)
         requires all projects to use either CLA (Contributor License Agreements)
         or [DCO (Developer Certificate of Origin)](https://github.com/apps/dco).
         Unless there's a strong necessity to use CLA, we encourage projects to

package.json

@@ -4,11 +4,20 @@
   "description": "Resources provided by the CNCF Technical Documentation team.",
   "scripts": {
     "_check:format:any": "npx prettier --check --ignore-path ''",
+    "_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)",
     "_check:format": "npx prettier --check .",
+    "_check:links": "npx markdown-link-check --config .markdown-link-check.json",
+    "_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}",
+    "_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}",
+    "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml",
+    "_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'",
+    "_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'",
+    "_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010|/0011'",
     "_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: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",
@@ -21,10 +30,12 @@
   "devDependencies": {
     "cspell": "^8.8.4",
     "markdown-link-check": "^3.12.2",
-    "prettier": "^3.3.1"
+    "markdownlint": "^0.34.0",
+    "markdownlint-cli": "^0.41.0",
+    "prettier": "^3.3.2"
   },
   "private": true,
-  "spelling": "cSpell:ignore loglevel -",
+  "spelling": "cSpell:ignore ACMR loglevel -",
   "prettier": {
     "proseWrap": "always",
     "singleQuote": true