chore(misc): add markdown lint and format (#2702)

- adds mdformat and markdownlint-cli as pre-commit hooks
- excludes markdown files under docs/, to be considered for addition
later (formatting was messing up math sections in user guides)
- cleans up links in readme
- standardizes headers in changelog

.markdownlint.yaml

@@ -0,0 +1,21 @@
+# default to true for all rules
+default: true
+
+# MD007/unordered-list-indent
+MD007:
+  indent: 4
+
+# MD033/no-inline-html
+MD033: false
+
+# MD041/first-line-h1
+MD041: false
+
+# MD013/line-length
+MD013:
+  line_length: 99
+
+# MD024/no-duplicate-heading
+MD024:
+  # Allow when nested under different parents e.g. CHANGELOG.md
+  siblings_only: true

.pre-commit-config.yaml

@@ -10,22 +10,43 @@ repos:
     rev: 1.16.0
     hooks:
       - id: blacken-docs
+
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v3.1.0
     hooks:
       - id: prettier
-        # Newer versions of node don't work on systems that have an older version of GLIBC
-        # (in particular Ubuntu 18.04 and Centos 7)
-        # EOL of Centos 7 is in 2024-06, we can probably get rid of this then.
-        # See https://github.com/scverse/cookiecutter-scverse/issues/143 and
-        # https://github.com/jupyterlab/jupyterlab/issues/12675
-        language_version: "17.9.1"
+        types: [yaml]
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.17
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-mkdocs
+          - mdformat-admon
+        exclude: |
+          (?x)^(
+            \.github/.*\.md
+            | docs/.*\.md
+          )$
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.39.0
+    hooks:
+      - id: markdownlint-fix
+        exclude: |
+          (?x)^(
+            \.github/.*\.md
+            | docs/.*\.md
+          )$
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.3.4
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:
@@ -36,6 +57,7 @@ repos:
         args: [--fix=lf]
       - id: trailing-whitespace
       - id: check-case-conflict
+
   - repo: local
     hooks:
       - id: forbid-to-commit