# Scripts Directory

Utility scripts for development, build optimization, and content generation.

## Overview

This directory contains **11 utility scripts** that automate various development tasks including image optimization, sitemap generation, performance testing, translation conversion, font downloads, icon generation, and documentation creation.

## Scripts

### Image Optimization

#### `optimize-images.js`
**Purpose:** Optimizes project cover images with responsive sizes and modern formats

**Usage:**
```bash
node scripts/optimize-images.js
# or
npm run build:images
```

**What it does:**
- Processes images from `source-images/projects/<project-slug>/cover.jpg`
- Generates multiple responsive sizes: 200w, 300w, 400w, 600w, 800w, 1200w
- Outputs both JPG (quality 80) and WebP (quality 75) formats
- Creates optimized original at 85% quality
- Outputs to `public/images/projects/<project-slug>/`

**Requirements:** `sharp`

---

#### `optimize-images.mjs`
**Purpose:** Optimizes gallery photos with predefined naming mapping

**Usage:**
```bash
node scripts/optimize-images.mjs
```

**What it does:**
- Converts and renames photos from `./photos` directory
- Resizes images to max 1200px width
- Outputs WebP format (quality 80)
- Maps cryptic filenames to semantic names (e.g., `thinker-dark.webp`, `studio-seated.webp`)
- Outputs to `public/images/gallery/`

**Requirements:** `sharp`

---

### SEO & Performance

#### `generate-sitemap.js`
**Purpose:** Generates XML sitemap with multi-language support and robots.txt

**Usage:**
```bash
node scripts/generate-sitemap.js
```

**What it does:**
- Generates `public/sitemap.xml` for all static pages, blog posts, and portfolio projects
- Supports 3 languages: German (default), English, Serbian
- Includes hreflang alternate links for SEO
- Sets appropriate priority and changefreq values
- Generates/updates `public/robots.txt` with sitemap references

**Configuration:**
- `SITE_URL`: https://damjan-savic.com
- `LANGUAGES`: ['de', 'en', 'sr']
- `DEFAULT_LANGUAGE`: 'de'

**Output:** `public/sitemap.xml`, `public/robots.txt`

---

#### `pagespeed-check.js`
**Purpose:** Tests website performance using Google PageSpeed Insights API

**Usage:**
```bash
node scripts/pagespeed-check.js
```

**What it does:**
- Runs PageSpeed tests for both mobile and desktop
- Displays Performance, Accessibility, Best Practices, and SEO scores
- Shows Core Web Vitals: FCP, LCP, TBT, CLS, Speed Index
- Lists top 5 optimization opportunities with time savings
- Identifies diagnostic issues with low scores
- Color-coded results (green ≥90, yellow ≥50, red <50)

**Requirements:** Google PageSpeed API key (configured in script)

**Note:** Disables SSL verification for local testing (line 10)

---

### Internationalization

#### `convert-translations.js`
**Purpose:** Converts TypeScript translation files to JSON format for next-intl

**Usage:**
```bash
node scripts/convert-translations.js
```

**What it does:**
- Reads TypeScript translations from `src/i18n/locales/<locale>/index.ts`
- Converts all 3 locales: de, en, sr
- Outputs formatted JSON to `src/messages/<locale>.json`
- Preserves nested structure and formatting

**Output:** `src/messages/de.json`, `src/messages/en.json`, `src/messages/sr.json`

---

### Assets & Resources

#### `download-fonts.js` (CommonJS)
**Purpose:** Downloads Inter variable font for self-hosting

**Usage:**
```bash
node scripts/download-fonts.js
```

**What it does:**
- Downloads InterVariable.woff2 from https://rsms.me/inter/
- Saves to `public/fonts/inter-var.woff2`
- Creates fonts directory if it doesn't exist
- Shows progress and error handling

**Requirements:** Node.js with CommonJS support

---

#### `download-fonts.mjs` (ES Module)
**Purpose:** Downloads Inter variable font for self-hosting (ES Module version)

**Usage:**
```bash
node scripts/download-fonts.mjs
```

**What it does:**
- Same functionality as download-fonts.js
- ES Module syntax with `import` statements
- Downloads InterVariable.woff2 from https://rsms.me/inter/
- Saves to `public/fonts/inter-var.woff2`

**Requirements:** Node.js with ES Module support

---

### Icon Generation

#### `generate-icons.mjs`
**Purpose:** Generates PWA icons from logo.svg or creates placeholders

**Usage:**
```bash
node scripts/generate-icons.mjs
```

**What it does:**
- Attempts to generate icons from `public/logo.svg`
- If logo.svg doesn't exist, creates placeholder icons with "DS" text
- Generates two sizes: 192x192 and 512x512 PNG
- Outputs to `public/icon-192x192.png` and `public/icon-512x512.png`
- Uses dark background (#18181b) with white text

**Requirements:** `sharp`

---

#### `generate-icons-simple.mjs`
**Purpose:** Creates simple SVG placeholder icons without Sharp dependency

**Usage:**
```bash
node scripts/generate-icons-simple.mjs
```

**What it does:**
- Generates SVG icons (not PNG) with "DS" text
- Creates 192x192 and 512x512 versions
- No image processing library required
- Outputs to `public/icon-192x192.svg` and `public/icon-512x512.svg`
- Dark background (#18181b) with white text

**Note:** Outputs SVG files instead of PNG - manifest.json may need updating

---

### Documentation

#### `generate-github-readme.js`
**Purpose:** Generates GitHub profile README and project README template

**Usage:**
```bash
node scripts/generate-github-readme.js
```

**What it does:**
- Generates comprehensive GitHub profile README with:
  - Tech stack badges (Python, JavaScript, React, TypeScript, etc.)
  - GitHub stats widgets
  - Featured projects section
  - Skills and specializations
  - Contact information
- Creates project README template with:
  - Standard sections (Overview, Installation, Usage, etc.)
  - Tech stack badges
  - Configuration examples
  - API documentation template
  - License and author info

**Output:**
- `github-profile-README.md` - For GitHub profile
- `project-readme-template.md` - Template for new projects

---

#### `generate-og-image.html`
**Purpose:** HTML template for creating Open Graph social media preview images

**Usage:**
```bash
# Open in browser and screenshot, or use with headless browser:
npx playwright screenshot scripts/generate-og-image.html og-image.png --viewport-size 1200,630
```

**What it does:**
- Provides ready-to-screenshot HTML for OG image (1200x630px)
- Features dark gradient background with pattern overlay
- Displays logo, name, subtitle, and skills
- Optimized dimensions for social media (Twitter, Facebook, LinkedIn)
- Modern, professional design matching portfolio branding

**Suggested tools:**
- Puppeteer
- Playwright
- Browser DevTools screenshot

---

## Dependencies

Scripts in this directory require the following npm packages:

### Required
- `sharp` - Image processing (optimize-images, generate-icons)

### Built-in Node.js Modules
- `fs` / `fs/promises` - File system operations
- `path` - Path manipulation
- `https` - HTTP requests
- `url` - URL utilities

## NPM Scripts

Some scripts are aliased in `package.json` for convenience:

```bash
npm run build:images    # Runs optimize-images.js
```

## Best Practices

### Running Scripts
- Always run from project root: `node scripts/<script-name>`
- Check for required dependencies before running
- Review output messages for errors or warnings

### Adding New Scripts
1. Add `.js` or `.mjs` file to `scripts/` directory
2. Use ES Module syntax (`.mjs`) for new scripts
3. Include usage comments at the top
4. Add error handling and progress logging
5. Update this README with documentation

### Maintenance
- Keep scripts focused on single responsibility
- Use descriptive filenames
- Add npm aliases for frequently used scripts
- Test scripts after dependency updates

## Common Issues

### Image Optimization
**Issue:** "Source directory not found"
**Solution:** Ensure images exist in `source-images/projects/<slug>/cover.jpg`

### Font Download
**Issue:** SSL/Certificate errors
**Solution:** Script includes `NODE_TLS_REJECT_UNAUTHORIZED='0'` for local testing

### Icon Generation
**Issue:** Sharp installation fails
**Solution:** Use `generate-icons-simple.mjs` as fallback (generates SVG instead)

### Sitemap Generation
**Issue:** Missing routes in sitemap
**Solution:** Update static page, blog post, or project arrays in `generate-sitemap.js`

## Missing Scripts

### `generate-blog-images.mjs`

**Status:** ❌ **MISSING** - Referenced in package.json but not implemented

**Package.json References:**
```json
"generate:images": "node scripts/generate-blog-images.mjs"
"generate:images:dry": "node scripts/generate-blog-images.mjs --dry-run"
```

**Description (from spec):**
This script is intended to generate AI-powered images for blog posts using the OpenAI API. It should support a `--dry-run` flag for testing without actually generating images.

**Recommended Action:**
Choose one of the following:
1. **Remove references** - If AI image generation is not needed, remove the npm scripts from package.json
2. **Implement the script** - Create the script with the following features:
   - OpenAI API integration for image generation
   - `--dry-run` flag support for testing
   - Process blog posts and generate featured images
   - Proper error handling and progress logging
   - API key management (environment variables)

**Impact:**
Running `npm run generate:images` or `npm run generate:images:dry` will fail with "Cannot find module" error until this is resolved.

---

## Notes

- Scripts use both `.js` (CommonJS) and `.mjs` (ES Module) extensions
- Duplicate scripts (e.g., download-fonts) exist for compatibility
- Some scripts include development-specific configurations (API keys, SSL bypass)
- HTML file (`generate-og-image.html`) requires manual screenshot or headless browser

---

**Total Scripts:** 11
**Last Updated:** 2026-01
**Maintained By:** Development Team