Peritext Reading Tools

By wimmelstein

0+ active installationsVersion 1.2.0

The tool that puts the reader front and center: reading time, a table of contents, related essays, a Listen button and text size. 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.
  • Text size: A− and A+ make the text smaller or larger (from 80% to 150%). The reader’s choice is remembered in their own browser, for every post. Headings keep their size.
  • 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 page for reading in a block theme: a single post, and any view another plugin adds (see “For plugin authors” below).

  • In a theme without a reading rail (Twenty Twenty-Five, Twenty Twenty-Four and most others): reading time, Listen and text size 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, Listen and text size 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, text size, 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 and sets no cookies. Listen uses the speech engine of the visitor’s own browser. Text size keeps the visitor’s choice in their own browser (localStorage, key peritext-reading-tools-text-scale); it is never sent to the site.

For plugin authors: your own reading views

The tools know one kind of page for reading: a single post. A plugin that shows text in other views (a book’s chapters, the whole book on one page, a course) adds them with a filter. The tools are then placed and active there too, and Reading Tools needs to know nothing else about them.

peritext_reading_tools_is_reading_view (bool) decides whether the current page is for reading. Default: `is_singular( 'post' )`. The second argument is the queried object.

add_filter( 'peritext_reading_tools_is_reading_view', function ( $is_reading_view, $queried_object ) {
    return $is_reading_view || is_singular( 'my_chapter' );
}, 10, 2 );

peritext_reading_tools_content_selector (string) names the element that holds the text: the one Listen reads aloud, text size scales and the table of contents is built from. Default: `.wp-block-post-content`, the Post Content block. Any CSS selector; the first match on the page is used.

add_filter( 'peritext_reading_tools_content_selector', function ( $selector, $queried_object ) {
    return my_plugin_is_whole_book_view() ? '.my-book-text' : $selector;
}, 10, 2 );

With the default selector the table of contents is built on the server from the post’s headings. With your own selector it is built in the browser from the h2 and h3 headings inside your element, which get an id if they have none.

In a block theme, the template your view uses gets the same default placement as a single post (under the title, above and below the Post Content block). In the Site Editor the tools show in the single post templates only, since the editor has no page to ask the filter about.

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.

FAQ

Does it work with my theme?

Yes, with any block theme. On a single post the plugin places the tools by itself: reading time, Listen and text size 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.

Can the tools work on my plugin’s own pages?

Yes: see “For plugin authors” above. Two filters, peritext_reading_tools_is_reading_view and peritext_reading_tools_content_selector, say which pages are for reading and which element holds their text.

Why does the text size not change the headings?

The headings keep their size on purpose: A+ is for reading comfort, and the headings already stand out. Text size scales the text element; anything sized relative to it grows with it.

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.2.0

  • New tool: text size. A− and A+ next to Listen make the text smaller or larger; the choice is remembered in the reader’s browser. Switch it off under Settings > Reading Tools like the others.
  • For plugin authors: the filters peritext_reading_tools_is_reading_view and peritext_reading_tools_content_selector add your own views for reading; Listen, text size and the table of contents work on their text.
  • Listen, the table of contents and related essays show on pages for reading only; on any other page they render nothing.

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.