Merge pull request #11 from damjan1996/auto-claude/021-document-the-scripts-directory-utilities-for-devel
auto-claude: 021-document-the-scripts-directory-utilities-for-devel
This commit is contained in:
Damjan Savic
@@ -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
|
||||
|
||||
@@ -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"
|
||||
},
|
||||
|
||||
@@ -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/<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
|
||||
Reference in New Issue
Block a user