feat: properly configure mdbook-lint as preprocessor

- Add .mdbook-lint.toml with proper configuration
- Temporarily disable MDBOOK010 (math detection) and MDBOOK005 (orphaned files)
  until upstream issues #141 and #142 are resolved
- Configure preprocessor correctly in book.toml
- Simplify GitHub Actions workflow - lint now runs as part of build
- Set line length to 120 chars for technical documentation
- Configuration validated with 'mdbook-lint check'

Thanks to @joshrotenberg for the quick feedback on proper configuration!

Author: joshrotenberg

.github/workflows/mdbook.yml

@@ -45,12 +45,7 @@ jobs:
         run: |
           command -v mdbook-lint || cargo install mdbook-lint
 
-      - name: Lint book
-        run: |
-          mdbook-lint lint docs/src --config-format=disabled || true
-          # Note: Linting is informational only for now due to false positives with $ in code blocks
-
-      - name: Build book
+      - name: Build book (includes linting via preprocessor)
         run: |
           cd docs
           mdbook build

docs/.mdbook-lint.toml

@@ -0,0 +1,31 @@
+# mdbook-lint configuration for redisctl documentation
+# https://github.com/joshrotenberg/mdbook-lint
+
+# Temporarily disable rules with known issues
+disabled-rules = [
+    "MDBOOK010",  # Math block detection - false positives with $ in shell code blocks (issue #141)
+    "MDBOOK005",  # Orphaned files - incorrectly checking outside src directory (issue #142)
+]
+
+# Don't fail the build on warnings during initial setup
+fail-on-warnings = false
+
+# Configure specific rules
+[rules.MD013]
+# Allow longer lines for code examples and CLI output
+line_length = 120
+
+[rules.MD024]
+# Allow duplicate headings in different sections
+enabled = true
+
+[rules.MD041]
+# Require first line to be a heading
+enabled = true
+
+# Future configuration options when issues are resolved:
+# [rules.MDBOOK005]
+# search-path = "src"  # Only check within src directory
+# 
+# [rules.MDBOOK010]  
+# skip-code-blocks = true  # Skip math detection in code blocks

docs/book.toml

@@ -15,5 +15,7 @@ edit-url-template = "https://github.com/joshrotenberg/redisctl/edit/main/docs/{p
 enable = true
 level = 1
 
-# mdbook-lint configuration can be added here if needed
-# Currently running lint separately via CI
+# Enable mdbook-lint preprocessor
+# Configuration is in .mdbook-lint.toml
+[preprocessor.lint]
+command = "mdbook-lint"