mcp-adr-analysis-server

# 📜 Documentation Scripts Guide **Automated setup and management for your documentation website** --- ## 🎯 Available Scripts ### **🚀 setup-website.sh** (Advanced Bash Script) **Full-featured script with error checking, colored output, and deployment guidance** ```bash ./setup-website.sh [command] ``` **Commands:** - `setup` - Install dependencies and check prerequisites - `dev` - Start development server with hot reload - `build` - Build static site for production - `preview` - Preview built site locally - `deploy` - Deployment guidance for GitHub Pages - `clean` - Clean build artifacts and cache - `help` - Show detailed help ### **📦 npm Scripts** (Simple & Cross-Platform) **Quick npm-based commands for common tasks** ```bash npm run [command] ``` **Commands:** - `setup` - Quick dependency installation - `dev` - Start development server - `build` - Build for production - `deploy` - Build + deployment info - `clean` - Clean build artifacts --- ## 🔄 When to Use Which ### **Use npm Scripts When:** ✅ You want simple, cross-platform commands ✅ You're familiar with npm workflow ✅ You don't need detailed progress feedback ✅ You're on Windows or prefer npm ### **Use Bash Script When:** ✅ You want detailed progress information ✅ You need comprehensive error checking ✅ You want deployment guidance ✅ You prefer rich terminal output ✅ You're on macOS/Linux --- ## ⚡ Quick Reference ### **First Time Setup** ```bash # Option A: npm (simple) cd docs npm run setup # Option B: script (detailed) cd docs ./setup-website.sh setup ``` ### **Development** ```bash # Option A: npm npm run dev # Option B: script ./setup-website.sh dev ``` ### **Production Build** ```bash # Option A: npm npm run build # Option B: script ./setup-website.sh build ``` ### **Deployment** ```bash # Option A: npm (just builds) npm run deploy # Option B: script (guidance + git integration) ./setup-website.sh deploy ``` --- ## 🎨 Script Features ### **setup-website.sh Features:** - 🎨 **Colored output** with emojis for better UX - ✅ **Prerequisites checking** (Node.js version, location) - 📊 **Build statistics** (file count, size) - 🚀 **Git integration** for deployment - 🧹 **Interactive cleanup** with confirmations - ❌ **Error handling** with helpful messages ### **npm Scripts Features:** - ⚡ **Fast execution** with minimal overhead - 🌐 **Cross-platform** compatibility - 📝 **Simple output** with status emojis - 🔄 **Standard npm workflow** integration --- ## 🛠️ Customization ### **Adding New Commands** **To npm scripts** (edit `package.json`): ```json "scripts": { "your-command": "echo '🎯 Your command' && your-actual-command" } ``` **To bash script** (edit `setup-website.sh`): ```bash # Add to the case statement "your-command") your_function ;; ``` ### **Modifying Existing Commands** - **npm scripts**: Edit the `scripts` section in `package.json` - **bash script**: Edit the corresponding function in `setup-website.sh` --- ## 🔧 Troubleshooting Scripts ### **Script Permission Issues** ```bash chmod +x setup-website.sh ``` ### **npm Scripts Not Working** ```bash # Verify package.json exists ls -la package.json # Reinstall if needed rm -rf node_modules package-lock.json npm install ``` ### **Script Path Issues** ```bash # Ensure you're in the docs directory pwd # Should end with /docs cd docs # If not ``` --- ## 📊 Performance Comparison | Task | npm Scripts | Bash Script | Winner | |------|-------------|-------------|---------| | **Speed** | ⚡ Fast | 🐌 Slower (checks) | npm | | **Feedback** | 📝 Basic | 🎨 Rich | Script | | **Error Handling** | ❌ Basic | ✅ Comprehensive | Script | | **Cross-Platform** | ✅ Yes | ⚠️ Unix only | npm | | **Deployment Help** | 📝 Basic | 🚀 Guided | Script | --- ## 🎯 Recommended Workflow ### **For Developers:** ```bash # Daily development npm run dev # Building for production ./setup-website.sh build # Better feedback # Deploying ./setup-website.sh deploy # Guided process ``` ### **For CI/CD:** ```bash # Automated builds (use npm for consistency) npm run setup npm run build ``` ### **For New Contributors:** ```bash # First time (use script for guidance) ./setup-website.sh setup ./setup-website.sh help ``` --- ## 📚 Related Documentation - **[QUICK_START.md](QUICK_START.md)** - Fastest way to get started - **[WEBSITE_SETUP.md](WEBSITE_SETUP.md)** - Complete setup documentation - **[package.json](package.json)** - npm scripts configuration - **[setup-website.sh](setup-website.sh)** - Bash script source code --- **🎉 Both approaches get you to the same amazing documentation website - choose the one that fits your workflow best!**