From 1e8f8223910f41294c16bfebea332c80fd83573c Mon Sep 17 00:00:00 2001
From: Nicholas McDonnell <50747025+mcdonnnj@users.noreply.github.com>
Date: Fri, 18 Jun 2021 03:33:26 -0400
Subject: [PATCH 1/4] Add style enforcement rules

Add rules to enforce ATX-closed headers, dashes for unordered list elements,
and `1.` for ordered list elements.
---
 .mdl_config.json | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.mdl_config.json b/.mdl_config.json
index 7a6f3f8..8266cdb 100644
--- a/.mdl_config.json
+++ b/.mdl_config.json
@@ -1,4 +1,10 @@
 {
+  "MD003": {
+    "style": "atx_closed"
+  },
+  "MD004": {
+    "style": "dash"
+  },
   "MD013": {
     "code_blocks": false,
     "tables": false
@@ -6,5 +12,8 @@
   "MD024": {
     "allow_different_nesting": true
   },
+  "MD029": {
+    "style": "one"
+  },
   "default": true
 }

From afc6bd6f6d754f8c2bc5675411535b0c61e0ec78 Mon Sep 17 00:00:00 2001
From: Nicholas McDonnell <50747025+mcdonnnj@users.noreply.github.com>
Date: Fri, 18 Jun 2021 03:37:08 -0400
Subject: [PATCH 2/4] Add rule for image headers

Add <h1> and <img> tags to the allowed list for MD033 (HTML elements) to
support using an image as the first thing in a markdown file (header image).
---
 .mdl_config.json | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/.mdl_config.json b/.mdl_config.json
index 8266cdb..38bc045 100644
--- a/.mdl_config.json
+++ b/.mdl_config.json
@@ -15,5 +15,11 @@
   "MD029": {
     "style": "one"
   },
+  "MD033": {
+    "allowed_elements": [
+      "h1",
+      "img"
+    ]
+  },
   "default": true
 }

From ce173f401d8eec4f2caf3cf8174a5b53f03222da Mon Sep 17 00:00:00 2001
From: Nicholas McDonnell <50747025+mcdonnnj@users.noreply.github.com>
Date: Fri, 18 Jun 2021 03:51:38 -0400
Subject: [PATCH 3/4] Switch to a YAML markdownlint configuration file

This converts the existing `.mdl_config.json` file to an equivalent
`.mdl_config.yaml` file. The reference in the markdownlint pre-commit hook
configuration is updated to match.

Co-authored-by: Shane Frasier <jeremy.frasier@trio.dhs.gov>
---
 .mdl_config.json        | 25 -------------------------
 .mdl_config.yaml        | 24 ++++++++++++++++++++++++
 .pre-commit-config.yaml |  2 +-
 3 files changed, 25 insertions(+), 26 deletions(-)
 delete mode 100644 .mdl_config.json
 create mode 100644 .mdl_config.yaml

diff --git a/.mdl_config.json b/.mdl_config.json
deleted file mode 100644
index 38bc045..0000000
--- a/.mdl_config.json
+++ /dev/null
@@ -1,25 +0,0 @@
-{
-  "MD003": {
-    "style": "atx_closed"
-  },
-  "MD004": {
-    "style": "dash"
-  },
-  "MD013": {
-    "code_blocks": false,
-    "tables": false
-  },
-  "MD024": {
-    "allow_different_nesting": true
-  },
-  "MD029": {
-    "style": "one"
-  },
-  "MD033": {
-    "allowed_elements": [
-      "h1",
-      "img"
-    ]
-  },
-  "default": true
-}
diff --git a/.mdl_config.yaml b/.mdl_config.yaml
new file mode 100644
index 0000000..a04720a
--- /dev/null
+++ b/.mdl_config.yaml
@@ -0,0 +1,24 @@
+---
+
+default: true
+
+MD003:
+  style: "atx_closed"
+
+MD004:
+  style: "dash"
+
+MD013:
+  code_blocks: false
+  tables: false
+
+MD024:
+  allow_different_nesting: true
+
+MD029:
+  style: "one"
+
+MD033:
+  allowed_elements:
+    - h1
+    - img
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index cf0330d..6b87ab0 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -35,7 +35,7 @@ repos:
     hooks:
       - id: markdownlint
         args:
-          - --config=.mdl_config.json
+          - --config=.mdl_config.yaml
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.3.0
     hooks:

From f2a423095efe2f1a96ce2621352ee7cb4dd0458a Mon Sep 17 00:00:00 2001
From: Nicholas McDonnell <50747025+mcdonnnj@users.noreply.github.com>
Date: Fri, 18 Jun 2021 03:59:36 -0400
Subject: [PATCH 4/4] Add comments to markdownlint configuration

Now that this is a YAML file we can add comments explaining the rule
modifications we use. This will make it easier to edit or expand in the future.
---
 .mdl_config.yaml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/.mdl_config.yaml b/.mdl_config.yaml
index a04720a..a2f08f3 100644
--- a/.mdl_config.yaml
+++ b/.mdl_config.yaml
@@ -1,24 +1,40 @@
 ---
 
+# Default state for all rules
 default: true
 
+# MD003/heading-style/header-style - Heading style
 MD003:
+  # Enforce the ATX-closed style of header
   style: "atx_closed"
 
+# MD004/ul-style - Unordered list style
 MD004:
+  # Enforce dashes for unordered lists
   style: "dash"
 
+# MD013/line-length - Line length
 MD013:
+  # Do not enforce for code blocks
   code_blocks: false
+  # Do not enforce for tables
   tables: false
 
+# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the
+# same content
 MD024:
+  # Allow headers with the same content as long as they are not in the same
+  # parent heading
   allow_different_nesting: true
 
+# MD029/ol-prefix - Ordered list item prefix
 MD029:
+  # Enforce the `1.` style for ordered lists
   style: "one"
 
+# MD033/no-inline-html - Inline HTML
 MD033:
+  # The h1 and img elements are allowed to permit header images
   allowed_elements:
     - h1
     - img