WP Manifestindependent plugin directory
manifest / content / kindlinks-glossary

Kindlinks Auto Glossary

A high-performance WordPress plugin for automatic keyword highlighting with Kindle-style tooltips

by Kindlinks · github.com/tad-agentics/kindlinks-glossary · website

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/tad-agentics/kindlinks-glossary/archive/refs/heads/main.zip
Readme github.com/tad-agentics/kindlinks-glossary ↗

Kindlinks Auto Glossary Plugin

A high-performance WordPress plugin that automatically highlights keywords in blog posts and displays Kindle-style tooltips with definitions. Optimized for long-form content (50,000+ words).

Version: 2.1.0
Author: Kindlinks
License: GPL-2.0+

🎯 Features

  • Client-Side Processing: Uses JavaScript TreeWalker API for efficient scanning of large documents
  • Smart Highlighting: Highlights keywords with configurable limits (max 2 occurrences per keyword by default)
  • Beautiful Tooltips: Kindle-style tooltips powered by Tippy.js (bundled locally)
  • REST API: Easy synchronization of glossary terms via REST endpoint
  • Performance Optimized: Handles 50k+ word documents without server overhead
  • Theme Agnostic: Works with any WordPress theme
  • Admin Interface: Full CRUD management for glossary terms
  • Configurable Settings: Customize colors, selectors, and behavior
  • Per-Post Control: Disable glossary on specific posts/pages
  • WordPress Category Filtering: Enable glossary only on specific post categories
  • Import/Export: Backup and transfer your glossary terms (JSON format)
  • Shortcodes: Manually insert glossary terms or lists
  • Analytics: Track which terms are clicked most
  • Rate Limiting: Built-in API protection (60 requests/hour)
  • Keyboard Accessible: Full keyboard navigation support (WCAG 2.1 AA)
  • RTL Support: Right-to-left language support
  • Categories: Organize terms by category
  • Caching: WordPress transients for performance (10 minute cache)
  • Case-Insensitive: Matches "WordPress", "wordpress", "WORDPRESS" automatically

📦 Installation

Method 1: WordPress Admin (Recommended)

  1. Download the plugin as a ZIP file
  2. Go to Plugins > Add New > Upload Plugin
  3. Choose the ZIP file and click Install Now
  4. Click Activate Plugin

Method 2: Manual Installation

  1. Upload the kindlinks-glossary folder to /wp-content/plugins/
  2. Activate the plugin through the Plugins menu in WordPress

The plugin will automatically create a database table for storing glossary terms.

🚀 Quick Start

Step 1: Add Your First Glossary Term

  1. Go to Glossary in WordPress admin sidebar
  2. Click Add New
  3. Fill in:
    • Keyword: The word to highlight (e.g., "WordPress")
    • Definition: Tooltip content (HTML allowed)
    • Read More URL: Optional link for more info
    • Category: For organization (e.g., "technical", "business")
  4. Click Add Term

Step 2: Configure Settings (Optional)

  1. Go to Glossary > Settings
  2. Adjust:
    • Max Occurrences: How many times to highlight each keyword (default: 2)
    • Content Selectors: Where to scan for keywords (default: .entry-content,.breakdance-post-content)
    • Enabled Post Types: Which post types to enable (default: post,page)
    • Enabled Post Categories: Select specific WordPress categories (default: All)
    • Colors: Customize underline, hover, and tooltip colors

Step 3: View Your Post

Visit any post containing your keyword - it will automatically be highlighted with a tooltip!

⚙️ Settings Guide

General Settings

Max Occurrences

  • Default: 2
  • Range: 1-10
  • Controls how many times each keyword is highlighted per page
  • Prevents overwhelming readers with too many tooltips

Content Selectors

  • Default: .entry-content,.breakdance-post-content
  • CSS selectors where glossary should scan for keywords (comma-separated)
  • Common selectors:
    • .entry-content (most themes)
    • .elementor-widget-theme-post-content (Elementor)
    • .et_pb_post_content (Divi)
    • .breakdance-post-content (Breakdance)
    • .post-content (generic)

Enabled Post Types

  • Default: post,page
  • Which post types should have glossary enabled (comma-separated)
  • Examples: post, page, product, portfolio

Enabled Post Categories

  • Default: All Categories (No Filtering)
  • Select which WordPress post categories should have glossary enabled
  • Use Cases:
    • Blog with mixed content: Enable only on "Technology" and "Business" posts
    • Educational site: Enable only on "Tutorials" and "Guides"
    • E-commerce: Enable only on "Product Reviews" and "Buying Guides"
  • How it works:
    • Check "All Categories" = Glossary on all posts (default)
    • Uncheck and select specific categories = Glossary only on those categories
    • If post has multiple categories, it only needs ONE enabled category
    • Note: Only applies to posts (not pages or custom post types)

Appearance Settings

Underline Color

  • Default: #F26C26 (orange)
  • Color of the dotted underline for glossary terms

Hover Background Color

  • Default: #fff3cd (light yellow)
  • Background color when hovering over a term

Tooltip Keyword Color

  • Default: #8B3A3A (dark red)
  • Color of the keyword inside the tooltip

API Settings

API Key

  • Auto-generated 32-character key
  • Used for REST API authentication
  • Click Regenerate to create a new key
  • Endpoint: /wp-json/kindlinks/v1/sync

📝 Per-Post Control

Each post/page has a Glossary Settings meta box in the sidebar:

  • Checkbox: "Disable glossary for this post"
  • When checked, the glossary will not load on that specific post
  • Useful for:
    • Posts where glossary doesn't make sense
    • Landing pages that need clean design
    • Posts with conflicting scripts

Note: Per-post disable takes precedence over category filtering.

🔧 Using Shortcodes

Individual Term Tooltip

Display a tooltip for a specific term:

[glossary keyword="WordPress"]

With custom text:

[glossary keyword="WordPress"]Click here for definition[/glossary]

Parameters:

  • keyword (required): The glossary keyword to display

Glossary List

Display all glossary terms as a formatted list:

[glossary_list]

With options:

[glossary_list category="technical" orderby="keyword" order="ASC" columns="2"]

Parameters:

  • category: Filter by category (e.g., "technical", "business")
  • orderby: Sort by keyword, category, or click_count
  • order: ASC (ascending) or DESC (descending)
  • columns: Number of columns (1-4, responsive)

Examples:

[glossary_list category="technical"]
[glossary_list orderby="click_count" order="DESC"]
[glossary_list columns="3"]

📊 Import/Export

Export Terms

  1. Go to Glossary > Import/Export
  2. Click Export Terms
  3. Downloads a JSON file: glossary-terms-YYYY-MM-DD.json

Import Terms

  1. Go to Glossary > Import/Export
  2. Choose your JSON file
  3. Click Import Terms
  4. Terms will be added/updated (uses keyword as unique identifier)

JSON Format:

[
  {
    "keyword": "WordPress",
    "definition": "A popular content management system",
    "url": "https://wordpress.org",
    "category": "technical"
  },
  {
    "keyword": "SEO",
    "definition": "Search Engine Optimization",
    "url": "",
    "category": "marketing"
  }
]

🔌 REST API

Sync Glossary Terms

Endpoint: POST /wp-json/kindlinks/v1/sync

Authentication: Include API key in header:

X-API-Key: your-api-key-here

Request Body:

{
  "terms": [
    {
      "keyword": "WordPress",
      "definition": "A popular content management system",
      "url": "https://wordpress.org",
      "category": "technical"
    }
  ]
}

Response:

{
  "success": true,
  "inserted": 5,
  "updated": 3,
  "total": 8,
  "message": "Synced 8 terms: 5 inserted, 3 updated."
}

cURL Example:

curl -X POST https://yoursite.com/wp-json/kindlinks/v1/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": [
      {
        "keyword": "API",
        "definition": "Application Programming Interface",
        "url": "https://example.com/api-guide",
        "category": "technical"
      }
    ]
  }'

Delete Terms

Endpoint: DELETE /wp-json/kindlinks/v1/delete

Delete specific keywords:

{
  "keywords": ["WordPress", "SEO"]
}

Delete all terms:

{
  "keywords": []
}

Rate Limiting

  • Limit: 60 requests per hour per IP address
  • Filter: kindlinks_glossary_rate_limit to change limit
  • Returns 429 Too Many Requests if exceeded

🎨 Customization

For Developers

Filter Glossary Terms

// Only show terms from specific category
add_filter('kindlinks_glossary_terms', function($terms) {
    return array_filter($terms, function($term) {
        return isset($term['category']) && $term['category'] === 'advanced';
    });
});

// Conditional loading by page type
add_filter('kindlinks_glossary_terms', function($terms) {
    if (is_page('about')) {
        return []; // No glossary on About page
    }
    return $terms;
});

// Different terms for logged-in users
add_filter('kindlinks_glossary_terms', function($terms) {
    if (!is_user_logged_in()) {
        // Remove advanced terms for guests
        return array_filter($terms, function($term) {
            return $term['category'] !== 'advanced';
        });
    }
    return $terms;
});

Change Max Limit Dynamically

add_filter('kindlinks_glossary_max_limit', function($limit) {
    return is_singular('tutorial') ? 5 : 2;
});

Change Content Selectors

add_filter('kindlinks_glossary_content_selectors', function($selectors) {
    return '.my-custom-content,.article-body';
});

Disable Click Tracking

add_filter('kindlinks_glossary_track_clicks', '__return_false');

Custom Styling

Override CSS in your theme:

/* Change underline style */
.kindlinks-term {
    text-decoration-style: solid !important;
    text-decoration-color: #FF0000 !important;
}

/* Change hover effect */
.kindlinks-term:hover {
    background-color: #FFE4E1 !important;
    border-radius: 3px;
}

/* Customize tooltip */
.tippy-box[data-theme~='kindlinks'] {
    background-color: #2c3e50;
    font-size: 14px;
}

.kindlinks-tooltip-keyword {
    color: #e74c3c !important;
    font-size: 16px;
}

📈 Analytics

View Click Statistics

  1. Go to Glossary > All Terms
  2. Click count displayed in "Clicks" column
  3. Sort by clicks to see most popular terms

Use Case Examples

  • Identify confusing terms: High click count = readers need clarification
  • Content optimization: Add more explanation for frequently clicked terms
  • User engagement: Track which topics interest readers most
  • A/B testing: Compare click rates before/after definition changes

How Click Tracking Works

  • Tracks when users click or hover to show tooltip
  • Uses AJAX for non-blocking tracking
  • Case-insensitive: Clicking "wordpress" tracks "WordPress"
  • sendBeacon API for better performance
  • No personal data collected (just keyword + count)

♿ Accessibility

Keyboard Navigation

  • Tab: Navigate to glossary terms
  • Enter/Space: Show tooltip
  • Escape: Close tooltip
  • All terms have role="button" and aria-label

Screen Readers

  • ARIA labels describe each term
  • Tooltips announced when shown
  • Semantic HTML structure

WCAG 2.1 AA Compliance

  • ✅ Keyboard accessible
  • ✅ Color contrast meets standards
  • ✅ Focus indicators visible
  • ✅ Screen reader compatible

⚡ Performance

Optimizations

  • Client-side processing: No server load for highlighting
  • Lazy loading: Scripts only load if terms exist
  • Transient caching: Database queries cached for 10 minutes
  • TreeWalker API: Efficient DOM traversal
  • Longest-first matching: Prevents incorrect partial matches
  • Local bundling: No CDN dependency (Tippy.js & Popper.js bundled)
  • Category filtering: Glossary not loaded on filtered-out posts

Performance Metrics

  • 50,000+ words: Handles without lag
  • 100+ terms: Processes in < 100ms
  • Initial load: ~45KB (gzipped: ~15KB)
  • No jQuery: Pure vanilla JavaScript

Benchmark Results

On a post with 10,000 words and 50 glossary terms:

  • Highlighting: ~30ms
  • Tooltip initialization: ~20ms
  • Total overhead: ~50ms

🔒 Security

Best Practices Implemented

  • ✅ Nonce verification on all forms
  • ✅ Capability checks (manage_options)
  • ✅ Input sanitization (sanitize_text_field, wp_kses_post)
  • ✅ Output escaping (esc_html, esc_attr, esc_url)
  • ✅ Prepared SQL statements (prevents SQL injection)
  • ✅ CSRF protection
  • ✅ API rate limiting (60 req/hour)
  • ✅ Optional API key authentication

API Security

For Production: Enable API key authentication by ensuring check_permission method in includes/class-api.php validates the API key.

Current setting allows public access. To restrict:

  1. Open includes/class-api.php
  2. Find check_permission() method
  3. Uncomment the API key validation code
  4. Save and regenerate your API key in Settings

🌍 Translation & i18n

Text Domain

kindlinks-glossary

Translation Files Location

/languages/ directory

Create Translations

  1. Use Poedit or similar tool
  2. Create .po file for your language (e.g., kindlinks-glossary-es_ES.po)
  3. Translate strings
  4. Generate .mo file
  5. Upload to /wp-content/plugins/kindlinks-glossary/languages/

Available for Translation

All admin interface text, error messages, and user-facing strings are translatable.

🐛 Troubleshooting

Glossary Not Showing

Check:

  1. ✅ Post type is enabled (Settings > Enabled Post Types)
  2. ✅ Post category is enabled (Settings > Enabled Post Categories)
  3. ✅ "Disable glossary" is NOT checked on the post
  4. ✅ Glossary terms exist in database (Glossary > All Terms)
  5. ✅ Content selector matches your theme (Settings > Content Selectors)
  6. ✅ JavaScript is not blocked by ad blockers
  7. ✅ No JavaScript errors in browser console (F12)

Tooltips Not Appearing

Check:

  1. ✅ Tippy.js loaded successfully (check browser console)
  2. ✅ No theme conflicts (try default WordPress theme)
  3. ✅ Terms are being highlighted (look for kindlinks-term class)
  4. ✅ No CSS conflicts hiding tooltips
  5. ✅ Browser supports modern JavaScript (ES6+)

Keywords Not Matching

Note: Matching is case-insensitive!

  • "WordPress" matches "wordpress", "WORDPRESS", "WordPress"
  • Uses whole-word matching with word boundaries
  • Won't match partial words (e.g., "press" won't match "WordPress")

Category Filtering Not Working

Remember:

  1. Category filtering ONLY applies to posts (not pages)
  2. Post must have at least ONE enabled category
  3. Check "All Categories" overrides specific selections
  4. Per-post "Disable glossary" checkbox takes precedence

Performance Issues

Solutions:

  1. Reduce max occurrences (Settings > Max Occurrences)
  2. Reduce number of terms in database
  3. Use more specific content selectors
  4. Enable caching plugin
  5. Check for JavaScript conflicts with other plugins

Import Fails

Common Issues:

  1. Invalid JSON format (use JSON validator)
  2. Missing required fields (keyword, definition)
  3. File too large (try splitting into smaller files)
  4. PHP upload limits (increase upload_max_filesize in php.ini)

🔄 Uninstallation

Clean Uninstall

  1. Deactivate the plugin
  2. Delete the plugin files

What gets removed:

  • ✅ Database table wp_kindlinks_glossary
  • ✅ All plugin options from wp_options
  • ✅ All post meta data
  • ✅ All transient caches

What stays:

  • Your WordPress installation (unaffected)
  • Other plugins and themes (unaffected)

Export Before Uninstalling

To save your glossary terms:

  1. Go to Glossary > Import/Export
  2. Click Export Terms
  3. Save the JSON file
  4. Re-import after reinstalling if needed

📋 Requirements

  • WordPress: 5.0 or higher
  • PHP: 7.4 or higher
  • MySQL: 5.6 or higher
  • Browser: Modern browser with JavaScript enabled (ES6+ support)

Recommended

  • WordPress 6.0+
  • PHP 8.0+
  • HTTPS enabled
  • WordPress caching plugin

🆘 Support

Documentation

  • This README file contains complete documentation
  • All features are documented above

Reporting Bugs

  1. Check troubleshooting section first
  2. Disable other plugins to test for conflicts
  3. Try default WordPress theme
  4. Check browser console for JavaScript errors
  5. Provide: WordPress version, PHP version, theme name, error message

Feature Requests

Submit feature requests with detailed use cases.

📜 Changelog

[2.1.0] - 2025-12-14

Added:

  • WordPress post category filtering
  • "Enabled Post Categories" setting in admin
  • Category-based conditional loading
  • Case-insensitive click tracking fix

Changed:

  • Version bumped from 2.0.0 to 2.1.0
  • Enhanced frontend logic with category checks
  • Improved analytics tracking accuracy

Technical:

  • Added kindlinks_glossary_enabled_categories option
  • Enhanced class-frontend.php with category filtering
  • Added data-keyword attribute for accurate click tracking

[2.0.0] - 2025-12-14

Changed:

  • Complete rebrand from TueSan to Kindlinks
  • All 452 references updated
  • Main file renamed to kindlinks-glossary.php
  • Database table renamed to wp_kindlinks_glossary
  • REST API endpoints: /kindlinks/v1/

[1.5.0] - 2025-12-14

Added:

  • Admin interface (CRUD for terms)
  • Import/Export functionality
  • Category organization for terms
  • Click tracking analytics
  • Accessibility features (keyboard navigation)
  • Shortcodes support
  • Dynamic color customization
  • Per-post disable option
  • Local bundling of Tippy.js & Popper.js (SPOF fix)

Fixed:

  • JavaScript regex bug for multiple matches
  • CDN dependency eliminated

[1.0.0] - Initial Release

Features:

  • Basic keyword highlighting
  • Tooltip display
  • REST API
  • Database storage

📄 License

GPL-2.0+

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

🙏 Credits

Made with ❤️ by Kindlinks
Version 2.1.0 | December 14, 2025