=== Herodotus - On This Day ===
Contributors: merkucio
Tags: this day in history, events, dates, recurring, history
Requires at least: 5.6
Tested up to: 6.9
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create an "On This Day" section on your WordPress site. Displays posts based on day and month — automatically, every year.

== Description ==

**Herodotus** is a specialized tool for creating recurring historical events based on Day and Month, making it perfect for "This Day in History", birthdays, anniversaries, or any annual recurring timeline.

Unlike the default WordPress behavior where posts are tied to a specific publication year, Herodotus introduces its own **`herodotus_post`** Custom Post Type. You simply pick a day and a month from the custom date picker in the block editor, and your post will automatically appear on that exact day *every single year*.

**Key Features:**

* **Dedicated Custom Post Type** — keeps your regular blog posts completely separate from historical events.
* **Custom Taxonomy** — group historical events into categories like "Science", "Politics", "Birthdays", etc.
* **Annual Recursion** — just set "May 15" and the post appears every May 15, forever.
* **Two Layouts** — standard list layout for pages, compact layout ideal for sidebars and widgets.
* **Shortcode & Gutenberg Block** — use `[herodotus]` or the included block to display events anywhere.
* **Year Support** — set the year of the event for display purposes.
* **Year Badge** — the historical year is displayed as a badge on each event card, so visitors immediately see when the event occurred.
* **Category Filtering** — display posts from a specific category using `[herodotus category="history"]`.
* **Category Labels** — category is displayed on each event card and on the single event page.
* **Hide Images** — show posts as text-only using `[herodotus show_image="false"]`.
* **Open Graph & Twitter Card** — automatic meta tags for beautiful social media sharing previews.
* **Schema.org Markup** — JSON-LD structured data (Article, Event, CollectionPage) for better SEO and Google rich results. Automatically disabled if Yoast SEO, RankMath, AIOSEO or The SEO Framework is active.
* **Timezone Aware** — strictly respects your WordPress timezone settings.
* **WPML & Polylang Ready** — includes `wpml-config.xml` for full multilingual compatibility.
* **Translation Ready** — includes translations for Georgian, Russian, Ukrainian, French, German, Spanish, Italian and Turkish.
* **Caching** — built-in transient caching for fast frontend performance.
* **Sortable Admin Columns** — the posts list in the admin shows "Herodotus Date" and "Year" columns, both clickable to sort your events by date or year.

**Available Shortcode Attributes:**

* `[herodotus]` — show today's posts using global settings.
* `[herodotus layout="compact"]` — compact view, ideal for sidebars.
* `[herodotus limit="5"]` — limit to first 5 posts.
* `[herodotus category="history"]` — show posts from a specific category (use slug).
* `[herodotus excerpt_words="15"]` — set custom excerpt length.
* `[herodotus show_image="false"]` — hide images, show only title, excerpt and Read more.
* `[herodotus order="DESC"]` — reverse sort order for this instance (overrides the global setting).

== Installation ==

1. Upload the entire `herodotus` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. A new **Herodotus - On This Day** menu item will appear in your WordPress admin sidebar.
4. Go to **Herodotus → Add New** and create your first historical event.
5. In the editor, use the **Herodotus Date** metabox (right sidebar) to set the day, month and year.
6. Place the shortcode `[herodotus]` or the **Herodotus Events** Gutenberg block on any page or widget area.

== Frequently Asked Questions ==

= What is Herodotus for? =
Herodotus is designed for creating "On This Day in History" sections on your website. You create posts tied to a specific day and month, and they automatically appear every year on that date. It is ideal for history blogs, music, art & educational sites, museum websites, anniversary trackers, and birthday calendars.

= Does this plugin modify my existing posts or pages? =
No. Herodotus uses its own dedicated Custom Post Type (`herodotus_post`). Your standard WordPress Posts, Pages, and any other content remain completely untouched.

= How is this different from regular WordPress posts? =
Regular WordPress posts are tied to the date they were published and appear in chronological order. Herodotus posts are tied to a recurring day and month — they have no "publication date" in the traditional sense and will appear automatically every year on the same day.

= Does it support leap years (February 29th)? =
Yes. You can set February 29th as the date. On non-leap years, this post will not be shown, which is the correct and expected behavior.

= How do I display today's events on my site? =
Use the shortcode `[herodotus]` in any post, page or text widget. Alternatively, use the included **Herodotus Events** Gutenberg block which you can find in the block inserter.

= Can I show events from a specific category only? =
Yes. Use the `category` attribute with the category slug: `[herodotus category="science"]`. You can create and manage categories under **Herodotus → Categories**.

= What is the compact layout and when should I use it? =
The compact layout (`[herodotus layout="compact"]`) shows posts with a small square thumbnail, title and a short excerpt — without the category label or Read more button. It is designed specifically for sidebar widgets where space is limited.

= Can I hide images and show only text? =
Yes. Use `[herodotus show_image="false"]` to hide all images including the default placeholder. Posts will show only the title, excerpt and — on full pages — the Read more link.

= What happens if a post has no featured image? =
By default, a placeholder "No Image" graphic is shown. You can replace this placeholder with any image of your choice by going to **Settings → Herodotus** and uploading a custom Default Image.

= Can I use multiple shortcodes on the same page? =
Yes. Each shortcode instance is independent and can have its own layout, category, limit and other settings.

= How does caching work? =
Herodotus uses WordPress transients to cache query results. The default cache lifetime is 3600 seconds (1 hour). You can adjust this under **Settings → Herodotus → Cache Settings**, or set it to 0 to disable caching entirely. The cache is automatically cleared whenever a Herodotus post is saved or deleted.

= Is the plugin compatible with WPML and Polylang? =
Yes. The plugin includes a `wpml-config.xml` file which automatically configures WPML to handle the custom post type, taxonomy and date meta fields correctly. Polylang works automatically as well since the CPT and taxonomy are registered with standard WordPress hooks. The cache key includes the current locale so different language versions are cached separately.

= Is the plugin translation ready? =
Yes. The plugin is fully internationalized. Translations are included for: Georgian (ka_GE), Russian (ru_RU), Ukrainian (uk), French (fr_FR), German (de_DE), Spanish (es_ES), Italian (it_IT) and Turkish (tr_TR). Additional translations can be contributed via the WordPress.org translation system (GlotPress).

= I see a red warning in the post editor — what does it mean? =
The red warning appears when a Herodotus post does not have a day, month or year set. All three fields are required — posts without a complete date will never appear on the frontend. Simply click the date field in the Herodotus Date metabox (right sidebar) to set the date.

= I see a warning icon (⚠) in the posts list — what does it mean? =
The ⚠ icon in the Herodotus Date or Year column means that post is missing date information and will not be shown on the frontend until the date is set.

= Can I sort events within the same date? =
Yes. Under **Settings → Herodotus → General Settings** you can choose between A → Z (alphabetical) and Z → A (reverse alphabetical) sorting. Events are always grouped by date first, then sorted by your chosen order.

= What data does the plugin store and what happens when I uninstall it? =
The plugin stores Herodotus posts (as a custom post type), categories (as a custom taxonomy), plugin settings (in `wp_options`) and temporary cache (as transients). By default, all data is kept when the plugin is uninstalled. If you want all data to be permanently deleted on uninstall, enable the **Remove Data on Uninstall** option under **Settings → Herodotus → Advanced**.

= Does the plugin add Open Graph or Schema.org markup? =
Yes. Herodotus automatically adds Open Graph and Twitter Card meta tags on single event pages and category archive pages, enabling rich previews when sharing links on Facebook, Twitter/X, Telegram and other platforms. It also outputs JSON-LD Schema.org structured data (`Article`, `Event`, `CollectionPage`) to help search engines understand your content. If Yoast SEO, RankMath, AIOSEO or The SEO Framework is active, Herodotus automatically skips its own tags to avoid duplicates.

= Is the plugin compatible with page builders (Elementor, Divi, Beaver Builder)? =
The shortcode `[herodotus]` works in any environment that supports standard WordPress shortcodes, including Elementor text/shortcode widgets, Divi Code modules and Beaver Builder HTML modules.

= Does the plugin work with caching plugins (WP Super Cache, W3 Total Cache, LiteSpeed Cache)? =
Yes. Herodotus has its own internal caching layer. It works alongside page-level caching plugins without conflict. Note that if you use aggressive full-page caching, the displayed date may be cached at the page level — consider excluding the pages with `[herodotus]` from full-page caching, or using a shorter cache TTL.

== Screenshots ==

1. Frontend list layout with featured images and compact widget in the sidebar - showing today's historical events.
2. Frontend list layout with images hidden (`show_image="false"`) and compact widget in the sidebar.
3. Category archive page - displays today's posts filtered by a specific Herodotus category.
4. Post editor - the Herodotus Date metabox for setting day, month and year of the historical event.
5. Plugin settings page - configure posts limit, sort order, excerpt length and default image.
6. Plugin settings page - Shortcodes Library - Ready-to-use Shortcodes.

== Changelog ==

= 1.0.0 =
* Initial public release.
* Dedicated Custom Post Type (`herodotus_post`) and Custom Taxonomy (`herodotus_category`).
* Shortcode `[herodotus]` with attributes: `layout`, `limit`, `category`, `excerpt_words`, `show_image`.
* Two layouts: `list` (standard page layout) and `compact` (sidebar/widget layout).
* Gutenberg block support.
* Custom date metabox with day, month and year fields.
* Red warning in metabox and ⚠ icon in posts list for posts missing date.
* Built-in transient caching with configurable lifetime.
* WPML compatibility via `wpml-config.xml`.
* Polylang compatibility — cache key includes locale.
* Plugin settings page: posts limit, sort order, excerpt length, default image, cache TTL, uninstall behavior.
* Translation ready — includes translations for: French, German, Spanish, Italian, Turkish, Georgian, Ukrainian, Russian.