LinkMesh Documentation: Complete Guide to AI-Powered Internal Linking

Quick Start

Get LinkMesh up and running on your WordPress site in under 5 minutes. Follow these three steps to start building smarter internal links.

Installation

1. Download the plugin ZIP file from your LinkMesh account or from the WordPress Plugin Directory.
2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Choose the ZIP file and click Install Now.
4. Click Activate Plugin.

Activation & License

After activation, navigate to LinkMesh → Bulk Settings in your WordPress admin sidebar. Enter your license key in the License field and click Save & Activate.

• Free Trial: Get one by filling out the form in the pricing section. Enter your domain and email. You will receive an email with all the details.
• Paid Plans: Enter the license key from your purchase confirmation email.
• LTD (Lifetime): Same as paid — enter your key once, never renew.

Site Indexing & Sync

Before LinkMesh can suggest and manage links, it needs to understand your content and know about any existing internal links you already have. Go to LinkMesh → Bulk Settings and run these two operations in order:

1. Build Vector Database — scans all your posts and pages, building a semantic index that powers AI-driven link suggestions. Without this, the Review Queue won't have any data to work with. Click the Build Vector Database button and wait for the progress bar to complete. On large sites this may take a few minutes.
2. Sync Manual Links — imports all internal links that already exist in your content (placed manually or by other plugins). This prevents LinkMesh from suggesting duplicate links or reporting false orphans. Click Sync Manual Links — the process is near-instant on most sites.

Configure Your Settings

Now that your content is indexed and existing links are synced, review these three groups of settings in LinkMesh → Bulk Settings before placing any links. Getting these right now prevents messy results later.

Link Limits

Control how many links can appear on any given page and how many times a single page can be linked to:

• Max Outgoing Links — maximum number of LinkMesh-placed links allowed on a single donor post. Default: 5.
• Max Incoming Links — maximum number of links that can point to any single target page from across your site. Default: 5. Prevents over-linking to the same page, which can look unnatural.

Content Rules

Define the physical placement behavior of links within your articles:

• Min Content Length — minimum number of characters a post must have before LinkMesh will process it. Default: 2000. Shorter posts are skipped entirely. Lower this to 500–1000 if you publish news snippets or short updates.
• Skip Intro — number of characters to skip from the beginning of each post before placing the first link. Default: 100. Useful to avoid links in your opening hook or lede paragraph.
• Min Gap Between Links — minimum character distance between two LinkMesh-placed links. Default: 200. Prevents links from clustering together in the same paragraph.

Filtering & Exclusions

Tell LinkMesh where it should and should not operate:

• Allowed Post Types — select which content types LinkMesh can scan and place links on. Default: Posts and Pages. Enable additional CPTs like WooCommerce products or portfolio items here.
• Blacklist Specific Posts — search and select individual posts or pages that should never receive automated links. Use this for landing pages, legal pages, or any content you want to keep link-free.
• Exclude Taxonomies / Terms — skip all posts belonging to specific categories or tags. For example, exclude your "News" or "Glossary" category if those posts shouldn't participate in link building.
• Exclude HTML Areas — protect specific HTML tags from link injection. Default: Headlines (h1-h6), Source code (code, pre), Quotes (blockquote). Add Lists (ul, ol) or Strong/Bold (strong, b) if needed.
• Strict Silo Linking — select taxonomies to isolate link building within the same term. For example, if you select "Categories," articles in the "SEO" category will only link to other articles also in the "SEO" category. Powerful for building topical clusters.

Creating Links

LinkMesh offers three ways to create internal links. Choose the one that fits your workflow.

Dashboard Quick Actions

Best for per-post surgical control. Go to LinkMesh → Dashboard, find a post in the table, and click the ⊕ button in the Actions column:

• AI Smart Link — The engine picks the best link for this post automatically. The suggestion appears in the Review Queue for your approval before placement.
• Manual Keyword Search — Type a keyword, see matching donor posts from your site, and pick the one you want to link from.
• Force Link FROM — Choose a target post and exact anchor text. The plugin places a link from this post to that target.
• Force Link TO — Choose a donor post and exact anchor text. The plugin places a link from that donor to this post.

See the full Dashboard guide for details on all columns, filters, and bulk actions.

Keyword Intelligence

Best for researching linking opportunities and managing existing link rules. Go to LinkMesh → Keyword Intelligence:

• Content Auto-Scanner — Select post types and a date range, then run a scan. The scanner analyzes your content and shows keyword frequencies (Single Keywords), multi-word phrases (N-grams), and surrounding context (Context Analysis). Use the results to pick promising keywords, then create link rules from them.
• Active Custom Routes — A paginated table of all existing link rules. Each row shows the keyword, donor posts, and target. Use this panel to audit your links, search by post title, and delete rules you no longer need. The Sync Manual Links button pulls in links you placed manually.

See the full Keyword Intelligence guide for scanner settings, rule creation, and troubleshooting.

Gutenberg Sidebar

Best for link management while writing or editing content. Open any post in the WordPress block editor:

• The LinkMesh sidebar panel shows inbound and outbound links for the current post. Review, navigate to linked posts, or remove links without leaving the editor.
• The AI Link button in the block toolbar suggests relevant links for selected text on the fly.

This is the fastest way to spot-check and tune links while you create content.

Core Concepts

Understanding these four key concepts will help you use LinkMesh effectively and avoid common pitfalls. Each section explains a layer of the plugin's architecture — from how links are stored, to how they flow through the system, to what guardrails keep your content safe.

1. Static Freeze Model

LinkMesh uses a Static Freeze Model: links are written directly into your post_content in the WordPress database via wp_update_post(). Unlike traditional plugins that inject links dynamically on every page load (adding runtime overhead), frozen links become part of your HTML — no runtime processing needed.

What happens when a link is placed

1. You create a link rule — via Dashboard, Keyword Intelligence, or AI Smart Link.
2. The injection engine reads the rule from wp_ailm_link_rules, locates the anchor text in your post using DOM-based parsing, and wraps it in an <a> tag with the target URL.
3. Each injected link is marked with data-ailm attribute and ailm-internal-link CSS class, so the plugin can identify and manage it later.
4. The modified post content is saved back via wp_update_post().
5. The scanner re-indexes the post, and the reconciler syncs the new link into wp_ailm_links with in_html = 1.

Erase ALL Links

The Erase ALL Links action in LinkMesh → Bulk Settings completely reverses the freeze model in one click. It:

• Deletes every rule from wp_ailm_link_rules.
• Physically unwraps every <a> tag that has data-ailm or ailm-internal-link class — keeping the anchor text intact.
• Resets all inbound link counters to zero.
• Clears all related caches.

This works on standard posts and Elementor pages alike — the Elementor handler traverses element data structures and applies the same unwrap logic.

2. Link Pipeline

LinkMesh operates on a two-table architecture that separates intent from reality:

Every link flows through a four-stage pipeline:

Stage 1: Rule Creation

A link rule is created through any of the three creation paths (Dashboard Quick Actions, Keyword Intelligence, or Gutenberg Sidebar). The rule is stored in wp_ailm_link_rules with in_html = 0 (not yet injected).

Stage 2: Injection

The Link Builder (AILM_Link_Builder) reads active rules for the post, sorts them by anchor length (longest first for correct nesting), checks all safety constraints, then applies links to the post content using the DOM Helper (AILM_DOM_Helper). After saving, each injected rule is marked in_html = 1 to prevent duplicate injection on future edits.

Stage 3: Scanning

The Scout Scanner (AILM_Scout_Scanner::process_post()) parses the updated post content and catalogs every link it finds — internal, external, and sponsored. Links with data-ailm markers are classified as plugin origin; links without markers are classified as manual. Each link's position is recorded as a normalized offset (0.0 to 1.0) for reliable re-identification even after content edits.

Stage 4: Reconciliation

The Reconciler (AILM_Reconciler::reconcile_post()) runs on every save_post at priority 20 (after the scanner at priority 10). It compares rules vs. scanned reality in five steps:

1. Load reality — all links from wp_ailm_links for this post.
2. Load intent — all rules from wp_ailm_link_rules for this post.
3. For each rule: if the link exists in HTML → confirm in_html = 1; if missing → mark as failed or delete (for manual rules).
4. For each real link without a rule → register as manual with in_html = 1.
5. Recalculate _ailm_inbound_count for every target post affected.

This pipeline ensures that what LinkMesh thinks is on your page always matches what's actually there — even when you edit posts manually.

3. Link Validation

Before a link can be injected into any post, the Link Validator (AILM_Link_Validator::validate_donor()) runs eight sequential checks. A single failure blocks the link for that donor post.

There is also a variant — validate_donor_with_content() — used by the Gutenberg sidebar to validate against unsaved editor content, so you get accurate pass/fail feedback in real time before publishing.

4. Injection Safety

Once a link passes validation, the DOM Helper and Link Builder apply a second layer of safety checks during the actual injection. These protect your HTML structure and prevent overlapping or redundant links.

HTML Exclusion Zones

The DOM Helper builds an XPath exclusion that prevents link injection inside:

• Always excluded: existing a tags, script, style.
• User-configurable: headings (h1–h6), strong, em, blockquote, code, lists (ul, ol). Configure in LinkMesh → Bulk Settings.

Block Boundary Protection

The DOM Helper creates a virtual text map where block-level elements (p, div, h1–h6, ul, ol, li, blockquote, etc.) are separated by double newlines. Links can never span across these boundaries — an anchor text that starts in one paragraph and ends in another will not match.

Self-Link Prevention

A post can never link to itself. If donor_id === target_id, the injection is skipped — even if the anchor text appears in the content.

Duplicate Prevention

Before injecting, the engine checks if the target URL is already linked from the same anchor text on that page. If a link already exists, the new injection is skipped. The in_html flag on each rule also prevents re-injection of links that were already placed on a previous save.

Spacing Constraints

Injection Order

Links are sorted by anchor text length (longest first), then applied in reverse order. This ensures that longer phrases like "best SEO plugin for WordPress" are matched before shorter ones like "SEO plugin", preventing incorrect partial matches.

Module Guides

LinkMesh is organized into focused modules, each accessible from the top navigation tabs in the plugin admin. Click any module card to jump to its detailed guide.

Dashboard

The Dashboard is your command center. The top panel displays 8 metric cards showing live site statistics: total articles and pages, internal/external/sponsored link counts, total clicks across all link types, broken links, and orphan pages (posts with zero inbound links). Below the metrics, three charts visualize content distribution (bar chart), links distribution (donut chart), and clicks distribution (donut chart) for quick at-a-glance assessment.

Posts Table

The main working area is an interactive posts table loaded via AJAX, showing all posts and pages across all statuses:

Actions Dropdown

Each post has an actions dropdown (click the "+" button):

Modal Dialogs

✨ AI Smart Link Generator

When you click "AI Smart Link" from the actions dropdown, the AI Smart Link Generator modal opens. The selected post becomes the target (where links will point TO), and the AI engine searches your entire site for the best donor articles — posts that are semantically related and contain suitable anchor text opportunities.

The modal displays a table of donor candidates with:

• Donor Article — the suggested source post with "View" and "Edit" links.
• Relevance — a percentage score (0–100%) with a color-coded progress bar (green ≥ 80%, yellow ≥ 70%, gray < 70%).
• Suggested Context — the paragraph from the donor where the link would be placed.
• Action — a "Generate Link" button that produces an AI-written anchor suggestion for that donor-target pair.

After clicking Generate Link, the AI returns a suggestion in one of two insertion modes:

1. In-Text (green badge) — the anchor phrase already appears in the donor's paragraph, and the AI simply wraps it in a link, leaving the surrounding text unchanged.
2. Rewrite (yellow badge) — the AI rewrites the sentence to naturally incorporate the anchor text, showing a word-level diff of what was added (green) and removed (red) so you can review the change.

You can then click Approve & Apply to immediately insert the link into the donor post. Alternatively, you can select multiple donor candidates via checkboxes (max 10) and click Generate Batch. The batch runs asynchronously — a progress bar tracks completion — and all generated suggestions are sent to the Review Queue for later approval. A "Open Review Queue" button appears once the batch finishes.

Force Link Validation

When creating a link via "Force Link FROM/TO", the plugin runs a series of checks before injection:

1. Donor and target must not be the same post.
2. Donor passes can_inject_phrase(): outbound link limits, blacklists, excluded HTML zones.
3. Target inbound link limit (ailm_target_limit) is not exceeded.
4. The anchor phrase is found in the donor's virtual text (accounting for whitespace and punctuation between words).
5. The match is located after ailm_skip_chars (intro skip offset).
6. No overlap with existing links or manual links (protected by ailm_min_gap).
7. No duplicate: the same donor→target pair with the same anchor text does not already exist.

Only after all checks pass is the link registered in wp_ailm_link_rules and physically written into the donor's post_content. The target's _ailm_inbound_count is then updated and the donor is re-scanned via the Scout Scanner.

Mass Operations

Above the posts table, two mass-action buttons are available:

• Index Selected — sequentially re-indexes checked posts by sending each to the SaaS server via saas_index_document(). Progress is displayed in the button itself ("Indexing (3/7)..."). Useful after bulk imports or content edits.
• Recalculate AILM Rank — triggers a full recalculation of every post and page across the entire site using LinkMesh's proprietary ranking formula. Inspired by Google's PageRank for page authority, the AILM Rank goes further by factoring in: link position within the page (distance from the first screen / viewport), CTR of each individual link, inbound and outbound link counts for the donor, proximity to the homepage (click depth), and many other signals. The SaaS server computes the score for each page and saves results to _ailm_pagerank postmeta. Progress is displayed in the button. Recommended after significant changes to your link structure.

Bulk Settings

The Bulk Settings tab is the central configuration hub for LinkMesh. Here you connect the plugin to the SaaS cloud engine, set linking limits and rules, manage exclusions, and perform system-level operations.

Top Action Bar

The header bar contains four buttons that control the entire plugin:

SaaS Configuration

This card connects your WordPress site to the LinkMesh cloud engine. Without it, AI features and indexing will not work.

• Server URL — the API endpoint of your LinkMesh SaaS server. Default: http://api.linkmesh.co. Change this only if you are using a self-hosted or custom server instance.
• License Key — your unique license key (format: sk_live_...). Obtain this from your LinkMesh account dashboard. The key is stored encrypted and never displayed in plain text after saving.

Semantic AI Indexing

This card controls how your content is indexed into the AI vector database, which powers all semantic matching features (AI Smart Link, Keyword Intelligence).

• Build Vector Database — starts a full re-index of all published posts. The plugin fetches the queue of post IDs, then processes them in batches of 10 via the OpenAI API to prevent timeouts. A progress bar shows real-time status: "Processing chunk (10 posts)… X / Y". The button is disabled during indexing and re-enabled when complete.
• Auto-index on publish/update — when enabled, every new or updated post is automatically sent to the SaaS vector database. Recommended for busy sites where content changes frequently.

Link Limits

Controls how many links the plugin is allowed to place:

• Max Incoming Links (ailm_target_limit, default: 5) — maximum number of internal links that can point to any single post. Prevents any page from becoming an unnatural link magnet.
• Max Outgoing Links (ailm_global_limit, default: 5) — maximum number of internal links the plugin can place from any single donor post. Keeps link density natural.

Content Rules

Fine-tune where and how links are physically placed within post content:

• Min Content Length (ailm_min_chars, default: 2000) — posts shorter than this number of characters are skipped entirely. Prevents linking on thin content pages.
• Skip Intro (ailm_skip_chars, default: 100) — the number of characters from the beginning of the post to skip before placing any links. Protects your introduction/lead paragraph.
• Min Gap Between Links (ailm_min_gap, default: 200) — minimum character distance between two adjacent links. Prevents links from clustering together.

Filtering & Exclusions

Control exactly which content the plugin can touch:

• Allowed Post Types — multi-select list of public post types. The plugin will only search for keywords and place links within the selected types (default: post and page). Uses Select2 with search.
• Blacklist Specific Posts — AJAX-powered search (type a post title or ID) to select individual posts that should never receive automated links. Useful for landing pages, legal pages, or paid content.
• Exclude Taxonomies/Terms — multi-select of all categories, tags, and custom taxonomy terms (up to 500). Posts assigned to any selected term are skipped by the plugin.
• Exclude HTML Areas — choose which HTML zones are protected from link injection. Options: headlines (h1–h6), bold text (strong, b), italic text (em, i), quotes (blockquote), code blocks (code, pre), lists (ul, ol). Default: headlines, code blocks, and quotes are excluded.
• Strict Silo Linking — select taxonomies (e.g., Categories) to enforce strict topical isolation. When enabled, articles will only link to other articles within the same term. Essential for building topical authority clusters.

Tracking & System

• Enable UTM (Internal Tracking) — appends UTM parameters to every internal link placed by LinkMesh. Configure Source, Medium, and Campaign values (defaults: auto_link / internal / seo_auto). Lets you track internal link performance in Google Analytics.
• Count existing manual links towards limits — when enabled, links that already exist in your content (placed manually or by other plugins) count against the Max Incoming/Outgoing limits. Prevents over-linking on posts that already have many manual links.
• Enable Debug Mode — outputs detailed calculation logs at the bottom of each article. Useful for troubleshooting why a link was or was not placed. Only enable when actively debugging.

Database Backup (CSV)

Export and import your entire link map as a CSV spreadsheet:

• Export CSV — downloads a CSV file with columns: donor_id, donor_url, keyword, target_url, target_id, link_origin, action. The link_origin column shows where each link came from (plugin, manual, or scout). UTF-8 encoded with BOM for Excel compatibility.
• Import CSV — upload a CSV file to bulk-update or create links. Existing links for articles included in the file will be overwritten. Useful for batch editing anchor text or target URLs in a spreadsheet, then uploading back.

Keyword Intelligence

Keyword Intelligence helps you build a strategic anchor text profile. Instead of guessing which keywords to use, the module:

• Extracts key phrases from each target page using LSI (Latent Semantic Indexing) analysis.
• Shows keyword density — how often each phrase appears across your site.
• Suggests anchors for each target page, ranked by semantic relevance.
• Tracks anchor text usage to prevent over-optimization (same anchor used too many times).

Anchor Text Best Practices

• Vary your anchor text — don't use the exact same phrase for every link to a page.
• Use natural language — anchors should flow within the sentence.
• Mix exact-match, partial-match, and branded anchors.

404 Scout

Broken internal links hurt user experience and SEO. 404 Scout:

• Scans all internal links (both LinkMesh-placed and manually created) to detect 404 errors.
• Runs in the background via WP-Cron — no manual triggering needed.
• Categorizes errors by source page, making it easy to fix links in bulk.
• Provides one-click fix suggestions — if a target page moved (URL changed), Scout suggests the new URL.

Scan Modes

• Full Scan: checks every internal link on your site. Recommended for initial setup.
• Incremental Scan: only checks links on recently modified pages. Faster, runs automatically.

Click Stats

Click Stats provides real-time analytics on every internal link click across your site:

• Click count per link: see which internal links get the most engagement.
• Click timeline: track clicks over time (daily, weekly, monthly).
• Top performing pages: which pages drive the most internal traffic.
• Click-through rate: clicks per page view for each link.
• Export to CSV: download your click data for external analysis.

The tracking script is lightweight (~2KB) and loaded asynchronously — zero impact on page load times.

Review Queue

The Review Queue is where AI meets human judgment. LinkMesh's semantic engine analyzes your content and suggests links ranked by relevance:

• Relevance Score (0–100): how semantically related the donor paragraph is to the target page.
• Suggested Anchor: the exact phrase LinkMesh recommends as anchor text, highlighted in context.
• Donor & Target Preview: see both pages side-by-side to evaluate the suggestion.
• One-click Approve / Skip: approve places the link immediately (Freeze mode), skip removes it from the queue.
• Bulk Approve: approve all suggestions above a relevance threshold in one click.

Advanced

For power users who want to customize LinkMesh beyond the default settings.

CSV Import / Export

LinkMesh provides a universal CSV export/import system for bulk link management. Both features are located at the bottom of the Bulk Settings tab, inside the Database Backup card.

Export CSV

Clicking EXPORT CSV File generates a universal CSV file containing every published post across all allowed post types — regardless of whether the post has links or not. The file is named ailm_universal_export_YYYY-MM-DD.csv and includes a UTF-8 BOM header for compatibility with Microsoft Excel.

The CSV has seven columns:

Each donor post produces one or more rows: one row per AILM link, one row per manual link, or a single none row if the post has no links whatsoever.

Import CSV

Clicking IMPORT CSV File opens a file upload dialog. Select your edited CSV and click Upload & Import. The import process:

1. Skips the header row (first line is ignored).
2. Skips invalid rows — any row where donor_id, keyword, or target_url is empty is silently ignored.
3. Skips manual and none rows — rows with link_origin set to manual or none are never modified. The plugin never touches manually created links via CSV import.
4. Honors the action column: set action to delete to remove a link rule from the database. Leave empty (or any other value) to keep or create the link.
5. Registers each kept link via AILM_Link_Repository::register_link() with in_html=0 — the rule is saved to the database but not yet physically injected. Injection happens on the next content save or manual injection trigger.
6. Re-scans each modified donor with AILM_Scout_Scanner::process_post() to update the 404 Scout monitor table.

After import completes, you are redirected back to the Bulk Settings tab with a success or error notice.

Roadmap

What's coming next for LinkMesh. Priorities and timelines are subject to change based on user feedback.

Q3 2026 (In Progress)

• llms.txt & Markdown Endpoint: Implementation of automated llms.txt generation and a Markdown endpoint to optimize site content for AI agents (GEO/LLMO). Provides structured, machine-readable access to your site's key pages — improving how LLMs discover, understand, and cite your content.
• Bulk URL Update on Site Restructure: Automatic site-wide update of all internal links when your permalink structure or URL patterns change, executed in a single batch operation. DONE

Q4 2026 (Planned)

• Auto-Suggest: Automatically scans new articles upon publication to generate smart, ready-to-approve internal link suggestions.
• Google Search Console Integration: Connect your GSC account to correlate internal link data with search performance — see which linked pages are gaining or losing organic traffic, identify ranking opportunities, and track the SEO impact of your linking strategy.
• Bing Webmaster Tools Integration: Pull in Bing search performance data alongside Google — get a complete picture of how your internal links influence rankings across both major search engines.
• Yandex Metrica Integration: Import behavioral analytics from Yandex Metrica — session replays, scroll maps, and click heatmaps — to understand how real users interact with your internal links on-page.

Q1 2027 (Planned)

• Mesh Network: Connect multiple websites into a unified private network to safely distribute link equity and automate cross-site linking.