linkpreview-cli 1.0.0
Generate beautiful link previews from any URL with smart image detection
Requires Python: >=3.8
Keywords: link preview, open graph, metadata, url, social media, image generation, pdf, png

# LinkPreview CLI

🔗 **Generate beautiful link previews from any URL with smart image detection**

LinkPreview CLI is a powerful command-line tool that automatically extracts Open Graph metadata from websites and generates professional link preview images. It features intelligent image detection, JavaScript-rendered page support via Playwright, and both PNG and PDF export options.

## ✨ Features

- **🚀 Smart Extraction**: Automatically detects and extracts Open Graph metadata
- **🧠 JavaScript Support**: Handles modern SPAs and JavaScript-rendered pages with Playwright
- **🎨 Intelligent Layouts**: 
  - Standalone mode for high-quality featured images
  - Text overlay mode for square/tall images
  - Traditional text+image layout for standard previews
- **📄 Multiple Formats**: Export as PNG or PDF
- **⚡ Fast & Reliable**: Built-in fallbacks and error handling
- **🔧 Manual Mode**: Override automatic detection when needed

## 📦 Installation

### Via Homebrew (Recommended)
```bash
brew install linkpreview-cli
```

### Via pip
```bash
pip install linkpreview-cli
```

### From Source
```bash
git clone https://github.com/yoel-frischoff/linkpreview-cli.git
cd linkpreview-cli
pip install -e .
```

## 🚀 Quick Start

```bash
# Generate a link preview
linkpreview https://example.com

# Export as PDF
linkpreview --pdf https://example.com

# Manual mode for blocked sites
linkpreview --manual https://example.com

# Custom output filename
linkpreview https://example.com my_preview.png
```

## 📋 Usage

```bash
linkpreview [OPTIONS] URL [OUTPUT_FILE]

Arguments:
  URL           The URL to generate a preview for
  OUTPUT_FILE   Output filename (optional, auto-generated from title)

Options:
  --pdf         Export as PDF instead of PNG
  --manual, -m  Force manual input of metadata
  --help        Show help message
```

## 🎯 Examples

### Basic Usage
```bash
# Generate PNG preview
linkpreview https://newsroom.servicenow.com/press-releases/...

# Generate PDF preview  
linkpreview --pdf https://canonical.com/blog/...
```

### Advanced Usage
```bash
# Manual mode for sites that block automation
linkpreview --manual https://blocked-site.com
# Then enter title, description, image URL, and site name when prompted

# Custom filename with PDF export
linkpreview --pdf https://example.com conference_preview.pdf
```

## 🧠 Smart Image Detection

The tool automatically determines the best layout based on content quality:

- **📸 Standalone Mode**: High-quality featured images (blog headers, announcements)
- **📝 Text Overlay**: Square/tall images with title text on the left
- **📰 Traditional**: Standard text + image layout

Detection criteria:
- URL patterns (`blog`, `featured`, `announcement`, etc.)
- Image dimensions and aspect ratios
- File naming conventions
- Open Graph metadata quality

## 🔧 Dependencies

- **Python 3.8+**
- **Playwright** (for JavaScript-rendered pages)
- **Pillow** (for image processing)
- **Requests** (for HTTP requests)
- **BeautifulSoup4** (for HTML parsing)

## 📐 Output Specifications

- **Dimensions**: 722×144 pixels (optimized for social sharing)
- **Formats**: PNG (default) or PDF
- **Fonts**: System fonts with Unicode support
- **Quality**: High-resolution with crisp text rendering

## 🚫 Troubleshooting

### Site Blocking Issues
If a website returns 403 Forbidden:
```bash
# Use manual mode
linkpreview --manual https://blocked-site.com
```

### JavaScript-Rendered Pages
The tool automatically detects and handles these with Playwright, but if issues persist:
1. Check your internet connection
2. Try manual mode
3. Verify the URL is correct

### Font Issues
If text appears as squares:
- Ensure system fonts are properly installed
- Try different URLs to verify the issue is font-related

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙋 Support

- 📚 [Documentation](https://github.com/yoel-frischoff/linkpreview-cli/wiki)
- 🐛 [Issue Tracker](https://github.com/yoel-frischoff/linkpreview-cli/issues)
- 💬 [Discussions](https://github.com/yoel-frischoff/linkpreview-cli/discussions)

## 🏗️ Built With

- [Playwright](https://playwright.dev/) - Browser automation for JavaScript pages
- [Pillow](https://pillow.readthedocs.io/) - Python Imaging Library
- [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/) - HTML/XML parsing
- [Requests](https://docs.python-requests.org/) - HTTP library for Python

---

**Made with ❤️ by [Yoel Frischoff](https://github.com/yoel-frischoff)**