linkpreview-cli 1.0.0

Generate beautiful link previews from any URL with smart image detection

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)

brew install linkpreview-cli

Via pip

pip install linkpreview-cli

From Source

git clone https://github.com/yoel-frischoff/linkpreview-cli.git
cd linkpreview-cli
pip install -e .

🚀 Quick Start

# 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

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

# Generate PNG preview
linkpreview https://newsroom.servicenow.com/press-releases/...

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

Advanced Usage

# 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:

# 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 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 file for details.

🙋 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🏗️ Built With

• Playwright - Browser automation for JavaScript pages
• Pillow - Python Imaging Library
• BeautifulSoup - HTML/XML parsing
• Requests - HTTP library for Python

---

Made with ❤️ by Yoel Frischoff