# BlogHero
A simple Python library and CLI tool for generating hero images by overlaying text on background images. Create professional-looking cover images by adding custom titles and subtitles to your background images.
## Features
- 🎨 **Text overlay on background images** - Add titles and subtitles to any image
- 🖼️ **Flexible background support** - Use image files or random selection from directories
- 🎯 **Smart positioning** - Left, center, or right text alignment
- 🌈 **Color customization** - Support for named colors, hex codes, and RGB values
- 📏 **Size preservation** - Output images maintain original background dimensions
- ⚡ **CLI and Python API** - Use in automation workflows or as a library
- 🎛️ **Configurable typography** - Adjust font sizes and families
## Installation
```bash
pip install bloghero
```
Or install from source:
```bash
git clone https://github.com/yourusername/bloghero.git
cd bloghero
poetry install
```
## Quick Start
### Command Line Interface
Generate a hero image with a background file:
```bash
bloghero generate path/to/background.jpg "My Awesome Blog Post"
```
With subtitle and custom styling:
```bash
bloghero generate path/to/background.jpg "My Awesome Blog Post" \
--subtitle "A detailed guide to something amazing" \
--position center \
--title-color blue \
--output hero.jpg
```
Use a directory of background images (random selection):
```bash
bloghero generate path/to/backgrounds/ "Random Background Post" \
--subtitle "Will pick a random image from the directory"
```
### Python API
```python
from bloghero import HeroImageGenerator
generator = HeroImageGenerator()
# Basic usage with background image
image = generator.generate(
background_path="path/to/background.jpg",
title="My Blog Post Title"
)
image.save("hero.jpg")
# Advanced usage with all options
image = generator.generate(
background_path="path/to/backgrounds/", # Directory for random selection
title="Advanced Blog Post",
subtitle="With custom styling",
title_color="white",
subtitle_color="lightgray",
title_size=80,
subtitle_size=40,
font_family="Arial",
position="center"
)
image.save("advanced_hero.jpg", quality=95)
```
## CLI Commands
### Generate Images
```bash
# Basic generation with background image
bloghero generate background.jpg "Title" --output hero.jpg
# With styling options
bloghero generate background.jpg "Title" \
--subtitle "Subtitle" \
--title-color white \
--subtitle-color lightgray \
--title-size 80 \
--subtitle-size 40 \
--position center \
--quality 95
# Using directory for random background selection
bloghero generate /path/to/backgrounds/ "Title" \
--subtitle "Random background from directory"
# Different positioning options
bloghero generate bg.jpg "Left aligned" --position left
bloghero generate bg.jpg "Center aligned" --position center
bloghero generate bg.jpg "Right aligned" --position right
# Color options
bloghero generate bg.jpg "Title" --title-color "#ff0000" # Hex color
bloghero generate bg.jpg "Title" --title-color "rgb(255,0,0)" # RGB
bloghero generate bg.jpg "Title" --title-color "red" # Named color
```
## Configuration Options
### Colors
Supported color formats:
- **Named colors**: `white`, `black`, `red`, `green`, `blue`, `yellow`, `cyan`, `magenta`, `gray`, `orange`, `purple`, `brown`, `pink`, `lime`, `navy`, `silver`, `gold`
- **Hex colors**: `#ffffff`, `#fff`, `ffffff`, `fff`
- **RGB values**: `rgb(255, 255, 255)`
### Positioning
- **left**: Text positioned in the left half of the image (default)
- **center**: Text centered on the image
- **right**: Text positioned in the right half of the image
### Font Sizes
- **title-size**: Font size for main title (default: 72)
- **subtitle-size**: Font size for subtitle (default: 36)
### Background Images
**Single image file:**
```bash
bloghero generate /path/to/image.jpg "Title"
```
**Directory (random selection):**
```bash
bloghero generate /path/to/images/ "Title"
```
Supported image formats: JPEG, PNG, BMP, TIFF
## Examples
### Basic Hero Image Generation
```bash
poetry run bloghero generate examples/background/image1.jpg \
"Bloghero generates hero images for blog posts" \
--output examples/output.png
```
### Basic Text Overlay
```python
from bloghero import HeroImageGenerator
generator = HeroImageGenerator()
image = generator.generate(
background_path="background.jpg",
title="Hello World"
)
image.save("output.jpg")
```
### With Subtitle and Styling
```python
image = generator.generate(
background_path="background.jpg",
title="My Blog Post",
subtitle="A comprehensive guide",
title_color="white",
subtitle_color="lightgray",
position="center",
title_size=80,
subtitle_size=40
)
```
### Random Background from Directory
```python
image = generator.generate(
background_path="images/", # Directory with background images
title="Random Background",
subtitle="Randomly selected from directory"
)
```
## CLI Reference
### Command: generate
```bash
bloghero generate BACKGROUND TITLE [OPTIONS]
```
**Arguments:**
- `BACKGROUND`: Path to background image file or directory
- `TITLE`: Main title text to overlay
**Options:**
- `-s, --subtitle TEXT`: Subtitle text
- `-o, --output PATH`: Output file path
- `--title-color TEXT`: Title color (default: white)
- `--subtitle-color TEXT`: Subtitle color (default: white)
- `--title-size INTEGER`: Title font size (default: 72)
- `--subtitle-size INTEGER`: Subtitle font size (default: 36)
- `--font-family TEXT`: Font family (default: Arial)
- `--position [left|center|right]`: Text position (default: left)
- `--quality INTEGER`: JPEG quality 1-100 (default: 95)
## API Reference
### HeroImageGenerator
```python
from bloghero import HeroImageGenerator
generator = HeroImageGenerator()
image = generator.generate(
background_path: str, # Required: background image or directory
title: str, # Required: main title text
subtitle: Optional[str] = None, # Optional subtitle
title_color: str = "white", # Title color
subtitle_color: str = "white", # Subtitle color
title_size: int = 72, # Title font size
subtitle_size: int = 36, # Subtitle font size
font_family: str = "Arial", # Font family
position: str = "left" # Text position: left/center/right
) -> PIL.Image.Image
```
## Requirements
- Python 3.11+
- Pillow (PIL)
- Click
- Pydantic
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/yegortokmakov/bloghero",
"name": "bloghero",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "blog, hero, image, generation, cli, automation",
"author": "Yegor Tokmakov",
"author_email": "yegor@tokmakov.biz",
"download_url": "https://files.pythonhosted.org/packages/30/bf/f7faddbbf4495211ca72bfde622e8b259c4d6e7be6b2d47f37b113ce7d19/bloghero-0.1.0.tar.gz",
"platform": null,
"description": "# BlogHero\n\nA simple Python library and CLI tool for generating hero images by overlaying text on background images. Create professional-looking cover images by adding custom titles and subtitles to your background images.\n\n## Features\n\n- \ud83c\udfa8 **Text overlay on background images** - Add titles and subtitles to any image\n- \ud83d\uddbc\ufe0f **Flexible background support** - Use image files or random selection from directories\n- \ud83c\udfaf **Smart positioning** - Left, center, or right text alignment\n- \ud83c\udf08 **Color customization** - Support for named colors, hex codes, and RGB values\n- \ud83d\udccf **Size preservation** - Output images maintain original background dimensions\n- \u26a1 **CLI and Python API** - Use in automation workflows or as a library\n- \ud83c\udf9b\ufe0f **Configurable typography** - Adjust font sizes and families\n\n## Installation\n\n```bash\npip install bloghero\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/yourusername/bloghero.git\ncd bloghero\npoetry install\n```\n\n## Quick Start\n\n### Command Line Interface\n\nGenerate a hero image with a background file:\n\n```bash\nbloghero generate path/to/background.jpg \"My Awesome Blog Post\"\n```\n\nWith subtitle and custom styling:\n\n```bash\nbloghero generate path/to/background.jpg \"My Awesome Blog Post\" \\\n --subtitle \"A detailed guide to something amazing\" \\\n --position center \\\n --title-color blue \\\n --output hero.jpg\n```\n\nUse a directory of background images (random selection):\n\n```bash\nbloghero generate path/to/backgrounds/ \"Random Background Post\" \\\n --subtitle \"Will pick a random image from the directory\"\n```\n\n### Python API\n\n```python\nfrom bloghero import HeroImageGenerator\n\ngenerator = HeroImageGenerator()\n\n# Basic usage with background image\nimage = generator.generate(\n background_path=\"path/to/background.jpg\",\n title=\"My Blog Post Title\"\n)\nimage.save(\"hero.jpg\")\n\n# Advanced usage with all options\nimage = generator.generate(\n background_path=\"path/to/backgrounds/\", # Directory for random selection\n title=\"Advanced Blog Post\",\n subtitle=\"With custom styling\",\n title_color=\"white\",\n subtitle_color=\"lightgray\",\n title_size=80,\n subtitle_size=40,\n font_family=\"Arial\",\n position=\"center\"\n)\nimage.save(\"advanced_hero.jpg\", quality=95)\n```\n\n## CLI Commands\n\n### Generate Images\n\n```bash\n# Basic generation with background image\nbloghero generate background.jpg \"Title\" --output hero.jpg\n\n# With styling options\nbloghero generate background.jpg \"Title\" \\\n --subtitle \"Subtitle\" \\\n --title-color white \\\n --subtitle-color lightgray \\\n --title-size 80 \\\n --subtitle-size 40 \\\n --position center \\\n --quality 95\n\n# Using directory for random background selection\nbloghero generate /path/to/backgrounds/ \"Title\" \\\n --subtitle \"Random background from directory\"\n\n# Different positioning options\nbloghero generate bg.jpg \"Left aligned\" --position left\nbloghero generate bg.jpg \"Center aligned\" --position center\nbloghero generate bg.jpg \"Right aligned\" --position right\n\n# Color options\nbloghero generate bg.jpg \"Title\" --title-color \"#ff0000\" # Hex color\nbloghero generate bg.jpg \"Title\" --title-color \"rgb(255,0,0)\" # RGB\nbloghero generate bg.jpg \"Title\" --title-color \"red\" # Named color\n```\n\n## Configuration Options\n\n### Colors\n\nSupported color formats:\n\n- **Named colors**: `white`, `black`, `red`, `green`, `blue`, `yellow`, `cyan`, `magenta`, `gray`, `orange`, `purple`, `brown`, `pink`, `lime`, `navy`, `silver`, `gold`\n- **Hex colors**: `#ffffff`, `#fff`, `ffffff`, `fff`\n- **RGB values**: `rgb(255, 255, 255)`\n\n### Positioning\n\n- **left**: Text positioned in the left half of the image (default)\n- **center**: Text centered on the image\n- **right**: Text positioned in the right half of the image\n\n### Font Sizes\n\n- **title-size**: Font size for main title (default: 72)\n- **subtitle-size**: Font size for subtitle (default: 36)\n\n### Background Images\n\n**Single image file:**\n\n```bash\nbloghero generate /path/to/image.jpg \"Title\"\n```\n\n**Directory (random selection):**\n\n```bash\nbloghero generate /path/to/images/ \"Title\"\n```\n\nSupported image formats: JPEG, PNG, BMP, TIFF\n\n## Examples\n\n### Basic Hero Image Generation\n\n```bash\npoetry run bloghero generate examples/background/image1.jpg \\\n \"Bloghero generates hero images for blog posts\" \\\n --output examples/output.png\n```\n\n\n\n### Basic Text Overlay\n\n```python\nfrom bloghero import HeroImageGenerator\n\ngenerator = HeroImageGenerator()\nimage = generator.generate(\n background_path=\"background.jpg\",\n title=\"Hello World\"\n)\nimage.save(\"output.jpg\")\n```\n\n### With Subtitle and Styling\n\n```python\nimage = generator.generate(\n background_path=\"background.jpg\",\n title=\"My Blog Post\",\n subtitle=\"A comprehensive guide\",\n title_color=\"white\",\n subtitle_color=\"lightgray\",\n position=\"center\",\n title_size=80,\n subtitle_size=40\n)\n```\n\n### Random Background from Directory\n\n```python\nimage = generator.generate(\n background_path=\"images/\", # Directory with background images\n title=\"Random Background\",\n subtitle=\"Randomly selected from directory\"\n)\n```\n\n## CLI Reference\n\n### Command: generate\n\n```bash\nbloghero generate BACKGROUND TITLE [OPTIONS]\n```\n\n**Arguments:**\n\n- `BACKGROUND`: Path to background image file or directory\n- `TITLE`: Main title text to overlay\n\n**Options:**\n\n- `-s, --subtitle TEXT`: Subtitle text\n- `-o, --output PATH`: Output file path\n- `--title-color TEXT`: Title color (default: white)\n- `--subtitle-color TEXT`: Subtitle color (default: white)\n- `--title-size INTEGER`: Title font size (default: 72)\n- `--subtitle-size INTEGER`: Subtitle font size (default: 36)\n- `--font-family TEXT`: Font family (default: Arial)\n- `--position [left|center|right]`: Text position (default: left)\n- `--quality INTEGER`: JPEG quality 1-100 (default: 95)\n\n## API Reference\n\n### HeroImageGenerator\n\n```python\nfrom bloghero import HeroImageGenerator\n\ngenerator = HeroImageGenerator()\nimage = generator.generate(\n background_path: str, # Required: background image or directory\n title: str, # Required: main title text\n subtitle: Optional[str] = None, # Optional subtitle\n title_color: str = \"white\", # Title color\n subtitle_color: str = \"white\", # Subtitle color\n title_size: int = 72, # Title font size\n subtitle_size: int = 36, # Subtitle font size\n font_family: str = \"Arial\", # Font family\n position: str = \"left\" # Text position: left/center/right\n) -> PIL.Image.Image\n```\n\n## Requirements\n\n- Python 3.11+\n- Pillow (PIL)\n- Click\n- Pydantic\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Python library and CLI tool for generating hero images by overlaying text on background images",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/yegortokmakov/bloghero/issues",
"Documentation": "https://github.com/yegortokmakov/bloghero#readme",
"Homepage": "https://github.com/yegortokmakov/bloghero",
"Repository": "https://github.com/yegortokmakov/bloghero"
},
"split_keywords": [
"blog",
" hero",
" image",
" generation",
" cli",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "448215be36f1c1f077f9db6cf048ac88cb3b8d991475bc1bd826b1d509d2ee7e",
"md5": "b67648a969172f79a509a4fbacd1f305",
"sha256": "a7847c3a9900d98aba6877d8d025a9cf30786eb9127274f14b48ba15b0238e72"
},
"downloads": -1,
"filename": "bloghero-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b67648a969172f79a509a4fbacd1f305",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 14862,
"upload_time": "2025-07-23T15:46:38",
"upload_time_iso_8601": "2025-07-23T15:46:38.573070Z",
"url": "https://files.pythonhosted.org/packages/44/82/15be36f1c1f077f9db6cf048ac88cb3b8d991475bc1bd826b1d509d2ee7e/bloghero-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "30bff7faddbbf4495211ca72bfde622e8b259c4d6e7be6b2d47f37b113ce7d19",
"md5": "3001a65ac8b4dab6ae7dd87f5014283e",
"sha256": "2731477062e9af361830c76cab4a979447935fb4d8046e9a905dfca20a7a566c"
},
"downloads": -1,
"filename": "bloghero-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3001a65ac8b4dab6ae7dd87f5014283e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 14702,
"upload_time": "2025-07-23T15:46:39",
"upload_time_iso_8601": "2025-07-23T15:46:39.762444Z",
"url": "https://files.pythonhosted.org/packages/30/bf/f7faddbbf4495211ca72bfde622e8b259c4d6e7be6b2d47f37b113ce7d19/bloghero-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 15:46:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yegortokmakov",
"github_project": "bloghero",
"github_not_found": true,
"lcname": "bloghero"
}
JSON
