docs: fix mdbook-lint issues and improve CLI reference formatting

- Fixed MD022, MD032, MD047 issues in introduction.md manually
- Updated doc generation script to use proper code block syntax (text)
- Fixed CLI reference documentation formatting issues
- Created comprehensive bug report for mdbook-lint issues
- Opened GitHub issue #175 on mdbook-lint repository for:
  - Configuration rules not being applied
  - --fix option not working
- Improved CLI reference generation with better markdown formatting

Most critical linting issues now resolved, remaining are due to mdbook-lint bugs.

Author: joshrotenberg

docs/.mdbook-lint.toml

@@ -8,10 +8,31 @@ disabled-rules = [
     "MDBOOK002",  # Internal link validation - false positives with existing files
 ]
 
-# Don't fail the build on warnings or errors during initial setup
+# Don't fail the build on warnings, but show them for fixing
 fail-on-warnings = false
 fail-on-errors = false
 
+# Enable rules that should be fixable
+[rules.MD022]
+# Require blank lines around headings 
+enabled = true
+
+[rules.MD032]
+# Require blank lines around lists
+enabled = true
+
+[rules.MD031]
+# Require blank lines around fenced code blocks
+enabled = true
+
+[rules.MD006]
+# Lists should start at beginning of line
+enabled = true
+
+[rules.MD047]
+# Files should end with single newline
+enabled = true
+
 # Configure specific rules
 [rules.MD013]
 # Allow longer lines for code examples and CLI output

docs/MDBOOK_LINT_BUG_REPORT.md

@@ -0,0 +1,61 @@
+# mdbook-lint Bug Report
+
+Found multiple bugs in mdbook-lint v0.11.2 during redisctl documentation linting.
+
+## Bug 1: Configuration Rules Not Applied
+
+**Issue**: Rules defined in `.mdbook-lint.toml` configuration file are not being applied.
+
+**Expected**: Rules configured in the config file should override defaults.
+
+**Actual**: Default rule settings are used regardless of configuration.
+
+**Reproduction**:
+1. Create `.mdbook-lint.toml` with:
+   ```toml
+   [rules.MD013]
+   line_length = 120
+   ```
+2. Run `mdbook-lint lint file.md` 
+3. Observe that MD013 still enforces 80 character limit instead of 120
+
+**Evidence**: Lines over 80 chars trigger MD013 warnings despite config setting line_length = 120.
+
+## Bug 2: --fix Option Not Working
+
+**Issue**: The `--fix` option doesn't actually fix any issues, even for rules that should be auto-fixable.
+
+**Expected**: `mdbook-lint lint --fix file.md` should automatically fix issues like MD022, MD032, MD031, MD047.
+
+**Actual**: Command shows the same warnings but doesn't modify the file.
+
+**Reproduction**:
+1. Create test file with MD022 violations (missing blank lines after headings)
+2. Run `mdbook-lint lint --fix test.md`
+3. File remains unchanged despite warnings being shown
+
+**Test case**:
+```markdown
+# Heading
+Text directly after heading without blank line
+```
+
+Should be auto-fixed to:
+```markdown
+# Heading
+
+Text directly after heading without blank line
+```
+
+But file remains unmodified.
+
+## Environment
+- mdbook-lint version: 0.11.2
+- OS: macOS (Darwin 24.6.0)
+- Configuration file present: `.mdbook-lint.toml`
+
+## Workaround
+Currently fixing issues manually by editing markdown files directly.
+
+## Impact
+These bugs prevent automated fixing and proper configuration of linting rules, requiring manual intervention for all markdown formatting issues.

docs/cli-reference/README.md

@@ -1,6 +1,6 @@
 # redisctl Command Reference
 
-```
+```text
 Unified Redis CLI for Cloud and Enterprise
 
 Usage: redisctl [OPTIONS] <COMMAND>
@@ -25,5 +25,4 @@ Options:
   -v, --verbose...               Verbose logging
   -h, --help                     Print help
   -V, --version                  Print version
-```
-
+```text

docs/cli-reference/auth/README.md

@@ -1,6 +1,6 @@
 # Authentication Management Commands
 
-```
+```text
 Authentication testing and management
 
 Usage: redisctl auth <COMMAND>
@@ -13,4 +13,3 @@ Commands:
 Options:
   -h, --help  Print help
 ```
-

docs/cli-reference/auth/setup.md

@@ -1,11 +1,10 @@
 # Auth Setup Command
 
-```
+```text
 Interactive setup wizard for new profiles
 
 Usage: redisctl auth setup
 
 Options:
   -h, --help  Print help
-```
-
+```text

docs/cli-reference/auth/test.md

@@ -1,6 +1,6 @@
 # Auth Test Command
 
-```
+```text
 Test authentication credentials
 
 Usage: redisctl auth test [OPTIONS]
@@ -9,5 +9,4 @@ Options:
       --profile <PROFILE>        Profile to test (defaults to current profile)
       --deployment <DEPLOYMENT>  Test a specific deployment type [possible values: cloud, enterprise]
   -h, --help                     Print help
-```
-
+```text

docs/cli-reference/cloud/README.md

@@ -1,6 +1,6 @@
 # Redis Cloud Commands
 
-```
+```text
 Redis Cloud commands
 
 Usage: redisctl cloud <COMMAND>
@@ -31,5 +31,4 @@ Commands:
 
 Options:
   -h, --help  Print help
-```
-
+```text

docs/cli-reference/cloud/account.md

@@ -1,6 +1,6 @@
 # Cloud Account Commands
 
-```
+```text
 Account management
 
 Usage: redisctl cloud account <COMMAND>
@@ -16,5 +16,4 @@ Commands:
 
 Options:
   -h, --help  Print help
-```
-
+```text

docs/cli-reference/cloud/acl.md

@@ -1,6 +1,6 @@
 # Cloud ACL Commands
 
-```
+```text
 ACL management
 
 Usage: redisctl cloud acl <COMMAND>
@@ -15,5 +15,4 @@ Commands:
 
 Options:
   -h, --help  Print help
-```
-
+```text

docs/cli-reference/cloud/api-key.md

@@ -1,6 +1,6 @@
 # Cloud API Key Commands
 
-```
+```text
 API Keys management
 
 Usage: redisctl cloud api-key <COMMAND>
@@ -18,5 +18,4 @@ Commands:
 
 Options:
   -h, --help  Print help
-```
-
+```text