# 📜 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!**