Skip to main content

📜 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

./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

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​

# Option A: npm (simple)
cd docs
npm run setup

# Option B: script (detailed)
cd docs
./setup-website.sh setup

Development​

# Option A: npm
npm run dev

# Option B: script  
./setup-website.sh dev

Production Build​

# Option A: npm
npm run build

# Option B: script
./setup-website.sh build

Deployment​

# 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):

"scripts": {
  "your-command": "echo '🎯 Your command' && your-actual-command"
}

To bash script (edit setup-website.sh):

# 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​

chmod +x setup-website.sh

npm Scripts Not Working​

# Verify package.json exists
ls -la package.json

# Reinstall if needed
rm -rf node_modules package-lock.json
npm install

Script Path Issues​

# Ensure you're in the docs directory
pwd  # Should end with /docs
cd docs  # If not

📊 Performance Comparison​

Tasknpm ScriptsBash ScriptWinner
Speed⚡ Fast🐌 Slower (checks)npm
Feedback📝 Basic🎨 RichScript
Error Handling❌ Basic✅ ComprehensiveScript
Cross-Platform✅ Yes⚠️ Unix onlynpm
Deployment Help📝 Basic🚀 GuidedScript

🎯 Recommended Workflow​

For Developers:​

# Daily development
npm run dev

# Building for production
./setup-website.sh build  # Better feedback

# Deploying
./setup-website.sh deploy  # Guided process

For CI/CD:​

# Automated builds (use npm for consistency)
npm run setup
npm run build

For New Contributors:​

# First time (use script for guidance)
./setup-website.sh setup
./setup-website.sh help

📚 Related Documentation​

🎉 Both approaches get you to the same amazing documentation website - choose the one that fits your workflow best!