Clever Linked Terms — User Manual

Clever Linked Terms

Complete User Manual — glossary terms, semantic relationships, WordPress linking, FluentCommunity support, analytics, import/export, and term discovery.

Version 1.0.10

1. Getting Started

Clever Linked Terms is a WordPress glossary and semantic linking plugin. It automatically finds defined terms in your content, links them to glossary pages, and shows helpful hover tooltips. It also includes optional support for FluentCommunity, including SPA-aware reprocessing so terms can continue working after portal navigation.

1.1 Requirements

WordPress 6.0 or higher
PHP 8.1 or higher
A theme or builder that outputs normal frontend content containers
FluentCommunity is optional, but required for the FluentCommunity add-on
Administrator access is required to configure settings, import/export terms, and view analytics reports

Good news: Clever Linked Terms v1.0.10 is free. The plugin uses add-on toggles to keep optional features organized, but there is no separate license system.

1.2 Installation

Method A: Install from WordPress.org

Go to Plugins → Add New Plugin.
Search for Clever Linked Terms.
Click Install Now, then Activate.

Method B: Upload ZIP

Go to Plugins → Add New Plugin → Upload Plugin.
Upload clever-linked-terms.zip.
Click Install Now, then Activate Plugin.

Method C: FTP/SFTP Upload

Unzip the plugin on your computer.
Upload the clever-linked-terms folder to /wp-content/plugins/.
Activate Clever Linked Terms from the WordPress Plugins screen.

1.3 First Steps After Activation

Go to Linked Terms → Add New.
Create your first glossary term. The title is the phrase the plugin will look for in content.
Add the definition in the editor body. This content is used for the term page and tooltip excerpt.
Go to Linked Terms → Settings and review the General and WordPress Content tabs.
If using FluentCommunity, enable the FluentCommunity add-on from the Add-Ons tab and configure its content areas.
Create the Glossary Index page from the General tab if you want a public A-Z directory.

Note: If you change the glossary slug, go to Settings → Permalinks and click Save Changes. That flushes rewrite rules so term URLs resolve correctly.

2. Core Concepts

2.1 What the Plugin Does

Clever Linked Terms creates a glossary content type and then scans selected frontend content areas for matching terms. When a match is found, the plugin can wrap the phrase in a glossary link and attach tooltip data for quick context.

Glossary Terms

Each term is a custom post type entry with a title, definition, permalink, and optional relationships.

Automatic Linking

The frontend linker finds terms inside selected content containers and turns them into helpful links.

Tooltips

Visitors can hover a linked term to read a short definition without leaving the page.

Relationships

Synonyms, aliases, abbreviations, and variations can point back to the canonical glossary term.

2.2 Where Terms Appear

WordPress content: Posts, pages, and selected public custom post types.
FluentCommunity: Feed and space content, with optional comment support.
Glossary index: Public A-Z term listing created with the built-in index page tool or shortcode.
Term pages: Individual public glossary entries, usually under your configured glossary slug.

2.3 Free Add-Ons

The Add-Ons tab organizes optional modules. These are not paid-license modules in v1.0.10; they are feature toggles that keep heavier or context-specific features disabled unless needed.

Add-On	Default	Description
FluentCommunity	Off	Enables term linking inside FluentCommunity portal content.
Analytics	Off	Tracks impressions, clicks, relationship type, matched text, context, user/post/space metadata, and reporting data.
Import/Export	Off	Adds tools for importing and exporting glossary data.
Term Discovery	Off	Adds definition, synonym, antonym, and encyclopedia lookup tools to term editing.
Multilingual	Coming soon	Placeholder for future translated term support.

3. Creating and Managing Terms

3.1 Add a Glossary Term

Go to Linked Terms → Add New.
Enter the main term as the title, such as FluentCommunity, shortcode, or canonical URL.
Add the definition or explanation in the main editor.
Publish the term.

Tip: Keep term titles clean and specific. If you need alternate spellings or related phrases, add them as relationships instead of creating duplicate glossary terms.

3.2 Term Pages

Each published glossary term has its own public page. The term page can contain the full definition, examples, screenshots, links, or any regular WordPress editor content. Relationship groups are appended to the term page when relationship values exist.

3.3 Per-Term Exclusions

Each term includes exclusion controls so the term can exist in the glossary without being automatically linked in every context.

Option	Default	Description
Exclude from WordPress	Off	Prevents this term from being automatically linked in regular WordPress content.
Exclude from FluentCommunity	Off	Prevents this term from being automatically linked in FluentCommunity content.

Note: Excluding a term from linking does not delete the term page. It only prevents automatic linking in the selected integration.

4. General Settings

General settings control the global glossary behavior, link behavior, and glossary page tools. Find them at Linked Terms → Settings → General.

4.1 Linking Behavior

Setting	Default	Description
Enable Glossary	On	Global master toggle for frontend glossary processing.
Link Behavior	Limit Links Per Term	Choose whether to link all occurrences or limit links per term on each page.
Max Links Per Term	3	When link behavior is limited, this controls how many times each term can link per page.
Enable Term Links	On	When enabled, matched terms link to their glossary pages.
No-Link Term Color	#2271b1	Text color used when term links are disabled but terms are still visually marked.

Recommended: Use Limit Links Per Term with a small number such as 1–3. Linking every occurrence can feel heavy on long posts.

4.2 Glossary Pages

Setting	Default	Description
Glossary Slug	glossary	Controls the base URL for individual term pages, such as `/glossary/my-term/`.
Create Index Page	Manual action	Creates a public A-Z glossary index page containing the index shortcode.
View Index Page	Shown if created	Opens the public glossary index page.
Edit Page	Shown if created	Opens the WordPress editor for the glossary index page.
Delete Index Page	Shown if created	Deletes the generated index page if you no longer want it.

[clevlite_linked_terms_index]

You can also manually place the shortcode above on any page where you want the A-Z index to appear.

4.3 Saving Settings

The settings screen uses tabs, but all settings are saved through the page form. Click Save Changes after editing any tab.

5. Semantic Relationships Free

Relationships let alternate words and phrases link back to one canonical glossary term. This is what moves the plugin beyond a simple glossary and toward a semantic linking system.

5.1 Relationship Types

Type	Use For	Example
Synonyms	Words with a similar meaning that should use the same definition.	`community` → group, network
Variations	Plural, singular, spelling, punctuation, or formatting variations.	`plugin` → plugins, plug-in
Abbreviations	Short forms, acronyms, or initialisms.	`Search Engine Optimization` → SEO
Aliases	Alternate labels, older names, common references, or branded shorthand.	`FluentCommunity` → FCom

Relationship fields accept comma-separated values or one value per line. Values are normalized and stored as clean arrays behind the scenes.

5.2 Matching Priority

When two terms or relationship phrases overlap, Clever Linked Terms uses priority-aware matching.

Primary term titles win first.
Abbreviations are checked next.
Synonyms follow abbreviations.
Aliases follow synonyms.
Variations are checked after stronger relationship types.

Why this matters: If a phrase appears in more than one place, the plugin needs a predictable rule so links do not jump to the wrong canonical term.

5.3 Conflict Warnings

The relationship editor and the Linked Terms admin list can show possible conflicts when the same alternate phrase appears on another term. This does not always mean something is broken, but it is a sign to review which canonical term should own that phrase.

Conflicts appear in the relationship meta box when editing a term.
The admin list shows relationship counts, linking badges, and conflict summaries.
Relationship chips appear on glossary index cards when relationship values exist.
Relationship groups also appear on individual term pages.

6. WordPress Content Integration

The WordPress Content tab controls linking inside normal WordPress frontend content.

6.1 Post Types

Setting	Default	Description
Enable WordPress Content	On	Enables term linking in regular WordPress content.
Select Post Types	Posts, Pages	Choose which public post types should be processed. Glossary terms and attachments are excluded.

6.2 Content Selector

The advanced content selector tells the frontend script where it should look for terms.

.entry-content, .post-content, .article-content

Advanced setting: Only change the selector if your theme or builder uses unusual markup. A bad selector can make linking appear broken even when the plugin is working.

6.3 Exclude Pages or Posts

The Exclusions section lets you search for individual posts/pages and exclude them from automatic linking. This is useful for sales pages, legal pages, landing pages, or content where automatic links would be distracting.

7. FluentCommunity Integration Optional

Clever Linked Terms includes a dedicated FluentCommunity integration for communities that use a Vue/SPA-style portal. This integration is intentionally separate from normal WordPress content processing because FluentCommunity does not always behave like a traditional WordPress theme page.

7.1 Enabling FluentCommunity

Install and activate FluentCommunity.
Go to Linked Terms → Settings → Add-Ons.
Enable the FluentCommunity add-on.
Go to the FluentCommunity tab to configure content areas and exclusions.

Note: If FluentCommunity is not installed or not active, the add-on card shows a warning and the integration will not run.

7.2 Content Areas

Area	Default	Description
Feed	On	Processes regular feed post content.
Space	On	Processes post content inside spaces.
Comments	Off	Processes comment bodies when feed or space content is also enabled.
Advanced Selector	`.feed_texts.feed_md_content`	Allows custom FCom selectors for advanced layouts.

7.3 SPA Behavior

FluentCommunity uses client-side navigation. That means new content can appear without a full page reload. Clever Linked Terms handles this by outputting portal-specific assets through FluentCommunity portal hooks and reprocessing content after navigation or feed updates.

Scripts/styles for the portal are printed through FluentCommunity-specific hooks.
Term processing is designed to re-run after SPA navigation.
Analytics is isolated to the FluentCommunity portal path so events report with the fluentcommunity context.

Testing tip: After installing an update, test a full page load, then click around inside the community without refreshing. Terms should continue linking after navigation.

7.4 New Tab Links

In FluentCommunity, glossary links open in a new browser tab. This preserves the community portal state and avoids pulling users out of the SPA experience. Normal WordPress post/page links still open in the same tab.

Context	Behavior	Why
WordPress posts/pages	Same tab	Standard website navigation behavior.
FluentCommunity portal	New tab	Keeps the community route open while showing the glossary page separately.

8. Styling

The Styling tab controls tooltip appearance and glossary index colors.

8.1 Tooltip Colors

Setting	Default	Description
Light Mode Background	#1f2937	Tooltip background for regular/light contexts.
Light Mode Text	#ffffff	Tooltip text color for regular/light contexts.
Light Mode Border	#ffffff	Tooltip border color when border is enabled.
Dark Mode Background	#1f2937	Tooltip background for FluentCommunity dark mode contexts.
Dark Mode Text	#ffffff	Tooltip text color for dark mode contexts.
Dark Mode Border	#ffffff	Tooltip border color for dark mode contexts.

8.2 Borders and Typography

Setting	Default	Description
Enable Border	Off	Adds a border around tooltip boxes.
Border Width	1	Width in pixels. Allowed range is clamped by the plugin.
Border Style	solid	CSS border style such as solid, dashed, or dotted.
Font Size	14	Tooltip font size.
Font Weight	400	Tooltip font weight.

8.3 Glossary Index Styling

The index styling controls affect the generated A-Z glossary page.

Setting	Default	Description
Accent Color	#2563eb	Primary accent used on index UI elements.
Navigation Background	#ffffff	Background color for the A-Z navigation bar.
Navigation Background (Scrolled)	#f9fafb	Navigation background when sticky/scrolled.
Term Card Background	#f9fafb	Background for individual term cards.
Term Card Border	#e5e7eb	Border color around term cards.
Active Letter Background/Text	#f3f4f6 / #6b7280	Colors for active letter navigation.
Inactive Letter Background/Text	#f3f4f6 / #d1d5db	Colors for disabled or unavailable letters.

9. Add-Ons

9.1 Add-On Overview

The Add-Ons tab lets you keep optional feature areas turned off until you need them. This keeps the admin simpler and avoids loading tools that are irrelevant to your site.

Add-On	Status	What It Adds
FluentCommunity	Optional	Portal term linking, SPA-aware processing, FCom-specific analytics context, and new-tab glossary links.
Analytics	Optional	Click/impression tracking, relationship reports, context reports, top users/spaces, and CSV export.
Import/Export	Optional	Bulk import/export tools for glossary terms and relationship metadata.
Term Discovery	Optional	External lookup tools for definitions, synonyms, antonyms, and encyclopedia summaries.
Multilingual	Planned	Future translated term support.

9.2 Enabling Add-Ons

Go to Linked Terms → Settings → Add-Ons.
Turn on the add-on you want.
Click Save Changes.
Use the newly available menu page or settings tab for that feature.

Note: Some add-ons reveal additional settings or menu pages only after saving.

10. Analytics Add-On

The Analytics add-on tracks glossary impressions and clicks so you can understand which terms are being seen, clicked, and engaged with in both WordPress and FluentCommunity contexts.

10.1 What Analytics Tracks

Data	Example	Description
Event Type	impression, click	Whether a term was viewed/hovered or clicked.
Term ID	123	The canonical glossary term attached to the event.
Matched Text	FCom	The exact word or phrase matched on the page.
Relationship	alias	Whether the match was primary, synonym, variation, abbreviation, or alias.
Context	wordpress, fluentcommunity	Where the event happened.
Post/Page	Post title or ID	The WordPress content object related to the event, when available.
Space	Space title or ID	The FluentCommunity space related to the event, when available.
User	User ID or anonymous	User association depending on anonymization settings.

10.2 Analytics Reports

Top Performing Terms: Terms ranked by impressions, clicks, and click-through rate.
Recent Events: Timeline of recent impressions and clicks.
Activity Over Time: Charted activity trend.
Activity by Relationship Type: Performance of primary terms versus synonyms, aliases, abbreviations, and variations.
Top Matched Words & Phrases: Shows which alternate phrases are actually being triggered.
Activity by Context: WordPress versus FluentCommunity breakdown.
Top Spaces: FluentCommunity space performance when available.
Top Users: User-level activity when anonymization allows it.

10.3 Analytics Settings

Setting	Default	Description
Anonymize Data	On	Stores analytics without tying events to individual users.
Auto-Cleanup	Off	Automatically deletes older analytics records.
Cleanup Schedule	30 days	When cleanup is enabled, records older than this number of days are removed.

Testing tip: If WordPress analytics works but FluentCommunity does not, confirm the FluentCommunity add-on is enabled and test after navigating inside the portal without a full page reload.

11. Import & Export Add-On

The Import/Export add-on helps you move glossary data into or out of Clever Linked Terms. It is especially useful when starting with an existing glossary list or migrating from another site.

11.1 Importing Terms

Enable Import/Export from the Add-Ons tab.
Go to Linked Terms → Import/Export.
Choose your import file.
Run the import and review the created terms afterward.

CSV-style imports should include term names and definitions. Current relationship fields can also be carried through export/import workflows when included in supported format columns.

11.2 Exporting Terms

Export tools are useful for backup, migration, spreadsheet review, or manual cleanup. Exported analytics data can include relationship, canonical term, and matched text metadata when analytics is enabled.

Export Use	Description
Backup	Keep a copy of your glossary before major edits.
Migration	Move terms from staging to production or between sites.
Review	Inspect terms, relationships, and definitions in a spreadsheet.
Analytics	Export click/impression data for reporting or long-term storage.

12. Term Discovery Add-On

Term Discovery adds helper tools to the term editor. It can fetch definitions, synonyms, antonyms, and encyclopedia summaries from optional external services. Always review generated content before publishing.

12.1 API Sources

Source	Requires Key?	Used For
Wikimedia / Wikipedia REST API	No	Encyclopedia summaries.
Merriam-Webster Dictionary API	Yes	Dictionary definitions.
Merriam-Webster Thesaurus API	Yes	Synonyms, antonyms, and related terms.
Encyclopaedia Britannica API	Yes	Encyclopedic articles and summaries.
Free Dictionary API	No	Fallback dictionary definitions and pronunciation data.
API Ninjas Thesaurus API	Yes	Synonyms and antonyms.
WordsAPI through RapidAPI	Yes	Definitions, synonyms, pronunciation, and related word data.

12.2 Using Term Discovery

Enable Term Discovery from Settings → Add-Ons.
Configure any desired API keys in the Term Discovery settings tab.
Open or create a glossary term.
Use the Term Discovery meta box to fetch a definition, synonyms/antonyms, encyclopedia summary, or all available data.
Review and edit the inserted content before publishing.

Content review required: External lookup data may be incomplete, overly generic, or contextually wrong for your community. Treat it as a starting point, not a final editorial answer.

13. Glossary Index

13.1 Creating the Index

The glossary index is an A-Z public page that lists published glossary terms. You can create it automatically from the General tab or manually by placing the shortcode on any page.

[clevlite_linked_terms_index]

Letters with available terms act as navigation.
Term cards link to individual glossary pages.
Styling is controlled from the Styling tab.

13.2 Relationship Chips

When a glossary term has synonyms, aliases, abbreviations, or variations, the index can show those values as relationship chips on the term card. This helps users understand that multiple phrases point to the same canonical entry.

14. Privacy & External Services

Clever Linked Terms can run without external lookup services. External services are only used when Term Discovery is enabled and an administrator performs a lookup or API test.

Feature	Data Involved	Admin Action Required?
Normal term linking	Local glossary terms and page content	No external service call.
Analytics	Local impressions/clicks, context, matched text, optional user ID	Analytics add-on must be enabled.
Term Discovery	The searched term and any configured API key	Admin must initiate lookup or API test.
Documentation/support links	No automatic site/user data sent by the plugin	User/admin clicks link manually.

Privacy note: If analytics is enabled, review whether your privacy policy should mention glossary engagement tracking. If Term Discovery APIs are used, your privacy policy may also need to mention external dictionary/encyclopedia providers.

15. Troubleshooting

Terms Are Not Linking

Confirm Enable Glossary is turned on.
Confirm WordPress Content or FluentCommunity integration is enabled for the place you are testing.
Confirm the term is published.
Check whether the term is excluded from WordPress or FluentCommunity in the term editor.
Review the advanced content selector. If it does not match your theme/community markup, the linker cannot find content.
Clear page cache, object cache, and CDN cache after plugin updates.

FluentCommunity Links Work on Refresh but Not After Navigation

Make sure the FluentCommunity add-on is enabled.
Test inside the actual portal, not only a normal WordPress page.
Enable debug mode temporarily from the Help tab.
Check whether portal scripts are present after SPA navigation.
Clear caches, especially if Redis/Cloudflare/page cache is active.

Analytics Tracks WordPress but Not FluentCommunity

Confirm Analytics and FluentCommunity add-ons are both enabled.
Hover or click a linked term inside FluentCommunity and check for an admin-ajax.php request.
Confirm analytics context appears as fluentcommunity.
Clear cache after updates. FCom portal scripts can be affected by stale assets.

Wrong Term Is Being Linked

Check for duplicate relationship phrases in the term editor or admin list.
Review the matching priority: primary titles, abbreviations, synonyms, aliases, then variations.
Move the phrase to the correct canonical term or remove duplicates.

Term URLs 404 After Changing Slug

Go to Settings → Permalinks and click Save Changes. No permalink format change is required; saving flushes rewrite rules.

16. Release and Update Checklist

Use this checklist after updating Clever Linked Terms on a staging site.

Area	Check
Version	Confirm WordPress shows the expected plugin version.
WordPress linking	Check a normal post/page. Links should open in the same tab.
FluentCommunity linking	Check feed/space content. Links should open in a new tab.
SPA navigation	Navigate inside FCom without refreshing and confirm new content still links.
Relationships	Test synonym, alias, abbreviation, and variation phrases. They should link to the canonical term.
Analytics	Confirm clicks/impressions record in WordPress and FluentCommunity contexts.
Index page	Confirm the A-Z glossary page loads and relationship chips display when available.
Admin list	Confirm relationship counts, linking badges, and conflict warnings are visible.
Cache	Clear site/CDN/object cache after installing an update.

For WordPress.org releases, the Stable tag in readme.txt must match an existing /tags/{version}/ folder in SVN.