=== Peritext Reading Tools ===
Contributors: wimmelstein
Tags: reading time, text to speech, related posts, table of contents, block theme
Requires at least: 6.7
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The tool that puts the reader front and center: reading time, a table of contents, related essays and a Listen button. For any block theme.

== Description ==

Peritext Reading Tools puts the reader front and center. A book's peritext is what surrounds the text inside its covers: the title, the contents, the notes. This plugin does that for a long post. It adds a few small blocks for people who write long texts and want them read, without turning the page into a dashboard.

* **Reading time**: "6 min read", placed automatically under the post title (or after the post date).
* **Listen**: a button that reads the post aloud with the browser's own voice. Nothing is sent anywhere; if the browser has no speech engine, the button hides itself.
* **Table of contents**: a linked outline of the post's headings, with the section in view highlighted.
* **Related essays**: up to three other posts that share the most tags with the current one.
* **Tagged stories** and the **Tagged page** template: give a page one or more tags and it shows the posts with those tags as cards, with an optional "Highlighted" row (posts that also carry the tag "highlighted"). If a post has a custom field `amazon_url`, its card also gets a "Read on Amazon" link.

= Placed for you, yours to move =

The blocks are placed for you with block hooks (WordPress 6.4 and later), on a single post in a block theme:

* In a theme **without** a reading rail (Twenty Twenty-Five, Twenty Twenty-Four and most others): reading time and Listen directly under the post title, the table of contents (folded, "On this page", only when the post has two or more headings) above the text, and related essays below it. If the template already shows a post date, reading time and Listen go after the date instead of under the title, never both.
* In a theme **with** a reading rail, a Group block with the CSS class `essay-tools-rail`: the table of contents and related essays go into the rail. The reading time also goes at the end of a group with the class `essay-tools-card`.

Anything you place by hand in a template is not doubled. You can remove or move any of them in the Site Editor, and add the blocks anywhere in a template or post.

Under Settings > Reading Tools you can switch each tool off: reading time, Listen, table of contents, related essays. A switched-off tool is no longer placed automatically, in any theme. Blocks you add yourself always show.

= Works with any block theme =

The styles follow the colors and fonts of the active theme, including dark modes that change the text color, so the tools fit any block theme.

A theme can give the tools a reading rail beside the text: a Group block with the class `essay-tools-rail`. There the table of contents and related essays sit out of the reader's way, and fold into one line on a phone. The author's own theme, Lexis, is built that way.

= Privacy =

The plugin makes no external requests, sets no cookies and stores nothing. Listen uses the speech engine of the visitor's own browser.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install it from Plugins > Add New.
2. Activate it.
3. Open a post. The tools are there: under the title, above the text and below it (or in the theme's reading rail).
4. Optional: Settings > Reading Tools lets you switch single tools off.

== Frequently Asked Questions ==

= Does it work with my theme? =

Yes, with any block theme. On a single post the plugin places the tools by itself: reading time and Listen under the title, a folded table of contents above the text, related essays below it. The styles follow your theme's colors and fonts, in light and dark. If your theme has a template with a Group that carries the class `essay-tools-rail`, the table of contents and related essays go there instead. A classic (non-block) theme is not supported; add the blocks to a block-based page or post instead.

= I changed my single post template in the Site Editor and see nothing new. =

WordPress places hooked blocks when a template is saved, not afterwards. Open the template in the Site Editor and save it once, or add the blocks by hand. If you deleted a tool in the editor, WordPress remembers and does not put it back.

= How do I switch a tool off? =

Settings > Reading Tools. One checkbox per tool; it applies to every theme, including a reading rail.

= How do I change the reading speed? =

Use the `peritext_words_per_minute` filter; the default is 200 words per minute.

= Why do my pages have tags now? =

Pages get the Tags box so the Tagged page template can show the posts with those tags. Tag archives still list posts only.

= The Tagged page template is missing. =

It needs WordPress 6.7 or later. In an older version the plugin does not run its template; the blocks remain.

== Changelog ==

= 1.1.0 =
* New name: Peritext Reading Tools, with a new slug and longer prefixes on everything the plugin declares.

= 1.0.1 =
* Related essays: a lighter query, without post__not_in or tax_query.

= 1.0.0 =
* First release: reading time, Listen, table of contents, related essays, tagged stories and the Tagged page template.
* Sensible defaults in block themes without a reading rail: reading time and Listen under the post title, a folded table of contents above the text, related essays below it. No doubles with a post date or blocks placed by hand.
* Settings > Reading Tools: switch each tool off, everywhere.

== Upgrade Notice ==

= 1.1.0 =
New name and slug.

= 1.0.1 =
A lighter query for related essays.

= 1.0.0 =
First release.
