npm package: @my-ginger-pussy/eleventy-social-images-v3
Description: Dynamically generate social media images for your Eleventy pages, suitable for Eleventy V3+ and Vento templates.
Author: Will Moody
Latest version: 1.0.11

# Eleventy Plugin: Generate Social Images (using SVG)

Dynamically generate social media images for your Eleventy (11ty) pages. This plugin uses SVG & does not depend on Puppeteer!

This version supports Eleventy 3.0.0+ and is compatible with Vento, Nunjucks, and Liquid templating engines.

## ✨ Features

- 🚀 **Fast**: Uses SVG + Sharp instead of Puppeteer
- 🎨 **Customizable**: Configure colours, fonts, layout, and more
- 📱 **Responsive**: Generates perfect 1200x628 social media images
- ⚡ **Modern**: Built for Eleventy v3+ with ESM support
- 🔧 **Template Agnostic**: Works with Vento, Nunjucks, and Liquid
- 🎯 **Zero Config**: Works out of the box with sensible defaults

## 📦 Installation

```bash
npm install @my-ginger-pussy/eleventy-social-images-v3
```

## 🚀 Quick Start

### 1. Add to your Eleventy config

```js
// .eleventy.js
import generateSocialImages from "@my-ginger-pussy/eleventy-social-images-v3";

export default async function (eleventyConfig) {
  eleventyConfig.addPlugin(generateSocialImages, {
    promoImage: "./src/img/profile.jpg",
    siteUrl: "https://example.com",
    siteEmail: "hello@example.com",
    titleColor: '#ffffff',
    bgGradient: ['#667eea', '#764ba2']
  });
}
```

### 2. Use in your templates

**Vento templates:**

```html
<meta property="og:image" content="{{ await GenerateSocialImage(title) }}" />
<meta name="twitter:image" content="{{ await GenerateSocialImage(title) }}" />
```

**Nunjucks/Liquid templates:**

```html
<meta property="og:image" content="{% GenerateSocialImage title %}" />
<meta name="twitter:image" content="{% GenerateSocialImage title %}" />
```

## ⚙️ Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `promoImage` | string | - | Path to profile/logo image |
| `outputDir` | string | `./_site/img/preview` | Output directory for images |
| `urlPath` | string | `/img/preview` | URL path for generated images |
| `siteUrl` | string | - | Website URL to display |
| `siteEmail` | string | - | Email address to display |
| `titleColor` | string | `#FFF` | Color of the title text |
| `bgColor` | string | - | Solid background color |
| `bgGradient` | array | `['#647DEE', '#7F53AC']` | Gradient background colors |
| `terminalBgColor` | string | `#404040` | Terminal window background |
| `hideTerminal` | boolean | `false` | Hide terminal window design |
| `customSVG` | string | - | Custom SVG elements |
| `customFontFilename` | string | - | Custom font file path |
| `lineBreakAt` | number | `35` | Characters per line for title wrapping |

## 🎨 Customization Examples

### Custom Colors

```js
eleventyConfig.addPlugin(generateSocialImages, {
  titleColor: '#2d3748',
  bgColor: '#f7fafc',
  terminalBgColor: '#1a202c'
});
```

### Custom Gradient

```js
eleventyConfig.addPlugin(generateSocialImages, {
  bgGradient: ['#ff6b6b', '#4ecdc4', '#45b7d1']
});
```

### Minimal Design

```js
eleventyConfig.addPlugin(generateSocialImages, {
  hideTerminal: true,
  bgColor: '#ffffff',
  titleColor: '#000000'
});
```

## 🛠️ Requirements

- Node.js 18+
- Eleventy 3.0.0+
- Sharp (automatically installed)

## 🔧 Troubleshooting

### Custom Fonts

To use custom fonts, you need to configure fontconfig:

1. Create a `fonts/` directory in your project
2. Add your font files (`.ttf`, `.otf`, etc.)
3. Create `fonts.conf`:

   ```xml

   <?xml version="1.0"?>
   <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
   <fontconfig>
     <dir prefix="default">fonts</dir>
   </fontconfig>
   ```

4. Set environment variable: `FONTCONFIG_PATH=.`

### Common Issues

- **Images not generating**: Check file paths and permissions
- **Fonts not loading**: Verify fontconfig setup
- **Vento syntax errors**: Use `await` with the function call