Pixel Banner is a plugin for Obsidian that allows you to automatically add beautiful banner images to your notes using the Pexels/Pixabay APIs, direct URLs, or folder-specific settings. Enhance your note-taking experience with visually appealing headers that provide context and improve the overall aesthetics of your notes.
- Automatically fetch and display banner images from Pexels/Pixabay based on keywords
- Use direct URLs for custom images
- Use local images from your vault
- Use Obsidian internal links to images
- Set folder-specific default banner images
- Customize image size and orientation
- Set default keywords for when no specific keyword is provided
- Adjust vertical position of the banner image globally, per folder, or per note
- Customize banner height (100-2500 pixels)
- Control fade transparency (-1500 to 100)
- Customize frontmatter field names
- Set a custom start position for the content below the banner image
- Set the banner image display to cover or contain and adjust wrapping
- Seamless integration with Obsidian's interface
- Banner Image Border radius customization
- Customize banner appearance with height, fade effect, and border radius
- Pin API images to your vault for permanent use (saves to local vault and updates note frontmatter)
- Refresh random API images with a single click to get a new image for the same keyword(s)
- Clean up orphaned pinned images
- Option to hide Pixel Banner fields (in the properties section) from displaying in Reading Mode
- Customize inline title color globally, per folder, or per note (requires Obsidian's "Show inline title" setting)
- Open Obsidian and go to Settings
- Navigate to Community Plugins and disable Safe Mode
- Click on Browse and search for "Pexels Banner" or "Pixel Banner"
- Install the plugin and enable it
- Unzip the latest release into your
<vault>/.obsidian/plugins/folder.
- Obtain a free API key from Pexels or Pixabay
- In Obsidian, go to Settings > Pixel Banner and enter your API key(s)
- In any note, add a
bannerfield to the frontmatter with keywords for the desired image, a direct URL, a path to a local image, or an Obsidian internal link:
---
banner: blue turtle
---
### Or use a direct URL:
---
banner: https://example.com/image.jpg
---
### Or use a local image:
---
banner: /path/to/local/image.jpg
---
### Or use an Obsidian internal link:
---
banner: [[path/to/internal/image.jpg]]
---
### All settings can be overridden per note:
---
banner: ocean
banner-y: 30
content-start: 90
banner-display: contain
banner-repeat: true
banner-height: 500
banner-fade: -75
banner-radius: 50
banner-title-color: "#FF5733"
---You can set default banner images for entire folders:
- Go to Settings > Pixel Banner
- Scroll down to the "Folder Images" section
- Click "Add Folder Image"
- Configure the folder settings:
- Folder path
- Image URL or keyword
- Y-position (0-100)
- Banner height (100-2500 pixels)
- Fade effect (-1500 to 100)
- Display mode and repeat settings
- Direct Children Only: Enable this option to apply the banner settings only to the direct children of the specified folder, excluding subfolders.
- Repeat for additional folders as needed
Folder-specific settings will apply to all notes in that folder (and subfolders) that don't have their own banner specified in the frontmatter, unless the "Direct Children Only" option is enabled.
In the plugin settings, you can customize:
- API Provider (Pexels or Pixabay)
- Test your API keys directly in settings with the "Test API" button
- Get immediate feedback if your API key is valid
- Image size (small, medium, large)
- Image orientation (landscape, portrait, square)
- Number of images to fetch (1-50)
- Default keywords for when no specific keyword is provided
- Global y-position of the banner image (0-100)
- Global banner height (100-2500 pixels, default 350)
- Global fade effect (-1500 to 100, default -75)
- Custom field names for all settings
- Folder-specific default banner images
- Global border radius (0-50 pixels, default 17)
- Global title color (requires Obsidian's "Show inline title" setting)
All global settings can be overridden on a per-folder or per-note basis.
You can customize the frontmatter field names used for each setting, and even define multiple names for each field. For example, if you set the banner field names to "banner, header-image, cover" and the Y-position field names to "banner-y, y-pos", you could use any of these variations in your frontmatter:
---
header-image: sunset
y-pos: 22
---
---
banner-y: 60
y-pos: 60
---
---
header-image: sunset
banner-y: 30
---Field names must follow these rules:
- Only letters, numbers, dashes, and underscores are allowed
- No spaces within field names (spaces after commas are fine)
- Names must be unique across all fields
When using random images from Pexels or Pixabay, you'll see a pin icon (📌) in the top left corner of the banner. Click this to:
- Save the image to your vault
- Update your note's frontmatter to use the local image
- Never lose that perfect banner image again!
You can configure the save location and manage orphaned pins in settings.
If you enjoy this plugin please consider sending me a tip to support my work 😀
If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository.
