=== Glossary Tooltip ===
Contributors: jumedeenkhan
Donate link: https://buymeacoffee.com/jumedeenkhan
Tags: glossary, tooltip, dictionary, knowledge base, definitions
Requires at least: 5.6
Requires PHP: 7.4
Tested up to: 7.0
Stable tag: 2.4.5
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Automatically highlight glossary terms in your content and show definitions in a tooltip, plus a searchable A-Z glossary index page.

== Description ==

Glossary Tooltip lets you build a glossary of terms and have the plugin automatically find and highlight those terms wherever they appear in your posts and pages. When a visitor hovers over (or focuses, via keyboard) a highlighted term, a tooltip pops up showing its definition — no need to leave the page or click through to another article.

This is useful for documentation sites, educational content, technical blogs, or any website that uses terms, acronyms, or vocabulary that not every visitor will already know.

= How it works =

1. Create a glossary term (a custom post type called "Glossary") with a title and a definition.
2. The plugin scans your site content and automatically turns matching words into glossary links.
3. Hovering or focusing on a glossary link shows a tooltip with the term's definition.
4. A dedicated glossary index page lists every term alphabetically, with a live search box.

= Main features =

**Automatic term highlighting**

* Automatically detects and highlights glossary terms inside your content.
* Choose which post types are scanned (posts, pages, or any other public post type, including the glossary terms themselves).
* Highlight each term only once per page, a limited number of times, skip every Nth occurrence, or highlight every occurrence.
* Case-sensitive or case-insensitive matching.
* Option to match only whole, space-separated terms so highlighting does not trigger inside compound words.
* Add synonyms/aliases to a term so alternate names or abbreviations are highlighted and link to the same term.
* Per-term visibility controls to exclude an individual term from auto-highlighting and/or the glossary index.
* Exclude highlighting from a specific post or page with the `[glossary_exclude]` shortcode, or with the "Glossary Highlight" setting available on the post/page edit screen.
* Per-post "Glossary Highlight" and "Tooltip" settings (Default, On, or Off) on the post/page edit screen let you override the site-wide highlighting and tooltip behavior for a single post or page.
* Ignore headings and existing links while parsing, and exclude specific HTML tags from parsing.
* Exclude glossary terms from your site's internal search results.
* Highlight only on single posts and pages (skips the homepage, archives, categories, and tags).
* Skip parsing content when no glossary terms exist yet, for better performance.
* Adjustable content-parsing priority for compatibility with other content filters.

**Tooltips**

* Enable or disable tooltips site-wide.
* Set the tooltip excerpt length (number of words shown from the term's description).
* Choose the tooltip position relative to the term: top, bottom, left, or right.
* Customize tooltip width, text color, background color, and border color.
* Control tooltip behavior on mobile devices — default hover, or tap-to-show — and optionally disable tooltips entirely below a chosen screen width.
* Tooltips are keyboard-accessible (shown on focus, not just mouse hover).

**Glossary index page**

* Display a complete, alphabetically organized (A–Z) glossary index using the `[glossary_list]` shortcode or by selecting a glossary index page in the settings.
* Optional A–Z alphabetical jump navigation at the top of the index.
* Optional live search box to filter glossary items on the index page.
* Customize the font size and color (including hover color) of the A–Z letter navigation, and the font size of index items.
* Option to disable tooltips specifically on the glossary index page.

**Glossary terms**

* Add a customizable text label before the term title on single glossary term pages.
* Optional "back to glossary index" link at the bottom of each term page, with customizable link text.
* Optionally add a `title` attribute to glossary links so the term name shows as a native browser tooltip.
* Optionally open glossary links in a new tab, with a customizable `rel` attribute (for example `noopener noreferrer`).
* Customize the glossary link color, hover color, and underline behavior (always, on hover, or none), including underline style, width, and color.

**Organization**

* Group glossary terms using a dedicated "Glossary Category" taxonomy.
* Manage terms from a familiar WordPress edit screen (title, content editor, categories).
* Customizable permalink slug for glossary term pages and for the glossary category taxonomy.

**Settings, backup, and maintenance**

* Clean, tabbed settings screen (General, Glossary Index Page, Glossary Terms, Tooltip, Advanced).
* Export all plugin settings to a JSON file, import a previously exported JSON file, or reset all settings to their defaults.
* One-click "Flush Rewrite Rules" tool to fix 404 errors after changing the glossary permalink slug.
* One-click "Clear Glossary Cache" tool to force an immediate refresh of cached terms, synonyms, and categories.
* A System Information panel that summarizes your site, server, and plugin configuration, with a one-click copy button — handy when requesting support.

**Performance**

* Optional content caching for glossary parsing.
* Option to load the plugin's JavaScript in the footer.
* Option to load CSS and JavaScript inline instead of as separate files.
* Option to limit parsing to the main WordPress query only, avoiding widgets, related-post blocks, and secondary queries.

= Shortcodes =

This plugin includes two shortcodes: `[glossary_list]` to display your glossary index, and `[glossary_exclude]` to turn off glossary highlighting on one specific post or page.

**`[glossary_list]`**

Add this shortcode to any post or page to display your full glossary index there — an alphabetically organized (A-Z) list of all your glossary terms, with optional jump navigation and a live search box.

Basic example, showing every glossary term with the default settings:

`[glossary_list]`

(The older `[glossary-list]` tag, with a hyphen instead of an underscore, still works too — it's kept for backward compatibility with sites set up before version 2.4.1, but `[glossary_list]` is the current, recommended tag.)

*Supported attributes*

* `category="all"` — Only show terms assigned to one or more Glossary Categories. Use a single category slug (e.g. `category="seo"`), or several separated by commas to show terms matching *any* of them (e.g. `category="seo,wordpress"`). Defaults to `all`, which shows every term regardless of category.
* `orderby="name"` — Chooses how terms are sorted *within* each A-Z letter group. A term never moves out of its own letter group — only the order of terms inside each group, and the order the groups themselves appear in, follow `orderby`/`order` together. Accepted values: `name` (alphabetical), `date` (publish date), `menu_order` (the custom order set on the Glossary Terms screen), or `rand` (random order, reshuffled on every page load — group order is unaffected by `order` in this case). Defaults to `name`.
* `order="ASC"` — Sets the sort direction used by `orderby`, and also the direction the A-Z letter groups themselves run in. Accepted values: `ASC` (ascending — groups run A to Z, terms sort oldest to newest for `orderby="date"`) or `DESC` (descending — groups run Z to A, terms sort newest to oldest for `orderby="date"`). Defaults to `ASC`. Has no effect on term order when `orderby="rand"`, and no effect on group order at all when `orderby="rand"`.
* `letters="show"` — Shows or hides the big A-Z letter heading above each group of terms. Accepted values: `show` or `hide`. Defaults to `show`.
* `limit="-1"` — The maximum number of terms to display *per A-Z letter group* — not a total for the whole index. For example, `limit="2"` shows at most 2 terms under A, at most 2 under B, at most 2 under C, and so on. Use `-1` for no limit, showing every matching term. Defaults to `-1`.
* `columns="2"` — How many columns to arrange the terms into within each letter group. Accepts a whole number from `1` to `6`. Defaults to `2`.

*More examples*

Show only terms from the "SEO" category:

`[glossary_list category="seo"]`

Show terms from either the "SEO" or "WordPress" category:

`[glossary_list category="seo,wordpress"]`

Sort terms newest-first, with the letter groups themselves running Z to A:

`[glossary_list orderby="date" order="DESC"]`

Reverse just the A-Z letter groups to run Z to A while keeping terms inside each group alphabetical:

`[glossary_list order="DESC"]`

Show the terms in a random order each time the page loads:

`[glossary_list orderby="rand"]`

Hide the A-Z letter headings and lay terms out in a single column:

`[glossary_list letters="hide" columns="1"]`

Show at most 3 terms per letter, arranged in 4 columns:

`[glossary_list limit="3" columns="4"]`

Combine several attributes together — show only "Web Development" terms, newest first, up to 5 per letter, in 3 columns:

`[glossary_list category="web-development" orderby="date" order="DESC" limit="5" columns="3"]`

**`[glossary_exclude]`**

Add this shortcode anywhere in a specific post or page to turn off automatic glossary term highlighting for that content only — the rest of your site keeps highlighting as normal. It doesn't display anything itself; the marker is simply removed from the page when it renders.

Example — placed at the very top of a post's content to disable highlighting for that entire post:

`[glossary_exclude]`

This is useful for pages where you don't want glossary tooltips to appear, such as a legal page, a code tutorial, or a post that already discusses a term in detail. It has the same effect as setting the "Glossary Highlight" option to Off on that post/page's edit screen.

= Multilingual sites =

Glossary Tooltip stores UTF-8 content and is compatible with multilingual plugins such as WPML and Polylang.

= Documentation and support =

Full documentation and setup guides are available at [glossarytooltip.com](https://www.glossarytooltip.com/). For questions or issues, please use the [support forum](https://wordpress.org/support/plugin/glossary-tooltip/).

== Installation ==

= Automatic installation =

1. In your WordPress admin, go to **Plugins → Add New Plugin**.
2. Search for **Glossary Tooltip**.
3. Click **Install Now**, then click **Activate**.
4. Go to **Glossary → Settings** to configure the plugin.

= Manual installation =

1. Download the plugin ZIP file.
2. In your WordPress admin, go to **Plugins → Add New Plugin → Upload Plugin**.
3. Choose the downloaded ZIP file and click **Install Now**.
4. Activate the plugin from the **Plugins** screen.

= After activation =

1. Go to **Glossary → Add New Glossary Term**.
2. Enter the term as the title and its definition in the content editor.
3. Publish the term.
4. Visit any post or page containing that word to see it automatically highlighted with a tooltip.
5. Optionally, create a page with the `[glossary_list]` shortcode (or select a glossary index page in **Glossary → Settings**) to display a full glossary index.

== Frequently Asked Questions ==

= Do I need to manually link glossary terms in my content? =

No. Once a glossary term is published, the plugin automatically detects and highlights matching words across the post types you've selected in the settings.

= How do I show a full list of glossary terms on a page? =

Use the `[glossary_list]` shortcode on any post or page, or select a glossary index page in **Glossary → Settings → Glossary Index Page**. The index lists terms alphabetically and includes an optional A–Z navigation and live search box.

= Can I stop a term from being highlighted on one specific page? =

Yes. Add the `[glossary_exclude]` shortcode to that post or page, or set the "Glossary Highlight" option to Off on the post/page edit screen, and glossary highlighting will be skipped for that content.

= Can I control tooltips for just one post or page? =

Yes. Each post/page edit screen includes a "Tooltip" setting with three options: Default (follows the site-wide tooltip setting), On, or Off. This lets you enable or disable tooltips for a single post or page without changing the global setting.

= Can I stop one specific glossary term from being highlighted everywhere? =

Yes. Each glossary term has per-term visibility controls that let you exclude it from auto-highlighting and/or the glossary index, without affecting any other terms.

= Can I control how many times a term is highlighted on the same page? =

Yes. In **Glossary → Settings → General**, you can highlight a term only once, a limited number of times, every Nth occurrence, or every occurrence.

= Can a term have alternate names or abbreviations? =

Yes. You can add synonyms/aliases to a glossary term, and any of those alternate forms will be highlighted and link to the same term.

= Will highlighting break my headings or existing links? =

No, by default the plugin ignores headings (H1–H6) and text that is already inside a link, so your existing structure and links are not altered. These behaviors can be adjusted in the settings.

= Does this affect my site's internal search results? =

You can optionally exclude glossary terms from your site's internal search results in **Glossary → Settings → General**. This does not affect Google or other external search engines.

= Can I choose which side of the term the tooltip appears on? =

Yes. In **Glossary → Settings → Tooltip**, the "Tooltip position" option lets you choose top, bottom, left, or right. Top is recommended for most layouts.

= I changed the glossary permalink slug and now get 404 errors. How do I fix this? =

Go to **Glossary → Settings → Advanced** and click **Flush Rewrite Rules**, or go to **Settings → Permalinks** and click **Save Changes**.

= I updated a term but the site still shows the old content. What should I do? =

If you have content caching enabled, use the **Clear Glossary Cache** tool on the Advanced settings tab, then clear any third-party caching or CDN cache your site may be using.

= Can I back up or transfer my plugin settings to another site? =

Yes. On the Advanced settings tab you can export all plugin settings as a JSON file and import that file on another installation. You can also reset all settings to their defaults.

= How do I move glossary terms to another WordPress site? =

Glossary terms are a standard WordPress content type, so you can use the built-in **Tools → Export** and **Tools → Import** screens to move them between sites.

= Does the plugin work with multilingual plugins like WPML or Polylang? =

Yes. Glossary Tooltip stores UTF-8 content and is compatible with popular multilingual plugins.

= Does the plugin slow down my site? =

The plugin includes several performance options: it can skip parsing when no glossary terms exist, cache parsed content, load scripts in the footer, load assets inline, and limit parsing to the main query only.

= Where can I get help? =

Visit the [support forum](https://wordpress.org/support/plugin/glossary-tooltip/) or the [documentation site](https://www.glossarytooltip.com/).

== Screenshots ==

1. General settings — choose which post types are highlighted, control repeated-highlighting behavior, and configure content parsing and performance options.
2. Glossary Index Page settings — configure the A–Z navigation, search box, and index page typography.
3. Glossary Terms settings — manage term label, back link, link attributes, and highlight styling.
4. Tooltip settings — customize tooltip position, width, colors, and mobile behavior.
5. Advanced settings — maintenance tools, settings backup/restore, and system information.
6. Front-end glossary index page with alphabetical navigation and live search.
7. A glossary term highlighted in post content with its tooltip definition visible.
8. A single glossary term page showing its full definition.

== Upgrade Notice ==

= 2.4.5 =
`[glossary_list order="DESC"]` now also reverses the order of the A-Z letter groups themselves (Z to A), instead of only reversing the terms inside each group.

= 2.4.4 =
Fixes the `[glossary_list category="..."]` attribute, which previously always returned an empty result. Also restores the deprecated `[glossary-list]` alias, which had stopped working.

= 2.4.3 =
`[glossary_list]`'s `limit` attribute now applies per A-Z letter group instead of as one total across the whole index.

= 2.4.2 =
`[glossary_list]` now accepts `category`, `orderby`, `order`, `letters`, `limit`, and `columns` attributes for filtering, sorting, and laying out the glossary index.

= 2.4.1 =
The glossary index shortcode is now `[glossary_list]` (underscore); the previous `[glossary-list]` tag still works but is deprecated. Per-post "Disable glossary highlighting" checkbox replaced with separate Glossary Highlight and Tooltip dropdown settings (Default/On/Off).

= 2.4.0 =
Adds a Maintenance Tools panel (flush rewrite rules, clear glossary cache), a System Information panel on the Advanced tab, and a new Tooltip Position setting (top, bottom, left, right); performance and content-parsing options moved back to General settings.

== Changelog ==

= 2.4.5 =

* Fixed: The `[glossary_list]` shortcode's `order="DESC"` attribute only reversed the terms inside each A-Z letter group, while the letter groups themselves (A, B, C...) always stayed in ascending order. `order` now also reverses the sequence the letter groups appear in — `order="DESC"` runs the whole index Z to A, matching the `DESC` direction applied within each group. The jump-navigation links at the top of the index reorder to match. `orderby="rand"` is unaffected, since random order has no group sequence to reverse.

= 2.4.4 =

* Fixed: The `[glossary_list]` shortcode's `category` attribute always returned an empty index. The glossary category taxonomy wasn't registered yet at the point the plugin first built its internal glossary terms cache, so every term's category list was silently recorded as empty and cached for 12 hours. The plugin's startup is now correctly deferred until WordPress's `init` hook, after the taxonomy is registered.
* Fixed: The deprecated `[glossary-list]` (hyphenated) alias had stopped being registered and no longer worked; it is now restored alongside the primary `[glossary_list]` tag.

= 2.4.3 =

* Changed: The `[glossary_list]` shortcode's `limit` attribute now caps the number of terms shown *per A-Z letter group*, instead of a single total across the whole index — e.g. `limit="2"` shows up to 2 terms under A, up to 2 under B, up to 2 under C, and so on.

= 2.4.2 =

* New: The `[glossary_list]` shortcode now accepts `category`, `orderby`, `order`, `letters`, `limit`, and `columns` attributes, letting you filter by Glossary Category, sort terms within each A-Z group by name/date/menu order/random, hide the A-Z group letters, cap the number of terms shown, and lay the index out in 1 to 6 columns.
* Fixed: `orderby`/`order` now sort the terms *inside* each A-Z letter group only — the letter groups themselves always stay in fixed alphabetical order, so the index navigation and layout remain predictable no matter which sort is applied.

= 2.4.1 =

* Changed: The glossary index shortcode is now `[glossary_list]` (underscore) again. The hyphenated `[glossary-list]` tag introduced in 2.4.0 continues to work unchanged, but is now the deprecated alias.
* Changed: The per-post "Disable glossary highlighting on this post" checkbox has been replaced with two independent dropdown settings on the post/page edit screen: "Glossary Highlight" and "Tooltip", each offering Default (follows the current global setting), On, or Off.

= 2.4.0 =

* New: "Tooltip position" setting on the Tooltip tab, letting you choose whether the tooltip appears above, below, to the left, or to the right of a highlighted term.
* Changed: The glossary index shortcode is now `[glossary-list]` (hyphenated). The original `[glossary_list]` tag continues to work unchanged for backward compatibility.
* New: "Maintenance Tools" card on the Advanced tab with one-click "Flush Rewrite Rules" (fixes 404s after permalink/slug changes) and "Clear Glossary Cache" (forces immediate re-read of terms, synonyms, and categories) actions.
* New: System Information panel on the Advanced tab summarizing site, server, and plugin details, with a one-click copy-to-clipboard button.
* Changed: The Advanced tab's Import/Export section is now scoped to plugin settings only (export/import/reset as JSON). Glossary term export and CSV/JSON import were removed — glossary terms are a standard WordPress custom post type, so the tab now points to the built-in Tools → Export / Tools → Import screens instead.
* Improved: "Only highlight on main WP query", "Enable content caching", "Load scripts in footer", and "Load CSS & JS inline" moved from Advanced back to General settings, under a new "Performance & Asset Loading" section.
* Improved: Settings screen visual design refined — tab navigation, cards, buttons, and form controls given a more consistent, modern appearance.

= 2.3.0 =

* New: Import & Export section on the Advanced tab, with plugin settings export/import/reset, glossary data export (CSV/JSON), and a 3-step import/migration wizard.
* New: All import/export/reset actions run over AJAX with nonce verification and a `manage_options` capability check.

= 2.2.1 =

* Improved: Settings layout now uses the full available width with a proportional main/sidebar split; tab navigation redesigned into a segmented pill style.
* Improved: Content-parsing options ("Skip parsing when no terms exist", "Ignore headings", "Ignore links", "Exclude specific HTML tags from parsing", "Content parsing priority") moved from Advanced back to General settings, under a new "Content Parsing" section.
* Improved: Renamed the "Index Page" and "Terms" tabs to "Glossary Index Page" and "Glossary Terms" for clarity.

= 2.2.0 =

* New: Redesigned settings screen with a branded header, version badge, quick action links, and a two-column layout with a persistent sidebar for the installation guide and support links.
* New: "Advanced" settings tab groups parsing-performance and asset-loading options.
* New: "Highlight only space-separated terms" option to prevent matching inside compound words.
* New: "Load scripts in footer" option for faster perceived load times.

= 2.1.1 =

* Fixed: Deactivating the plugin no longer deletes your glossary settings.
* Fixed: "Disable tooltips on the glossary index" setting now works correctly.
* Fixed: Glossary highlighting no longer skips a page just because its slug happens to be "glossary".
* Fixed: A closure/filter mismatch that could force all outgoing emails to HTML formatting after using the deactivation feedback form.
* Security: Added nonce verification to the deactivation feedback form.
* Security: Added a capability check when saving the "disable highlight" post setting.
* Accessibility: Tooltips are now visible on keyboard focus, not just mouse hover.
* New: Synonyms/aliases for glossary terms.
* New: Per-term visibility controls (exclude a term from auto-highlighting and/or the glossary index).
* Improved: Replaced deprecated `get_post_custom()` calls with targeted `get_post_meta()` calls.
* Improved: Corrected the plugin's declared minimum PHP version to match the code.
* Improved: Added missing translator strings in the deactivation feedback modal.
* Improved: Synonym/alias matching now treats a term and its synonyms as one keyword group and always prefers the longest matching keyword, preventing overlapping links.

= 2.0.1 =

* Improved tooltip behavior.
* Performance improvements.
* Minor fixes.

= 2.0.0 =

* Added advanced glossary settings.
* Added glossary index improvements.
* Added tooltip customization options.
* Added live search on the glossary index.
* Improved parsing performance.

= 1.0.1 =

* Settings improvements.

= 1.0 =

* Initial release.
