diff --git a/README.md b/README.md index 21af8a2..ae37bd8 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,25 @@ npm test npm run preview ``` +## Development Scripts + +The project includes **11 utility scripts** for automating development tasks. See [scripts/README.md](scripts/README.md) for full documentation. + +**Categories:** +- **Image Optimization** - Responsive image generation with WebP support +- **SEO & Performance** - Sitemap generation, PageSpeed testing +- **Internationalization** - Translation file conversion (TS → JSON) +- **Assets & Resources** - Font downloads and self-hosting +- **Icon Generation** - PWA icon creation with placeholders +- **Documentation** - GitHub README and OG image templates + +**Quick Start:** +```bash +npm run build:images # Optimize project images +node scripts/generate-sitemap.js # Generate sitemap +node scripts/pagespeed-check.js # Run performance tests +``` + ## Key Technologies Used **Languages:** TypeScript, Python, MDX diff --git a/package.json b/package.json index e9cc626..dd30165 100644 --- a/package.json +++ b/package.json @@ -10,6 +10,11 @@ "build:images": "node scripts/optimize-images.js", "generate:images": "node scripts/generate-blog-images.mjs", "generate:images:dry": "node scripts/generate-blog-images.mjs --dry-run", + "generate:sitemap": "node scripts/generate-sitemap.js", + "generate:icons": "node scripts/generate-icons.mjs", + "generate:github": "node scripts/generate-github-readme.js", + "download:fonts": "node scripts/download-fonts.mjs", + "convert:translations": "node scripts/convert-translations.js", "test": "vitest", "test:coverage": "vitest run --coverage" }, diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..8a95758 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,352 @@ +# 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//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//` + +**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//index.ts` +- Converts all 3 locales: de, en, sr +- Outputs formatted JSON to `src/messages/.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/` +- 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//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