Improves pre-commit hook configuration

Organizes and enhances the pre-commit configuration for better code quality and consistency.

- Groups hooks into logical sections (Spellchecking/Linting, Bibliography, Local Custom Hooks) for improved readability.
- Adds markdown linting and formatting hooks to ensure consistent markdown style.
- Refines local hook descriptions and organization for clarity.
- Validates images using pillow and rich libraries

.pre-commit-config.yaml

@@ -2,8 +2,9 @@ ci:
   skip: true
 
 repos:
+  # --- Spellchecking and Linting ---
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0  # Or latest stable
+    rev: v2.3.0
     hooks:
       - id: codespell
         name: "Check for common misspellings"
@@ -28,6 +29,26 @@ repos:
         files: ^contents/.*\.qmd$
         verbose: false
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+      - id: markdownlint
+        name: "Lint quarto markdown"
+        types: [text]
+        files: ^contents/.*\.qmd$
+        args: ["--quiet", "-c", ".mdlintconfig.yml"]
+        entry: bash -c 'markdownlint "$@" || true'
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.9
+    hooks:
+      - id: mdformat
+        name: "Format quarto markdown"
+        additional_dependencies: [mdformat-frontmatter]
+        files: ^contents/.*\.qmd$
+        pass_filenames: true
+
+  # --- Bibliography ---
   - repo: https://github.com/FlamingTempura/bibtex-tidy
     rev: v1.14.0
     hooks:
@@ -48,38 +69,17 @@ repos:
         ]
         files: ^contents/.*\.bib$
 
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.45.0
-    hooks:
-      - id: markdownlint
-        name: "Lint quarto markdown"
-        types: [text]
-        files: ^contents/.*\.qmd$
-        args: ["--quiet", "-c", ".mdlintconfig.yml"]
-        entry: bash -c 'markdownlint "$@" || true'
-
-  - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.9
-    hooks:
-      - id: mdformat
-        name: "Format quarto markdown"
-        additional_dependencies: [mdformat-frontmatter]
-        files: ^contents/.*\.qmd$
-        pass_filenames: true
-
+  # --- Local Custom Hooks ---
   - repo: local
     hooks:
-      # Configuration and setup hooks (run first)
-
-
-      # Content validation hooks (check for issues)
+      # --- Structural & Reference Validation ---
       - id: check-unreferenced-labels
         name: "Check for unreferenced labels"
         entry: python ./scripts/find_unreferenced_labels.py ./contents/core
         language: python
         additional_dependencies: []
-        files: ''
         pass_filenames: false
+        files: ''
 
       - id: check-section-ids
         name: "Check section IDs"
@@ -103,7 +103,7 @@ repos:
         pass_filenames: true
         files: ^contents/.*\.qmd$
 
-      # Formatting and cleanup hooks (fix formatting issues)
+      # --- Formatting and Cleanup ---
       - id: collapse-extra-blank-lines
         name: "Collapse extra blank lines"
         entry: python scripts/collapse_blank_lines.py
@@ -111,19 +111,21 @@ repos:
         pass_filenames: true
         files: ^contents/.*\.qmd$
 
+      # --- Image Validation ---
       - id: validate-images
         name: "Validate image files"
         entry: python scripts/check_images.py
         language: python
         language_version: python3.13
-        pass_filenames: true
-        files: ^contents/core.*\.(png|jpg|jpeg|gif)$ # need to fix for labs!
         additional_dependencies:
           - pillow
-          - rich        
-                
+          - rich
+        pass_filenames: true
+        files: ^contents/core.*\.(png|jpg|jpeg|gif)$
+
+      # --- Locked File Check (macOS specific) ---
       - id: check-locked-files
         name: "Detect locked files (uchg flag on macOS)"
         entry: bash -c 'find contents/ -type f -exec ls -lO {} + | grep -q " uchg " && { echo "❌ Locked files detected (uchg). Please unlock them before commit."; exit 1; } || exit 0'
         language: system
-        pass_filenames: false          
+        pass_filenames: false