=== BlueFeed ===
Contributors: alexhedstrom
Tags: bluesky, social media, feed, shortcode, instagram grid
Requires at least: 6.3
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.12
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display your Bluesky feed on any WordPress page or post with a simple shortcode. Multiple layouts including an image grid.

== Description ==

**BlueFeed** lets you embed your Bluesky feed anywhere on your WordPress site using the `[bluefeed]` shortcode. Choose from four beautiful layouts:

* **Classic** – A familiar social-media timeline look
* **Cards** – A responsive card grid, great for visual content
* **Compact** – A minimal, space-efficient list view
* **Images** – An image grid, square image grid showing only posts with images, with hover overlays for likes and comments

= Features =

* 4 layout styles (classic, cards, compact, images)
* Gutenberg block with live preview and full settings panel
* Configurable column count for grid layouts
* Profile header with avatar, banner, bio, and stats
* Clickable links and @mentions auto-linked
* Follow button linking to the Bluesky profile
* Color customization via admin settings or per-shortcode attributes
* Automatic caching with configurable duration for fast page loads
* Stale-cache fallback. Serves cached content if the API is temporarily unreachable
* Test Connection button in admin to diagnose API connectivity
* Compatible with page builders (Breakdance, Elementor, Beaver Builder, etc.)
* Responsive design for all screen sizes
* Translation-ready
* Works with the public Bluesky API. No authentication required

= Shortcode Examples =

    [bluefeed]
    [bluefeed layout="images" columns="4" count="12"]
    [bluefeed layout="compact" count="5" show_header="false"]
    [bluefeed handle="other.bsky.social" layout="classic"]

= Shortcode Parameters =

**Layout & Display:**

* `layout` – classic, cards, compact, or images (default: classic)
* `count` – Number of posts (default: 9, max 100)
* `handle` – Override the Bluesky handle from settings
* `columns` – Grid columns for images/cards (default: 3)
* `gap` – Space between posts/cards in pixels (default: auto per layout)
* `border_radius` – Corner rounding in pixels (default: 12, use 0 for square)
* `border_width` – Border thickness in pixels (default: 1, images layout defaults to 0)
* `show_header` – Show profile header: true/false (default: true)
* `show_replies` – Include replies in the feed: true/false (default: false)
* `show_images` – Show images in classic/cards layouts: true/false (default: false)
* `show_follow` – Show follow button: true/false (default: true)
* `show_caption` – Show post caption on hover in images layout: true/false (default: false)
* `show_avatar` – Show post author avatar: true/false (default: true)
* `show_name` – Show post author display name: true/false (default: true)
* `show_handle` – Show post author @handle: true/false (default: true)
* `show_time` – Show post timestamp: true/false (default: true)
* `show_stats` – Show stats bar (replies, reposts, likes) on all layouts including images overlay: true/false (default: true)

**Color Overrides (hex values, e.g. #ffffff):**

* `card_bg`, `placeholder_bg`, `post_text`, `meta_text`, `card_border`
* `link_color`, `link_hover`, `row_hover_bg`, `header_name`
* `follow_text`, `follow_bg`, `follow_border`, `follow_hover_text`, `follow_hover_bg`

== Installation ==

1. Upload the `bluefeed` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Go to **Settings → BlueFeed** and enter your Bluesky handle
4. Add the `[bluefeed]` shortcode to any page or post

== Frequently Asked Questions ==

= Do I need a Bluesky account? =

You need a Bluesky handle to display a feed. The plugin uses the public API to fetch posts. No App Password or authentication is required.

= Can I show multiple feeds on one page? =

Yes! Use the `handle` parameter to show different accounts:

    [bluefeed handle="user1.bsky.social"]
    [bluefeed handle="user2.bsky.social"]

= How does the Images layout work? =

The Images layout automatically filters to only show posts that contain images, displaying them in an square grid. When visitors hover over an image, they see the reply, repost, and like counts.

= Can I customize the colors? =

Yes. You can set global default colors in **Settings → BlueFeed → Color Customization**, or override colors per-shortcode using color attributes like `card_bg="#1a1a2e"`.

= The feed shows a connection error. What should I do? =

Go to **Settings → BlueFeed** and click **Test Connection**. This will tell you whether your server can reach the Bluesky API. If it times out, your hosting provider may be blocking outbound HTTPS requests. Contact them to whitelist `public.api.bsky.app`.

= How does caching work? =

Feed data is cached for 15 minutes by default (configurable in settings). If the API is temporarily unreachable, the plugin serves the last cached data instead of showing an error.

= Is the plugin translatable? =

Yes. BlueFeed is fully translation-ready and ships with English (en_US) and Swedish (sv_SE) translations covering the admin settings page, Gutenberg block editor, and front-end strings. Translators can use the included `languages/bluefeed.pot` template, or contribute via [translate.wordpress.org](https://translate.wordpress.org/).

== External services ==

This plugin connects to the **Bluesky public API** to retrieve and display Bluesky social media content on your WordPress site. It is required for all plugin functionality. Without it, no feed or profile data can be displayed.

= What data is sent and when =

* **Profile requests** – When a page containing the `[bluefeed]` shortcode is loaded, the plugin sends the configured Bluesky handle to the endpoint `https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile` to retrieve the user's profile information (display name, avatar, banner, bio, and follower/following/post counts).
* **Feed requests** – On the same page load, the plugin sends the Bluesky handle along with display parameters (post count, filter type) to the endpoint `https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed` to retrieve the user's posts.

No visitor personal data, cookies, or tracking information is sent to the API. Responses are cached locally on your server (default 15 minutes, configurable) to reduce the number of external requests.

= Service provider =

This service is provided by **Bluesky PBC** ([bsky.app](https://bsky.app)).

* [Terms of Service](https://bsky.social/about/support/tos)
* [Privacy Policy](https://bsky.social/about/support/privacy-policy)

== Screenshots ==

1. Classic layout – familiar timeline view
2. Cards layout – responsive grid
3. Images layout – Instagram-style image grid with hover stats
4. Compact layout – minimal list view
5. Admin settings page with color customization

== Changelog ==

= 1.0.12 =
* Fixed small bugs

= 1.0.11 =
* Added language translation support with full text-domain
* Added `bluefeed.pot` template for translators
* Added Bluesky handle/DID validation before API calls

= 1.0.10 =
* Fixed profile header banner image not displaying on WordPress 7.0 beta.
* Added `show_avatar` shortcode parameter and admin setting to show/hide post author avatars (default: true)
* Added `show_name` shortcode parameter and admin setting to show/hide post author display names (default: true)
* Added `show_handle` shortcode parameter and admin setting to show/hide post author @handles (default: true)
* Added `show_time` shortcode parameter and admin setting to show/hide post timestamps (default: true)
* Added `show_stats` shortcode parameter and admin setting to show/hide the stats bar (replies, reposts, likes) on all layouts including the images overlay (default: true)
* New "Post Elements" checkboxes in admin under Layout & Spacing to set global defaults for avatar, name, handle, timestamp, and stats visibility
* All new visibility options available as Gutenberg block toggle controls in the Visibility panel

= 1.0.9 =
* Added Gutenberg block (BlueFeed) with live preview, full settings panel (layout, display, visibility, colors), and server-side rendering
* Frontend CSS is now only loaded on pages that use the BlueFeed shortcode or block

= 1.0.8 =
* Added circuit breaker for Bluesky API requests. When the API is unresponsive, the plugin now serves cached content instantly instead of waiting for the request to time out
* Added a long-lived stale backup cache (24 hours) so cached data survives beyond the normal cache TTL during extended outages
* After a failed API call, subsequent requests skip the API for 5 minutes and serve stale cache immediately, eliminating slow page loads when Bluesky is down

= 1.0.7 =
* Redesigned admin settings page with a tabbed navigation (General, Layout & Spacing, Colors, Shortcodes) for easier navigation

= 1.0.6 =
* Fixed profile header breaking when the Bluesky profile has no banner image. The banner area now always renders with a placeholder background color so the avatar is not cut off
* Fixed bare domain URLs without a protocol (e.g. example.com) not being clickable in the profile bio and post text

= 1.0.5 =
* Added configurable gap/spacing between posts in classic, cards, and images layouts
* New "Card Gap" setting in admin (Settings → BlueFeed → Layout & Spacing)
* New `gap` shortcode parameter to override spacing per-shortcode (e.g. `[bluefeed layout="cards" gap="24"]`)
* Each layout retains its own default spacing when no gap is set (Classic: 12px, Cards: 16px, Images: 4px)
* Added configurable border radius for all card/post elements
* New "Border Radius" setting in admin (Settings → BlueFeed → Layout & Spacing)
* New `border_radius` shortcode parameter (e.g. `[bluefeed border_radius="0"]` for square corners)
* Added configurable border width for all card/post/divider borders
* New "Border Width" setting in admin (Settings → BlueFeed → Layout & Spacing)
* New `border_width` shortcode parameter (default: 1px, images layout defaults to 0)
* URLs, @mentions, and #hashtags are now clickable in the profile bio
* Added #hashtag linking in post text. Links to Bluesky hashtag search
* URLs in posts and bio now display without the http/https prefix for cleaner appearance
* Layout & Spacing settings moved to their own admin section with a dedicated reset button
* Fixed compact layout hover background bleeding outside rounded corners on first and last rows
* Fixed card image radius gap when using larger border widths
* Fixed double line-break spacing in profile bio when URLs or domains are present

= 1.0.4 =
* Added "View Details" link on the Plugins page that opens the WordPress.org plugin information modal

= 1.0.3 =
* Added External services section to readme for third-party API disclosure compliance

= 1.0.2 =
* Fixed copy-to-clipboard button showing both icons at the same time before being clicked

= 1.0.1 =
* Improved compact layout – tighter spacing, smaller avatars, and single-line flow for name and time on both desktop and mobile
* Fixed copy-to-clipboard icons missing on the admin settings page

= 1.0.0 =
* Initial release
* Four layout styles: classic, cards, compact, images
* Profile header with stats
* Caching system
* Public API integration
