Add markdownlint to CI for Markdown file validation

.claude/commands/issue-checkout.md

@@ -147,7 +147,7 @@ If no branch exists:
 
 **For existing branch with commits**:
 
-```
+```text
 You're continuing work on issue #91.
 
 Branch: 91-add-issue-checkout-command
@@ -168,7 +168,7 @@ Suggested next steps:
 
 **For existing branch with no commits**:
 
-```
+```text
 You have an empty branch for issue #91.
 
 Branch: 91-add-issue-checkout-command
@@ -184,7 +184,7 @@ Suggested next steps:
 
 **For new branch**:
 
-```
+```text
 Created new branch for issue #91.
 
 Branch: 91-add-issue-checkout-command

.github/workflows/ci.yml

@@ -30,6 +30,15 @@ jobs:
       - name: Check GitHub Actions workflows (actionlint)
         run: actionlint
 
+      - name: Check Markdown files (markdownlint)
+        uses: DavidAnson/markdownlint-cli2-action@v22
+        with:
+          globs: |
+            *.md
+            docs/**/*.md
+            .github/**/*.md
+            .claude/**/*.md
+
   test:
     runs-on: ubuntu-latest
     steps:

.markdownlint.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
+  "default": true,
+  "MD007": {
+    "indent": 4
+  },
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD029": false,
+  "MD031": {
+    "list_items": false
+  },
+  "MD033": {
+    "allowed_elements": ["number"]
+  },
+  "MD041": false
+}

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Structure
 
-```
+```text
 keystone-cli/
 ├── src/
 │   └── Keystone.Cli/               # Main application
@@ -65,6 +65,7 @@ keystone-cli/
 │   └── verify-deb-install.sh       # Verify .deb package installation
 ├── nfpm.yaml                       # nfpm configuration for .deb packaging
 ├── .shellcheckrc                   # ShellCheck configuration
+├── .markdownlint.json              # Markdownlint configuration
 ├── Makefile                        # Development task automation (lint targets)
 ├── artifacts/                      # Build outputs
 ├── global.json                     # .NET SDK version (used by local and CI builds)
@@ -109,10 +110,12 @@ The project uses strict code analysis:
 - Uses Microsoft.VisualStudio.Threading.Analyzers
 - Shell scripts use shfmt for formatting and shellcheck for static analysis
 - GitHub Actions workflows validated with actionlint
+- Markdown files checked with markdownlint
 
 ### Linting
 
-Shell scripts and GitHub Actions workflows are checked in CI and can be validated locally.
+Shell scripts, GitHub Actions workflows, and Markdown files are checked in CI and can be
+validated locally.
 
 ```bash
 # Run all linters (recommended)
@@ -125,19 +128,22 @@ make lint-fix
 make lint-shfmt       # Shell formatting
 make lint-shellcheck  # Shell static analysis
 make lint-actionlint  # GitHub Actions workflows
+make lint-markdown    # Markdown files
 ```
 
 Install tools:
 
 - **shfmt**: `brew install shfmt` (macOS) or `go install mvdan.cc/sh/v3/cmd/shfmt@latest`
 - **shellcheck**: `brew install shellcheck` (macOS) or `apt-get install shellcheck` (Debian/Ubuntu)
 - **actionlint**: `brew install actionlint` (macOS) or `go install github.com/rhysd/actionlint/cmd/actionlint@latest`
+- **markdownlint**: `brew install markdownlint-cli2` (macOS) or `npm install -g markdownlint-cli2`
 
 Configuration:
 
 - shfmt: Flags in Makefile (`-i 2 -ci -bn -sr`)
 - shellcheck: `.shellcheckrc` (bash dialect, stricter optional checks enabled)
 - actionlint: Uses shellcheck for `run:` blocks when available
+- markdownlint: `.markdownlint.json` (4-space list indent, line length disabled)
 
 Shell code in GitHub workflow `run:` blocks should follow the same conventions—use
 `${VAR}` (braced) instead of `$VAR` for consistency with shellcheck's

CONTRIBUTING.md

@@ -89,8 +89,9 @@ This project follows a structured workflow documented in
 - Include unit tests for new functionality
 - Shell scripts must pass `shfmt` formatting and `shellcheck` analysis
 - GitHub Actions workflows must pass `actionlint` validation
-  - Run `make lint` to check all locally
-  - Run `make lint-fix` to auto-fix shell formatting
+- Markdown files must pass `markdownlint` validation
+    - Run `make lint` to check all locally
+    - Run `make lint-fix` to auto-fix shell formatting
 - Run `dotnet test` before submitting
 
 ## Labels

Makefile

@@ -4,7 +4,7 @@
 #   make lint       Run all linters (shell scripts and workflows)
 #   make lint-fix   Auto-fix shell script formatting
 
-.PHONY: help lint lint-fix lint-shfmt lint-shfmt-fix lint-shellcheck lint-actionlint
+.PHONY: help lint lint-fix lint-shfmt lint-shfmt-fix lint-shellcheck lint-actionlint lint-markdown
 
 .DEFAULT_GOAL := help
 
@@ -20,7 +20,7 @@ help: ## Show available targets
 	@echo "Targets:"
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
 
-lint: lint-shfmt lint-shellcheck lint-actionlint ## Run all linters
+lint: lint-shfmt lint-shellcheck lint-actionlint lint-markdown ## Run all linters
 	@echo "All checks passed"
 
 lint-fix: lint-shfmt-fix ## Auto-fix formatting issues (shfmt only)
@@ -41,3 +41,7 @@ lint-shellcheck: ## Run shellcheck on shell scripts
 lint-actionlint: ## Validate GitHub Actions workflows
 	@echo "Checking GitHub Actions workflows (actionlint)..."
 	@actionlint
+
+lint-markdown: ## Check Markdown file formatting
+	@echo "Checking Markdown files (markdownlint)..."
+	@markdownlint-cli2 "*.md" "docs/**/*.md" ".github/**/*.md" ".claude/**/*.md"

docs/how-to/how-to-test-man-page.md

@@ -12,15 +12,15 @@ To read the [mdoc(7)](https://man.openbsd.org/mdoc.7) documentation in your term
 man 7 mdoc
 ```
 
-### Using `mandoc`
+## Using `mandoc`
 
 To test the generated man page locally:
 
 ```bash
 mandoc docs/man/man1/keystone-cli.1
 ```
 
-### Using `man`
+## Using `man`
 
 To view the man page with man, you must supply an absolute path for the man path:
 

docs/how-to/how-to-workflow.md

@@ -40,11 +40,13 @@ Since PRs are squash-merged, individual commits don't need to be release-note qu
 good commit messages still help reviewers and your future self understand the progression of changes.
 
 **Do:**
+
 - Write short, descriptive summaries (e.g., `Add validation for empty input`)
 - Use commits to mark logical checkpoints (e.g., `WIP: basic structure`, `Add tests`, `Fix edge case`)
 - Feel free to use `WIP`, `fixup`, or `checkpoint` prefixes for in-progress work
 
 **Don't:**
+
 - Reference issue numbers in commit messages—the PR description handles issue linking
 - Worry about perfect formatting—squash merge discards individual commit messages
 - Write multi-paragraph commit bodies unless the context is genuinely useful for review