=== MLPicks ===
Contributors: rachanapaudel26
Tags: related posts, related content, read next, internal links, recommendations
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Keep readers engaged with fast, smart, and privacy-friendly related post recommendations that never slow down your site.

== Description ==

**MLPicks** helps you keep visitors on your website longer by showing smart, beautiful "Read Next" recommendation cards below your articles.

Most related-posts plugins slow down your website because they search through your database every single time a visitor opens a page. **MLPicks is different:** it matches your articles quietly in the background. When a reader opens an article, the suggestions are already ready and load instantly.

= Key Features =

* **Lightning Fast Page Speed:** Recommendations are pre-calculated in the background. It never delays your page loading, making your site feel snappy and keeping Google Core Web Vitals green.
* **Smart & Accurate Suggestions:** Uses your categories, tags, and article content to find articles that readers actually care about.
* **Smart Personalized Taste Matching:** Recommends stories based on what each reader has been enjoying on your site, completely on your own server.
* **Side-by-Side Comparison (VS) Cards:** Automatically displays related product or topic comparisons side-by-side with prices and specs.
* **100% Privacy-Friendly & GDPR Ready:** Collects zero personal data. No IP addresses, no tracking cookies, and no data is ever sent to external cloud servers.
* **Built-In Click & Impression Analytics:** See exactly which recommendations get the most clicks, which ones need improvement, and which articles have never been suggested yet.
* **Simple Shortcodes:** Place related posts, recent articles, trending stories, or comparison cards anywhere with simple, one-click copyable shortcodes.
* **Theme Friendly & Responsive:** Looks clean and professional out of the box on mobile, tablet, and desktop, naturally matching your WordPress theme's fonts and colors.

== Installation ==

Getting started takes less than two minutes:

1. In your WordPress admin, go to **Plugins > Add New**, search for **MLPicks**, and click **Install Now**. (Or upload the plugin folder directly to `/wp-content/plugins/`).
2. Click **Activate**.
3. MLPicks will immediately begin organizing your existing articles quietly in the background.
4. Go to **MLPicks > Settings** to customize how many cards to show, change the title (e.g., "Read next" or "You might also like"), or exclude specific categories.
5. Visit any post on your site to see your new recommendation cards live!

== Frequently Asked Questions ==

= Does MLPicks slow down my website? =
No. MLPicks is specifically engineered for speed. It never runs heavy database searches while a reader is loading your page. All matching happens quietly in the background via WordPress background tasks.

= Does it work with caching plugins (WP Rocket, LiteSpeed, W3 Total Cache, Cloudflare)? =
Yes, 100%. MLPicks works perfectly with all WordPress caching plugins and CDNs. Because the card HTML is clean and static, it can be cached indefinitely without breaking.

= How does MLPicks pick related articles? =
MLPicks analyzes three things in the background:
1. **Shared Topics:** Matches specific categories and tags between articles.
2. **Content Overlap:** Reads key terms from titles and article text to find topic relevance.
3. **Freshness:** Gives a gentle bonus to newer articles when topics match.

It automatically filters out weak matches so readers only see genuine recommendations.

= What if an article has no related posts? =
You can choose what happens under **MLPicks > Settings**:
* **Show only real matches (Recommended):** Displays only true topic matches. If none exist, it cleanly hides the box so readers never see random, off-topic content.
* **Fill empty spots with latest posts:** Automatically fills any remaining spots with your site's newest published articles.

= Can I hand-pick suggestions for specific posts? =
Yes! When editing any post, scroll to the **MLPicks - Hand-Picked Suggestions** box in the editor. You can search or select specific posts that you always want recommended on that article.

= How do I place recommendations manually with shortcodes? =
You can copy and paste any of these shortcodes into your content, block editor, or widgets:

* `[mlpicks]` - Shows related articles based on the current post.
* `[mlpicks_recommendations]` - Shows personalized recommendations based on the reader's interests.
* `[mlpicks_most_read]` - Shows your most-read or trending articles (e.g. `period="7"` for the past week).
* `[mlpicks_recent_articles]` - Shows your newest published articles.
* `[mlpicks_comparison]` - Shows side-by-side comparison cards (e.g. "iPhone 15 vs Galaxy S24").

All shortcodes and their options can be copied with one click in **MLPicks > Settings > Shortcode**.

= What happens if a post does not have a featured image? =
No problem! MLPicks automatically checks if there is an image inside the article and uses it as the thumbnail. If the article has no images at all, it displays a clean, elegant text teaser card without any broken image icons or blank gaps.

= What kind of data does MLPicks track? =
MLPicks only tracks **anonymous daily numbers**:
* How many times suggestion cards were viewed (Impressions).
* How many times suggestion cards were clicked (Clicks).

It **never** collects IP addresses, cookies, user accounts, or browsing history. Everything is stored directly inside your own WordPress database and never leaves your server.

= How do I hide the recommendation box on a single post? =
When editing a post, check the box labeled **"Hide the Read next box on this post"** in the MLPicks sidebar box.

== Screenshots ==

1. Front-end "Read next" recommendation card grid below an article.
2. Clean, organized Settings panel with the Shortcode guide.
3. Hand-picked suggestion selector in the post editor.
4. Visual Click & Suggestion Report showing your top-clicked stories and average CTR.

== Changelog ==

= 1.0.0 =
* Initial public release.
* Lightweight background matching engine for instant front-end page loads.
* Smart topic matching combining categories, tags, text similarity, and freshness decay.
* Local personalized recommendation engine based on reader interests.
* Side-by-side comparison (VS) cards with automatic competitor matching.
* Full shortcode suite: `[mlpicks]`, `[mlpicks_recommendations]`, `[mlpicks_most_read]`, `[mlpicks_recent_articles]`, and `[mlpicks_comparison]`.
* 100% privacy-safe daily click, view, and viewport impression tracking.
* Comprehensive Click & Suggestion Report with helpful explanatory tooltips.
* Hand-picked suggestion overrides and per-post visibility controls in the editor.
* Multisite compatibility and clean uninstallation cleanup.
