auto-claude: subtask-1-1 - Create scripts/README.md with comprehensive documentation
This commit is contained in:
@@ -0,0 +1,322 @@
|
|||||||
|
# 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`
|
||||||
|
|
||||||
|
## 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
|
||||||
Reference in New Issue
Block a user