From 47a98406005904875d0fd632808a6b9ff2126079 Mon Sep 17 00:00:00 2001
From: Nahian Pathan <npathan@redhat.com>
Date: Thu, 25 Apr 2024 10:51:55 -0400
Subject: [PATCH] clean up markdown for linter

---
 .markdownlint-cli2.yaml                       | 13 ++++++++
 README.md                                     | 32 +++++++++----------
 ...nfigGuide.md => reference-config-guide.md} |  1 -
 docs/{UserGuide.md => user-guide.md}          | 13 +++++---
 4 files changed, 37 insertions(+), 22 deletions(-)
 create mode 100644 .markdownlint-cli2.yaml
 rename docs/{ReferenceConfigGuide.md => reference-config-guide.md} (99%)
 rename docs/{UserGuide.md => user-guide.md} (95%)

diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
new file mode 100644
index 00000000..0a137817
--- /dev/null
+++ b/.markdownlint-cli2.yaml
@@ -0,0 +1,13 @@
+# See https://github.com/DavidAnson/markdownlint#optionsconfig
+# and https://github.com/DavidAnson/markdownlint-cli2
+
+config:
+  line-length:
+    line_length: 300
+    code_blocks: false
+
+  ul-style: consistent
+  emphasis-style: true
+  strong-style: true
+  no-space-in-emphasis: true
+  no-blanks-blockquote: false
diff --git a/README.md b/README.md
index 6537b541..63496d1d 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ directly by the customer. The reference configuration is the engineered set of c
 has been sufficiently annotated to describe
 expected user variations versus required content.
 
-```
+```shell
 ┌──────────────────┐                 ┌──────────────────┐
 │                  │ Adaptation to   │                  │
 │     Published    │    user env     │   Deployed user  │
@@ -64,9 +64,9 @@ Existing tools meet some of this need but fall short of the goals
 
 - kubectl diff: This subcommand allows comparison of a live cluster against a known configuration.
   There are three shortcomings we need to address:
-    - Ability to handle expected user variation and optional versus required content.
-    - Ability to handle 1 to N mappings where users have multiple instances of a CR which should be validated
-    - Consumption of an offline representation of the cluster configuration.
+  - Ability to handle expected user variation and optional versus required content.
+  - Ability to handle 1 to N mappings where users have multiple instances of a CR which should be validated
+  - Consumption of an offline representation of the cluster configuration.
 - `<get cr> | <key sorting> | diff` : There are various ways of chaining together existing tools
   to obtain, correlate, and compare/diff two YAML objects. These methods fall short in similar ways as
   the `kubectl diff`
@@ -100,7 +100,7 @@ The design and implementation of this subcommand is guided by the following goal
 
 ### Terminology
 
-* **drift** -- A significant delta/difference which needs to be brought into compliance or undergo further
+- **drift** -- A significant delta/difference which needs to be brought into compliance or undergo further
   review/assessment
 
 ### Validation Tool Implementation
@@ -132,9 +132,9 @@ of variability as defined by the reference configuration (ie the "drift"). The t
 this drift for additional analysis/review by the user. In addition to the CR comparison output the tool will output a
 report detailing:
 
-* Input configuration CRs with no match in the reference
-* Required reference CRs with no match in the input configuration
-* Number of drifts found
+- Input configuration CRs with no match in the reference
+- Required reference CRs with no match in the input configuration
+- Number of drifts found
 
 #### Inputs
 
@@ -160,8 +160,8 @@ automatic of correlation, meaning manual matches override matches by similar val
 
 `kubectl cluster-compare` gets as input a diff config that contains an option to specify manual matches between cluster resources
 and resource templates. The matches can be added to the config as pairs of
-apiVersion_kind_namespace_name: <Template File Name>. For cluster scoped CRs that don't have a namespace the matches can
-be added as pairs of apiVersion_kind_name: <Template File Name>.
+`apiVersion_kind_namespace_name: <Template File Name>`. For cluster scoped CRs that don't have a namespace the matches can
+be added as pairs of `apiVersion_kind_name: <Template File Name>`.
 
 ##### Correlation by group of fields (apiVersion, kind, namespace and name)
 
@@ -300,8 +300,8 @@ is specific to the users cluster (not like the metadata.yaml that includes only
 reference).
 
 In the version the diff config includes an option to specify manual matches between cluster resources and resource
-templates. The matches can be added to the config as pairs of apiVersion_kind_namespace_name: <Template File Name>. For
-resources that don't have a namespace the matches can be added as pairs of apiVersion_kind_name: <Template File Name>.
+templates. The matches can be added to the config as pairs of `apiVersion_kind_namespace_name: <Template File Name>`. For
+resources that don't have a namespace the matches can be added as pairs of `apiVersion_kind_name: <Template File Name>`.
 The pairs are listed in the config under correlationSettings.manualCorrelation.correlationPairs as can be seen in the
 example below.
 
@@ -384,7 +384,7 @@ To allow easy chaining all the corealtors match the corelator interface: (includ
 
 In this Version the corealtors are created and initialized in the following chain:
 
-```
+```shell
                                                                ┌─────────────────────┐
                                                     <<use>>    │                     │
                                                   ┌──────────► │                     │
@@ -439,9 +439,9 @@ a known valid configuration. This tool does a good job of suppressing diffs in k
 (eg metadata, status, etc), however it is lacking in several critical features for the use cases in
 this enhancement:
 
-* Suppression of expected user variations
-* Handling of one-to-many matches
-* Comparison of two offline files
+- Suppression of expected user variations
+- Handling of one-to-many matches
+- Comparison of two offline files
 
 ### Command line utilities
 
diff --git a/docs/ReferenceConfigGuide.md b/docs/reference-config-guide.md
similarity index 99%
rename from docs/ReferenceConfigGuide.md
rename to docs/reference-config-guide.md
index ca4f44b1..2a5f836e 100644
--- a/docs/ReferenceConfigGuide.md
+++ b/docs/reference-config-guide.md
@@ -70,4 +70,3 @@ spec:
     tier: frontend
     {{- end }}
 ```
-
diff --git a/docs/UserGuide.md b/docs/user-guide.md
similarity index 95%
rename from docs/UserGuide.md
rename to docs/user-guide.md
index 7a718290..2fee7afa 100644
--- a/docs/UserGuide.md
+++ b/docs/user-guide.md
@@ -1,5 +1,4 @@
 
-
 # Rationale
 
 The “kubectl cluster-compare” command is capable of performing an intelligent diff between a reference configuration and
@@ -33,9 +32,9 @@ fields.
 #### Correlation by manual matches
 
 `kubectl cluster-compare` gets as input a diff config that contains an option to specify manual matches between cluster
-resources and resource templates. The matches can be added to the config as pairs of apiVersion_kind_namespace_name:
-<Template File Name>. For cluster scoped CRs that don't have a namespace the matches can be added as pairs of
-apiVersion_kind_name: <Template File Name>.
+resources and resource templates. The matches can be added to the config as pairs of `apiVersion_kind_namespace_name:
+<Template File Name>`. For cluster scoped CRs that don't have a namespace the matches can be added as pairs of
+`apiVersion_kind_name: <Template File Name>`.
 
 #### Correlation by group of fields (apiVersion, kind, namespace and name)
 
@@ -64,16 +63,20 @@ For each resource the group correlation will be done by the next logic:
 We can phrase this logic in a more general form. Each CR will be correlated to a template with an exact match in the
 largest number of fields from this group:  apiVersion, kind, namespace, name.
 
-## How it works 
+## How it works
+
 * eg how templates pull content into reference prior to compare
 
 ## Limits
+
 ## Single CR scope
+
 This tool provides a context aware diff function. In some cases the reference may further provide validation of values
 in the CRs. This validation operates within the scope of a the current CR. Any validation of values across multiple CRs
 is out of scope.
 
 ## CR validation
+
 This tool performs a diff of a CR against the reference. It does not have access to resources outside the scope of what
 is available through the cluster's API. This places validation of the configuration against underlying platform
 hardware, os configuratoin, etc (unless available through the api) out of scope.