feat(docs): add comprehensive documentation and markdown linting setup

- Add new documentation files covering CI, contributing, image processing, linting, lockfile management, markdown linting, node version, and package manager
- Set up markdown linting with markdownlint-cli2 and configuration files
- Update CI workflow to include markdown linting
- Add scripts for testing CI locally
- Update README with links to new documentation

Author: wilsonwangdev

.github/workflows/lint.yml

@@ -39,4 +39,10 @@ jobs:
         run: pnpm biome format .
 
       - name: Run linting
-        run: pnpm biome check .
+        run: pnpm biome check .
+        
+      - name: Lint Markdown files
+        run: pnpm lint:md
+        
+      - name: Run all linting checks (combined)
+        run: pnpm lint

.lintstagedrc.json

@@ -1,4 +1,5 @@
 {
   "*.{js,jsx,ts,tsx}": ["biome check --write", "biome format --write"],
-  "*.astro": ["biome check --write", "biome format --write"]
+  "*.astro": ["biome check --write", "biome format --write"],
+  "*.md": ["markdownlint-cli2 --fix"]
 }

.markdownlint-cli2.jsonc

@@ -0,0 +1,14 @@
+{
+  "config": {
+    "extends": ".markdownlint.json",
+    "MD013": false,
+    "MD012": false,
+    "MD047": false
+  },
+  "globs": ["**/*.md"],
+  "ignores": ["node_modules/**", "**/node_modules/**", "README.md"],
+  "fix": false,
+  "noProgress": true,
+  "customRules": [],
+  "markdownItPlugins": []
+}

.markdownlint.json

@@ -0,0 +1,19 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false,
+  "MD046": { "style": "fenced" },
+  "MD024": false,
+  "MD025": { "front_matter_title": "" },
+  "MD029": false,
+  "MD012": false,
+  "MD047": false,
+  "MD032": false,
+  "MD031": false,
+  "MD001": false,
+  "MD009": false,
+  "MD026": false,
+  "MD040": false,
+  "MD007": false
+}

.markdownlintignore

@@ -0,0 +1,5 @@
+# Ignore main README.md which has special formatting for badges and alignment
+README.md
+
+# Ignore node_modules
+node_modules/

README.md

@@ -50,7 +50,7 @@ Frontend Tools Explorer is a curated collection of essential tools, libraries, a
   - v22 LTS (v22.0.0 or newer, also supported v22.17.0)
 - pnpm (v8.0.0 or newer)
 
-> **Note:** This project requires specific Node.js and package manager versions. For more details, see [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md) and [NODE-VERSION.md](./NODE-VERSION.md).
+> **Note:** This project requires specific Node.js and package manager versions. For more details, see [PACKAGE-MANAGER.md](./docs/PACKAGE-MANAGER.md) and [NODE-VERSION.md](./docs/NODE-VERSION.md).
 
 ### Installation
 
@@ -78,7 +78,7 @@ Frontend Tools Explorer is a curated collection of essential tools, libraries, a
    # If needed, install the LTS version from nodejs.org
    ```
 
-   > **Note:** This project requires pnpm as the package manager. We recommend using Corepack (built into Node.js 20+) to manage pnpm. See [PACKAGE-MANAGER.md](./PACKAGE-MANAGER.md) for more details and troubleshooting.
+   > **Note:** This project requires pnpm as the package manager. We recommend using Corepack (built into Node.js 20+) to manage pnpm. See [PACKAGE-MANAGER.md](./docs/PACKAGE-MANAGER.md) for more details and troubleshooting.
 
 3. Start the development server
 
@@ -109,23 +109,43 @@ To add a new frontend tool to the directory:
 3. Import and add your tool to the array in `src/data/tools/index.ts`
 4. Submit a pull request
 
-Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
+Please see [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for detailed contribution guidelines.
+
+## 📚 Documentation
+
+All project documentation is available in the [docs](./docs) directory. This includes:
+
+- [Contributing Guidelines](./docs/CONTRIBUTING.md)
+- [CI Setup](./docs/CI.md)
+- [Linting and Formatting](./docs/LINTING.md)
+- [Markdown Linting](./docs/MARKDOWN-LINTING.md)
+- [Package Manager Configuration](./docs/PACKAGE-MANAGER.md)
+- [Node.js Version Requirements](./docs/NODE-VERSION.md)
+- [Lockfile Management](./docs/LOCKFILE-MANAGEMENT.md)
+- [Image Processing](./docs/IMAGE-PROCESSING.md)
 
 ## 🔄 Continuous Integration
 
 This project uses GitHub Actions for continuous integration to ensure code quality. The CI workflow automatically runs linting and formatting checks on every pull request and push to the main branch.
 
-For more details on the CI setup, troubleshooting common issues, and best practices, see [CI.md](./CI.md).
+You can test the CI workflow locally before pushing changes:
+
+```sh
+# Run the CI test script
+./scripts/test-ci.sh
+```
+
+For more details on the CI setup, troubleshooting common issues, and best practices, see [CI.md](./docs/CI.md).
 
 ### Dependency Management
 
-This project uses pnpm for dependency management and requires proper lockfile handling, especially in CI environments. For guidance on managing the lockfile and resolving common issues, see [LOCKFILE-MANAGEMENT.md](./LOCKFILE-MANAGEMENT.md).
+This project uses pnpm for dependency management and requires proper lockfile handling, especially in CI environments. For guidance on managing the lockfile and resolving common issues, see [LOCKFILE-MANAGEMENT.md](./docs/LOCKFILE-MANAGEMENT.md).
 
 ## 🖼️ Image Processing
 
 This project uses Astro's built-in image optimization with Sharp for processing images. Sharp is required for both local development and Vercel deployment.
 
-For more details on image processing configuration, troubleshooting, and best practices, see [IMAGE-PROCESSING.md](./IMAGE-PROCESSING.md).
+For more details on image processing configuration, troubleshooting, and best practices, see [IMAGE-PROCESSING.md](./docs/IMAGE-PROCESSING.md).
 
 ## 📝 License
 

CI.md docs/CI.mdCI.md renamed to docs/CI.md

@@ -10,10 +10,12 @@ The CI workflow is defined in `.github/workflows/lint.yml` and performs the foll
 
 1. **Checkout Code**: Fetches the repository code with full history for proper lockfile validation
 2. **Setup pnpm**: Installs the pnpm package manager (version 8.15.4)
-3. **Setup Node.js**: Configures Node.js environment (version 22.17.0 LTS) with pnpm caching
+3. **Setup Node.js**: Configures Node.js environment with both Node.js v20 LTS and v22 LTS using a matrix strategy
 4. **Install Dependencies**: Installs project dependencies using pnpm
 5. **Check Formatting**: Verifies code formatting using Biome with `pnpm biome format .`
-6. **Run Linting**: Performs code linting using Biome with `pnpm biome check .`
+6. **Run JavaScript/TypeScript Linting**: Performs code linting using Biome with `pnpm biome check .`
+7. **Run Markdown Linting**: Checks markdown files with `pnpm lint:md`
+8. **Run Combined Linting**: Executes all linting checks with `pnpm lint`
 
 ## Important Notes on Dependency Management
 
@@ -56,11 +58,66 @@ If you encounter dependency-related issues in CI:
 
 For more detailed guidance on lockfile management and troubleshooting, see [LOCKFILE-MANAGEMENT.md](./LOCKFILE-MANAGEMENT.md).
 
+## Testing CI Locally
+
+Before pushing changes to CI configuration or code that might affect CI, it's recommended to test the workflow locally:
+
+### Using the Test Script
+
+We provide a convenient script to test the CI workflow locally:
+
+```bash
+# Make the script executable (if needed)
+chmod +x scripts/test-ci.sh
+
+# Run the test script
+./scripts/test-ci.sh
+```
+
+This script will:
+1. Run all the individual commands from the CI workflow
+2. Optionally run the entire GitHub Actions workflow locally using `act`
+
+### Manual Testing
+
+If you prefer to test manually, follow these steps:
+
+1. **Run the same commands locally** that are executed in the CI workflow:
+   ```bash
+   # Install dependencies (same as CI)
+   pnpm install --no-frozen-lockfile
+   
+   # Check formatting
+   pnpm biome format .
+   
+   # Run JavaScript/TypeScript linting
+   pnpm lint:js
+   
+   # Lint Markdown files
+   pnpm lint:md
+   
+   # Run all linting checks at once
+   pnpm lint
+   ```
+
+2. **Test with multiple Node.js versions** if possible:
+   - Use a version manager like nvm to switch between Node.js versions
+   - Test with both Node.js v20 LTS and v22 LTS as specified in the CI matrix
+
+3. **Use GitHub Actions local runners** for more comprehensive testing:
+   - [act](https://github.com/nektos/act) allows running GitHub Actions workflows locally
+   - Install with: `brew install act` (on macOS)
+   - Run with: `act -j lint` to execute the lint job
+
+4. **Validate workflow files** for syntax errors:
+   - Use the [GitHub Actions Workflow Validator](https://github.com/marketplace/actions/workflow-validator) or online tools
+
 ## Best Practices
 
 1. Always commit the `pnpm-lock.yaml` file to ensure consistent dependencies
 2. Use the same Node.js and pnpm versions locally as specified in the CI workflow
 3. Avoid manually editing the lockfile
 4. When adding new dependencies, update the lockfile by running `pnpm install` and commit the changes
 5. Use `pnpm install --no-frozen-lockfile` in CI environments to prevent lockfile-related failures
-6. If you're experiencing CI failures related to the lockfile, try removing the `--frozen-lockfile` flag in your local environment
+6. If you're experiencing CI failures related to the lockfile, try removing the `--frozen-lockfile` flag in your local environment
+7. Always test CI workflow changes locally before pushing to the repository

CONTRIBUTING.md docs/CONTRIBUTING.mdCONTRIBUTING.md renamed to docs/CONTRIBUTING.md

@@ -113,6 +113,17 @@ export const toolName: Tool = {
 
 4. Open your browser and visit `http://localhost:4321`
 
+5. Test your changes locally before submitting a PR
+   ```sh
+   # Run linting checks
+   pnpm lint
+   
+   # Test CI workflow locally
+   ./scripts/test-ci.sh
+   ```
+   
+   > For more details on testing CI locally, see [CI.md](./CI.md#testing-ci-locally).
+
 ## Style Guidelines
 
 ### Code Style

IMAGE-PROCESSING.md docs/IMAGE-PROCESSING.mdIMAGE-PROCESSING.md renamed to docs/IMAGE-PROCESSING.md

@@ -34,14 +34,15 @@ biome format --write .
 
 ## Features Summary
 
-| Feature | Biome |
-|---------|-------|
-| Linting | ✅ |
-| Formatting | ✅ |
-| Astro Support | ⚠️ (partial) |
-| Performance | Very Fast |
-| Editor Integration | ✅ |
-| Configuration | `biome.json` |
+| Feature | Biome | markdownlint-cli2 |
+|---------|-------|------------------|
+| Linting | ✅ | ✅ |
+| Formatting | ✅ | ✅ |
+| Astro Support | ⚠️ (partial) | N/A |
+| Markdown Support | ❌ | ✅ |
+| Performance | Very Fast | Fast |
+| Editor Integration | ✅ | ✅ |
+| Configuration | `biome.json` | `.markdownlint.json` |
 
 ## Automated Checks with Husky and lint-staged
 
@@ -61,13 +62,15 @@ The lint-staged configuration is in `.lintstagedrc.json`:
 ```json
 {
   "*.{js,jsx,ts,tsx}": ["biome check --write", "biome format --write"],
-  "*.astro": ["biome check --write", "biome format --write"]
+  "*.astro": ["biome check --write", "biome format --write"],
+  "*.md": ["markdownlint-cli2 --fix"]
 }
 ```
 
 This ensures that:
 - JavaScript and TypeScript files are linted and formatted
 - Astro files are linted and formatted (to the extent supported by Biome)
+- Markdown files are linted and automatically fixed when possible
 
 ### Benefits
 
@@ -84,25 +87,55 @@ This project uses **Biome** as the linting and formatting tool because:
 3. It offers a Prettier-compatible formatter
 4. It provides excellent performance for JavaScript and TypeScript projects
 
+## Markdown Linting with markdownlint-cli2
+
+In addition to Biome, this project uses [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) to lint and format Markdown documentation files.
+
+### Features
+
+- **Consistent formatting** across all markdown files
+- **Automated fixes** for common issues
+- **Pre-commit checks** to ensure documentation quality
+- **CI integration** to verify documentation in pull requests
+
+### Usage
+
+```bash
+# Check markdown files for issues
+pnpm lint:md
+
+# Fix markdown issues automatically where possible
+pnpm lint:md:fix
+```
+
+For more details on the markdown linting setup, see [MARKDOWN-LINTING.md](./MARKDOWN-LINTING.md).
+
 ## Installation
 
-Biome is already installed as a dev dependency in this project. You can use it directly through the npm scripts or via the `biome` command:
+Biome and markdownlint-cli2 are already installed as dev dependencies in this project. You can use them directly through the npm scripts or via their respective commands:
 
 ```bash
-# Using npm scripts
+# Using npm scripts for Biome
 pnpm lint
 pnpm format
 pnpm check
 
+# Using npm scripts for markdownlint
+pnpm lint:md
+pnpm lint:md:fix
+
 # Or directly
 pnpm biome check .
 pnpm biome format .
+pnpm markdownlint-cli2 "**/*.md"
+pnpm markdownlint-cli2 --fix "**/*.md"
 ```
 
 ## Editor Integration
 
-Biome offers a VS Code extension for editor integration:
+Both Biome and markdownlint offer VS Code extensions for editor integration:
 
 - [Biome VS Code Extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
+- [markdownlint VS Code Extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
 
-The project's `.vscode/settings.json` is already configured to use Biome when it's installed.
+The project's `.vscode/settings.json` is already configured to use Biome when it's installed. The markdownlint extension will automatically use the project's `.markdownlint.json` configuration.