From 679dd110ccfafbdd4d460be01e0e322fbdc8a0a5 Mon Sep 17 00:00:00 2001
From: Kirk Rodrigues <2454684+kirkrodrigues@users.noreply.github.com>
Date: Thu, 30 Jan 2025 10:03:01 -0500
Subject: [PATCH 1/3] WIP

---
 lint-configs/.markdownlint-cli2.yaml | 30 ++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 lint-configs/.markdownlint-cli2.yaml

diff --git a/lint-configs/.markdownlint-cli2.yaml b/lint-configs/.markdownlint-cli2.yaml
new file mode 100644
index 0000000..bac431a
--- /dev/null
+++ b/lint-configs/.markdownlint-cli2.yaml
@@ -0,0 +1,30 @@
+config:
+  MD003:
+    style: "atx"
+  MD004:
+    style: "asterisk"
+  MD009:
+    list_item_empty_lines: true
+    strict: true
+  MD010:
+    code_blocks: false
+    spaces_per_tab: 4
+  MD013:
+    line_length: 100
+    stern: true
+    tables: false
+  MD024:
+    siblings_only: true
+  MD035:
+    style: "---"
+  MD046:
+    style: "fenced"
+  MD048:
+    style: "backtick"
+  MD049:
+    # We choose an asterisk to avoid confusion when emphasizing text that includes underscores.
+    style: "asterisk"
+  MD052:
+    shortcut_syntax: true
+  MD055:
+    style: "leading_and_trailing"

From e726242b57bdf119e5bf61c97849df0f2e69a940 Mon Sep 17 00:00:00 2001
From: Kirk Rodrigues <2454684+kirkrodrigues@users.noreply.github.com>
Date: Thu, 1 May 2025 08:33:14 -0400
Subject: [PATCH 2/3] Update rules based on real Markdown docs.

---
 lint-configs/.markdownlint-cli2.yaml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lint-configs/.markdownlint-cli2.yaml b/lint-configs/.markdownlint-cli2.yaml
index bac431a..41271b4 100644
--- a/lint-configs/.markdownlint-cli2.yaml
+++ b/lint-configs/.markdownlint-cli2.yaml
@@ -15,6 +15,10 @@ config:
     tables: false
   MD024:
     siblings_only: true
+
+  # TODO Improve comment
+  # We use HTML tags in Mermaid diagrams.
+  MD033: false
   MD035:
     style: "---"
   MD046:
@@ -24,6 +28,11 @@ config:
   MD049:
     # We choose an asterisk to avoid confusion when emphasizing text that includes underscores.
     style: "asterisk"
+
+  # TODO Improve comment
+  # Sphinx should validate links and markdownlint doesn't support the MyST syntax for specifying
+  # arbitrary links.
+  MD051: false
   MD052:
     shortcut_syntax: true
   MD055:

From 66d21647c0739d7dc4394980ea533798f920575a Mon Sep 17 00:00:00 2001
From: Kirk Rodrigues <2454684+kirkrodrigues@users.noreply.github.com>
Date: Sat, 3 May 2025 13:31:36 -0400
Subject: [PATCH 3/3] Improve comments.

---
 lint-configs/.markdownlint-cli2.yaml | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/lint-configs/.markdownlint-cli2.yaml b/lint-configs/.markdownlint-cli2.yaml
index 41271b4..6cf2afd 100644
--- a/lint-configs/.markdownlint-cli2.yaml
+++ b/lint-configs/.markdownlint-cli2.yaml
@@ -16,8 +16,7 @@ config:
   MD024:
     siblings_only: true
 
-  # TODO Improve comment
-  # We use HTML tags in Mermaid diagrams.
+  # `false` since we sometimes need to use HTML tags (e.g., in Mermaid diagrams, etc.).
   MD033: false
   MD035:
     style: "---"
@@ -29,9 +28,8 @@ config:
     # We choose an asterisk to avoid confusion when emphasizing text that includes underscores.
     style: "asterisk"
 
-  # TODO Improve comment
-  # Sphinx should validate links and markdownlint doesn't support the MyST syntax for specifying
-  # arbitrary links.
+  # `false` since Sphinx validate links, and markdownlint doesn't support MyST-Parser's syntax for
+  # specifying explicit targets.
   MD051: false
   MD052:
     shortcut_syntax: true