feat: Set up markdownlint GitHub Action for automated linting (Closes #14)

.github/workflows/lint.yaml

@@ -0,0 +1,50 @@
+name: Linting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # This identifies which files changed in the specific commit or PR
+      - uses: tj-actions/changed-files@v47
+        id: changed-files
+        with:
+          files: '**/*.md'
+          separator: ","
+
+      # This runs the linter ONLY on the files identified above
+      - uses: DavidAnson/markdownlint-cli2-action@v22
+        if: steps.changed-files.outputs.any_changed == 'true'
+        with:
+          globs: ${{ steps.changed-files.outputs.all_changed_files }}
+          separator: ","
+          fix: true
+
+      # Check if anything was fixed, then Commit & Push
+      - name: Commit and push fixes
+        if: always() && steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          # Configure the bot's identity
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Check if the linter modified any files
+          if [[ -n $(git status -s) ]]; then
+            git add .
+            git commit -m "style: auto-fix markdown formatting"
+            git push origin HEAD:${{ github.head_ref }}
+          fi

CONTRIBUTING.md

@@ -177,7 +177,12 @@ chore: update mkdocs dependencies
 
 ### Linting
 
-The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. Key settings:
+The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`.
+
+**Automated Checks:**
+We have a GitHub Action that checks for formatting errors on Pull Requests. To avoid flagging legacy issues, **it only checks files that you have modified.**
+
+**Key Rules:**
 
 - 4-space indentation for lists (`MD007`).
 - No hard tab restrictions disabled.
@@ -186,13 +191,19 @@ The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with
 - Allowed code blocks without language specification (`MD040`).
 - Allow fenced code blocks, as this commonly errors when indented (see [discussion](https://github.com/DavidAnson/markdownlint/issues/327)).
 
-For faster PR review, you may want to run linting locally; we do have a PR Action in place as well. First install markdownlint, then run
+**Local Testing**
+For faster PR review, you may want to run linting locally. We recommend installing `markdownlint-cli2` or the VS Code extension.
 
-```console
-markdownlint -c .markdownlint.json -f docs/wiki-guide/
+```bash
+# Install
+npm install markdownlint-cli2 --global
+# Run on the specific file you are editing
+markdownlint-cli2 "docs/path/to/your/file.md"
+# Fix simple errors automatically
+markdownlint-cli2 --fix "docs/path/to/your/file.md"
 ```
 
-The `-f` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `<filename>.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`).
+The `--fix` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `<filename>.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`).
 
 ### Content Review
 

lint-fail-test.md

@@ -0,0 +1,15 @@
+# Auto-Fixable Header (No space after hash)
+
+This paragraph has trailing spaces at the end.
+
+# Duplicate Header
+
+Content A
+
+# Duplicate Header
+
+Content B (Linter won't be able to fix the duplicate header but should point it out)
+
+<div class="error">
+  Inline HTML is also not auto-fixable
+</div>