mux/DOCS.md

# Mux Documentation Index

Welcome to the Mux documentation! This page helps you navigate all available documentation.

## 📚 Documentation Files

### Getting Started
- **[QUICKSTART.md](QUICKSTART.md)** - Get up and running in 5 minutes
  - Installation instructions
  - Your first route
  - Common patterns
  - Complete working example
  - Testing examples
  - Troubleshooting

### Main Documentation
- **[README.md](README.md)** - Comprehensive project documentation
  - Full API reference
  - Detailed examples
  - Feature overview
  - Performance guidelines
  - Testing strategies
  - Complete working examples

### Contributing
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
  - Code quality standards
  - Development workflow
  - Testing requirements
  - Commit conventions
  - Performance considerations
  - Documentation standards

### Project Information
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
  - Release notes
  - Breaking changes
  - New features
  - Bug fixes
  - Migration guides

- **[SUMMARY.md](SUMMARY.md)** - Recent changes summary
  - Latest improvements
  - API changes
  - Migration guide
  - Quality metrics

## 🚀 Quick Links by Topic

### For New Users
1. Start with [QUICKSTART.md](QUICKSTART.md)
2. Read the "Basic Usage" section in [README.md](README.md)
3. Check out the [example directory](example/)
4. Review common patterns in [QUICKSTART.md](QUICKSTART.md)

### For API Reference
- **Routing**: [README.md#basic-routing](README.md#basic-routing)
- **Middleware**: [README.md#middleware](README.md#middleware)
- **Groups**: [README.md#route-groups](README.md#route-groups)
- **Resources**: [README.md#restful-resources](README.md#restful-resources)
- **Parameters**: [README.md#url-parameters](README.md#url-parameters)
- **Shutdown**: [README.md#graceful-shutdown](README.md#graceful-shutdown)

### For Contributors
1. Read [CONTRIBUTING.md](CONTRIBUTING.md) thoroughly
2. Review code quality standards
3. Install development tools: `make install-tools`
4. Run quality checks: `make check` or `./check.sh`
5. Follow the development workflow

### For Migration
- Check [CHANGELOG.md](CHANGELOG.md) for breaking changes
- Review [SUMMARY.md#migration-guide](SUMMARY.md#migration-guide)
- See API changes in [SUMMARY.md#api-changes](SUMMARY.md#api-changes)

## 📖 Code Examples

### Live Examples
- **[example/main.go](example/main.go)** - Full working application
  - Complete server setup
  - Middleware examples
  - Resource routing
  - Group routing
  - Custom routes

### Documentation Examples
- [QUICKSTART.md](QUICKSTART.md) - Simple, focused examples
- [README.md](README.md) - Comprehensive examples with explanations

## 🛠️ Development Tools

### Makefile Commands
```bash
make help              # Show all available commands
make test              # Run tests
make check             # Run all quality checks
make install-tools     # Install dev tools
make run-example       # Run example server
```

Full list in [Makefile](Makefile)

### Quality Check Script
```bash
./check.sh            # Run all quality checks with colored output
```

Script details in [check.sh](check.sh)

## 🔍 Configuration Files

### Project Configuration
- **[.cursorrules](.cursorrules)** - AI coding assistant rules
- **[.golangci.yml](.golangci.yml)** - Linting configuration
- **[Makefile](Makefile)** - Development commands
- **[go.mod](go.mod)** - Go module definition (Go 1.25+)

### CI/CD
- **[.github/workflows/ci.yml](.github/workflows/ci.yml)** - GitHub Actions workflow
  - Automated testing
  - Quality checks
  - Build verification

## 📋 API Overview

### Core Components

#### Mux
The main router instance.
```go
m := mux.New()
m.GET("/path", handler)
m.POST("/path", handler)
m.Use(middleware)
m.Group(func(grp *mux.Mux) { ... })
m.Resource("/pattern", func(res *mux.Resource) { ... })
```

#### Resource
RESTful resource routing.
```go
// Standard routes
res.Index(handler)        // GET /pattern
res.Create(handler)       // POST /pattern
res.View(handler)         // GET /pattern/{id}
res.Update(handler)       // PUT /pattern/{id}
res.Delete(handler)       // DELETE /pattern/{id}

// Collection routes
res.GET("/search", handler)     // GET /pattern/search
res.POST("/bulk", handler)      // POST /pattern/bulk

// Member routes
res.MemberGET("/stats", handler)    // GET /pattern/{id}/stats
res.MemberPOST("/publish", handler) // POST /pattern/{id}/publish
```

#### Middleware
Standard signature: `func(http.Handler) http.Handler`
```go
func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Before
        next.ServeHTTP(w, r)
        // After
    })
}
```

## 📊 Quality Standards

### Required Checks
- ✅ `go vet ./...`
- ✅ `staticcheck ./...`
- ✅ `fieldalignment ./...`
- ✅ `go test -race ./...`

### Running Checks
```bash
make check         # Run all checks
./check.sh         # Run with colored output
```

Details in [CONTRIBUTING.md#code-quality-standards](CONTRIBUTING.md#code-quality-standards)

## 🎯 Features

- ✅ HTTP method routing (GET, POST, PUT, DELETE, PATCH, etc.)
- ✅ Middleware support
- ✅ Route grouping
- ✅ RESTful resources
- ✅ URL parameters
- ✅ Graceful shutdown
- ✅ Zero dependencies
- ✅ Go 1.25+
- ✅ High performance
- ✅ Well tested
- ✅ Comprehensive docs

## 🔗 Related Links

### External Resources
- [Go HTTP Package](https://pkg.go.dev/net/http)
- [Go 1.22 Routing Enhancements](https://go.dev/blog/routing-enhancements)
- [Semantic Versioning](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)

### Middleware Compatibility
- [Gorilla Handlers](https://github.com/gorilla/handlers)
- [Chi Middleware](https://github.com/go-chi/chi/tree/master/middleware)

## 💡 Tips

### Finding Information
- **General usage**: Start with README.md
- **Quick start**: Use QUICKSTART.md
- **Contributing**: Read CONTRIBUTING.md
- **Changes**: Check CHANGELOG.md
- **Examples**: See example/ directory

### Getting Help
1. Check the documentation
2. Review examples
3. Search existing issues
4. Open a new issue with details

## 📝 License

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.

---

**Note**: All documentation files are written in Markdown and can be viewed on GitHub or in any Markdown viewer.

Last Updated: 2024