feat(ci): add markdownlint-cli2 for consistent markdown formatting

[DasBen]

Add markdownlint-cli2 for consistent markdown formatting

AI Assistance Disclosure

This PR was implemented primarily using Claude Code (Anthropic) with human oversight, testing, and direction throughout the process. All changes were reviewed, tested locally, and verified before submission.

Summary

This PR adds automated markdown linting to Spec Kit using markdownlint-cli2 to ensure consistent formatting across all markdown files in the repository.

Why this matters for Spec Kit:

1. Consistency across documentation - Spec Kit templates, guides, and documentation should have uniform formatting to maintain professional quality
2. Prevent errors after project initialization - When users run /speckit.init to set up new projects, they receive clean, properly formatted markdown files without linting errors
3. Enforce quality standards - Automated checks catch formatting issues before they're merged, maintaining high documentation quality
4. Reduce manual review burden - Maintainers don't need to manually check markdown formatting in every PR

Personal note: After initializing spec-kit in my projects, I kept encountering markdown linting errors. This ensures that never happens again! 😄

How to Reproduce the Problem

Before this PR, cloning spec-kit and running markdownlint showed extensive errors:

1. Install markdownlint-cli2 globally:

   npm install -g markdownlint-cli2

2. Clone spec-kit main branch:

   git clone https://github.com/specify-systems/spec-kit.git
   cd spec-kit

3. Run the linter:

   markdownlint-cli2 "**/*.md"

4. Result - 908 errors across 27 files:

   Summary: 908 error(s)
   

   Common errors included:

   • Missing language specifiers on code blocks (MD040)
   • Inconsistent list formatting (MD004, MD032)
   • Missing blank lines around headings/lists (MD022, MD031)
   • Trailing spaces (MD009)
   • Inconsistent emphasis styles (MD049, MD050)

After this PR, the same command produces:

markdownlint-cli2 v0.18.1 (markdownlint v0.38.0)
Finding: **/*.md
Linting: 27 file(s)
Summary: 0 error(s)

Changes Made

1. Added .markdownlint-cli2.jsonc configuration

• Disabled line length checking (MD013) - technical docs often have long lines (URLs, code examples, tables)
• Disabled inline HTML (MD033) - necessary for advanced formatting like <div>, <details>, <summary>
• Disabled first-line heading requirement (MD041) - template files use YAML frontmatter
• Enforced ATX-style headings (# instead of underline style)
• Set consistent list indentation (2 spaces)
• Enforced asterisk style for emphasis (*italic*, **bold**)
• Allows duplicate headings in different sections

2. Created .github/workflows/lint.yml

• Runs on every push to main and all pull requests
• Uses DavidAnson/markdownlint-cli2-action@v19
• Automatically discovers and uses the config file
• Provides fast feedback on markdown formatting issues

3. Fixed all existing markdown errors

• 908 initial errors found in 27 markdown files
• Auto-fixed 879 errors (97%): spacing, list formatting, blank lines, emphasis style
• Manually fixed 29 errors (3%): missing language specifiers, alt text, table formatting
• Final result: 0 errors ✅

---

Ready for review! This ensures consistent, high-quality markdown formatting across the entire Spec Kit project. 🎉

[Copilot]

Pull Request Overview

Adds automated markdown linting to Spec Kit using markdownlint-cli2 to ensure consistent formatting across all markdown files. This prevents formatting errors in documentation and templates that users receive when initializing new projects.

• Configured markdownlint-cli2 with project-appropriate rules (allowing long lines, HTML elements, and YAML frontmatter)
• Added GitHub Actions workflow for automated linting on pushes and pull requests
• Fixed 908 existing markdown formatting errors across 27 files

Reviewed Changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated no comments.

File	Description
.markdownlint-cli2.jsonc	Configuration file defining markdown linting rules tailored for technical documentation
.github/workflows/lint.yml	GitHub Actions workflow to automatically run markdown linting on all markdown files
Multiple template files	Fixed markdown formatting issues including missing blank lines, inconsistent list styles, and code block language specifiers
Documentation files	Corrected formatting in README, contributing guide, and other project documentation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}