Internal linking automatically adds links to relevant pages across your website. You configure which terms should link to which URLs, publish your configuration, and an embeddable script handles everything else — scanning your page content and inserting links where those terms appear.

This improves SEO by creating a structured internal link network and helps visitors navigate to relevant content without any ongoing manual work.

Plan requirements

Growth plan and above required — Internal linking is available on Growth, Business, and Enterprise plans. Upgrade your plan

How it works

Internal linking has three parts:

1. Configure your link mappings

In the ConvertMate dashboard, you create link mappings — pairs of terms and target URLs. For example:

• "conversion rate optimization" → /blog/cro-guide
• "free shipping" → /shipping-policy
• "ergonomic office chair" → /collections/ergonomic-chairs

Each mapping tells the script: when you see this term in page content, link it to this URL.

2. Publish to CDN

When you're ready, click Publish to CDN. ConvertMate uploads your link configuration as a JSON file to a CDN. The embeddable script loads this file to know which terms to link and where.

You need to republish after making changes for them to take effect on your website.

3. The script links terms automatically

The embeddable script runs on your website. When a visitor loads a page:

1. The script loads your link configuration from CDN (cached locally for 24 hours)
2. It scans the page content for your configured terms
3. It inserts links for the first occurrence of each term on that page
4. It applies a smart limit so pages are not over-linked

No server changes are required. The script runs entirely in the visitor's browser.

Getting started

Step 1: Install the script

Add the installation snippet to your website's HTML, just before the closing tag:

<script src="https://cdn.convertmate.io/js/internal-linking.js"
        data-workspace-id="YOUR_WORKSPACE_ID" async></script>

Your workspace ID is pre-filled in the snippet shown in the dashboard. Copy it with one click.

Go to internal linking

Step 2: Add link mappings

Click Add link and fill in:

• Term — The word or phrase to link (e.g., "content strategy")
• Target URL — Where the link should point (e.g., /blog/content-strategy-guide or https://yoursite.com/page)
• Priority — When multiple terms match in the same content area, higher priority terms are linked first (0–100)
• Whole word only — Enabled by default; prevents partial word matches (e.g., "shirt" won't match "t-shirt")
• Open in new tab — Links open in a new browser tab

Step 3: Publish

Once you've added your link mappings, click Publish to CDN. Your configuration goes live on the CDN within seconds. The script on your website will pick up the new configuration the next time a visitor's browser cache expires (up to 24 hours) or immediately on a fresh visit.

Smart link limit

The script uses a word-count-based limit to avoid over-linking pages. The limit is approximately one internal link per 175 words of content.

| Page word count | Maximum links | |----------------|---------------| | Under 175 words | 1 | | 175–349 words | 1 | | 350–524 words | 2 | | 700 words | 4 | | 1,200 words | 6 | | 2,000 words | 11 |

This keeps link density natural and prevents any single page from being cluttered with links, which can hurt both user experience and SEO.

The same limit applies when ConvertMate inserts internal links during blog content generation.

Link mapping options

Priority

Priority determines which terms are linked when multiple terms appear in the same content block. Terms with higher priority numbers are matched first.

Use higher priority for:

• Core product or service terms
• Pages with high conversion value
• Terms that appear frequently across your site

Use lower priority for:

• Supporting content terms
• Less important pages
• Terms with many aliases

Whole word only

When enabled (the default), the script only matches complete words. The term "chair" will match "office chair" and "ergonomic chair" but not "wheelchair" or "highchair".

Disable this for terms where partial matching is useful, though this is rarely needed.

Open in new tab

When enabled, links open in a new browser tab using target="_blank". Useful for links to external resources or pages where you don't want visitors to leave the current page.

Aliases

Aliases are alternative phrasings that link to the same URL. For example, for a page about CRO:

• Main term: "conversion rate optimization"
• Aliases: "CRO", "conversion optimization"

All three terms will link to the same target URL. Aliases use the same priority as the main term.

Exclude URLs

Exclude URLs prevent the link from appearing on specific pages of your website. Useful when:

• You don't want a term linked on its own target page (the script already handles the current-page case automatically, but you may have related pages)
• Certain landing pages should not have internal links for conversion reasons
• Blog posts about a topic shouldn't link to themselves

Use wildcards for patterns: /blog/* excludes all blog pages.

What the script links (and what it skips)

The script only inserts links in main content areas and skips navigational and structural elements.

Links are added in:

• and

  elements
• Elements with role="main"
• Elements with class .content or id #content
• Falls back to if none of the above are found
• Within

  , , ,

• , and
  tags

Links are never added in:

• Existing tags (no nested links)

• through

  headings

• and

   blocks

• , form controls, and scripts

The script also skips the home page (/) and any page where the term's target URL matches the current page URL.

Dynamic content

The script uses a MutationObserver to detect when new content is added to the page (for single-page applications and dynamically loaded content). New content is processed automatically with a small debounce delay to avoid performance issues.

Publish status

The publish bar at the top of the internal linking page shows:

• Active links — Number of link mappings that are currently active
• Total links — Total link mappings including inactive ones
• Last published — Date and time of the last publish
• Version — Version number incremented on each publish

Changes to link mappings are not live on your website until you publish again.

Managing link mappings

Search and filter

Use the search bar to find specific terms or URLs. Filter by status (all, active, or inactive) to see only the mappings you want to work with.

Activating and deactivating links

Toggle individual links on or off using the active toggle in the table. Inactive links are excluded from the next publish but remain saved in ConvertMate.

This is useful for temporarily disabling a link without deleting it — for example, during a seasonal campaign or when a target page is being updated.

Editing links

Click the edit icon on any row to update any field. Changes take effect on your website after you publish.

Deleting links

Click the delete icon to permanently remove a link mapping. This cannot be undone. After deleting, publish again to remove the link from your website.

Best practices

Start with your most valuable pages — Begin with terms that lead to high-converting pages: product categories, key blog posts, or service pages. Match how customers search — Use the terms your visitors actually type, not internal jargon. Check your search analytics for common queries. One target URL per topic — Avoid creating multiple mappings that all point to different pages for the same broad topic. This dilutes the linking signal. Use aliases for common variations — Instead of separate mappings for "CRO", "conversion rate optimization", and "conversion optimization", use one mapping with aliases. Set exclude URLs on target pages — If a page is about "conversion rate optimization", exclude it from linking on that page to avoid self-referencing links. Don't over-configure — The smart limit handles link density automatically. You don't need to manually restrict how many mappings you create — the script picks the highest-priority ones that fit within the word count limit. Republish after changes — After adding, editing, or deleting mappings, click Publish to CDN to update your live configuration.

Troubleshooting

Links not appearing on my website

• Verify the installation snippet is added to your website's HTML before
• Check that the data-workspace-id attribute matches your workspace ID (shown in the snippet)
• Make sure you've clicked Publish to CDN after adding your mappings
• The browser may have a cached version — wait up to 24 hours or clear localStorage in developer tools
• Confirm the terms appear in allowed content areas (not in headings or navigation)

A specific term is not being linked

• Check that the mapping is set to active
• Verify the term appears on the page as an exact match (whole word matching is on by default)
• The term may already be inside a link elsewhere on the page — the script skips terms that are already linked
• The page may have reached its smart link limit based on word count
• The target URL may match the current page URL — the script skips self-referencing links
• Check if the page URL matches an exclude pattern on that mapping

Links appear on unwanted pages

• Add the page URL pattern to the Exclude URLs field on the relevant mapping
• Use wildcards for sections: /blog/* excludes all pages under /blog/

Changes not reflected on the website

• Click Publish to CDN — changes only go live after publishing
• The CDN cache clears immediately on publish, but visitor browsers may use their local cache for up to 24 hours

Publish button is disabled

• The Publish button is disabled when there are no active link mappings
• Activate at least one mapping, then publish

Related topics

• Blog writer agent
• Content suggestions
• Smart Collections
• Plan features

Need help? Use the chat widget in the bottom-right corner or email support@convertmate.io.