# Link Engine

## Link Engine

Link Engine automatically discovers and injects relevant internal and external links into your generated content. No more manual linking - Cuppa handles it during generation.

***

### How Link Engine Works

#### The Problem

Manually adding links is:

* Time-consuming (finding relevant pages)
* Inconsistent (some articles get links, others don't)
* Hard to scale (especially for bulk generation)
* Easy to forget (publishing without links)

#### The Solution

Link Engine uses a **hybrid search approach**:

1. **BM25 (Keyword Search):** Finds pages with matching terms
2. **Vector Search (Semantic):** Finds conceptually related pages
3. **AI Reranking:** Claude ranks results by relevance

This combination finds links that are both topically relevant and contextually appropriate.

***

### Link Sources

#### Internal Links (Your Site)

Link Engine discovers pages from:

| Source                 | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| **Sitemap**            | Automatically imports URLs from your sitemap.xml              |
| **Published Articles** | Content you've published through Cuppa                        |
| **Planned Content**    | For bulk projects, links to articles being generated together |

#### External Links (Authority Sources)

Curated authority links by industry:

* Industry publications
* Wikipedia articles
* Research sources
* Government/official sites
* Trusted reference material

***

### Setting Up Link Engine

#### 1. Import Your Sitemap

1. Go to **Brand DNA → Link Engine**
2. Click **Import Sitemap**
3. Enter your sitemap URL: `https://yoursite.com/sitemap.xml`
4. Cuppa indexes all URLs with descriptions

#### 2. Configure Link Settings

| Setting                | Description                        | Recommended |
| ---------------------- | ---------------------------------- | ----------- |
| **Max Internal Links** | Total internal links per article   | 3-5         |
| **Max External Links** | Total external links per article   | 2-3         |
| **Links Per Section**  | Max links within each section      | 1-2         |
| **Minimum Confidence** | Threshold for link inclusion (0-1) | 0.7         |

#### 3. Set URL Pattern (For Bulk Generation)

If generating content in bulk that will link to each other:

**URL Pattern:** `https://yoursite.com/blog/{slug}/` **Slug Format:** kebab-case, snake\_case, or as-is

This allows articles to link to each other before they're published.

***

### How Links Are Injected

#### During Generation

1. Content topic is analyzed
2. Link Engine searches your indexed URLs
3. Top matches (internal + external) are provided to AI
4. AI naturally places links where contextually appropriate

#### Link Placement

Links are placed:

* In relevant paragraphs (not forced)
* With appropriate anchor text
* Without over-optimization
* Distributed throughout the article

#### Self-Exclusion

Smart logic prevents:

* Articles linking to themselves
* Circular reference chains
* Duplicate links within an article

***

### Bulk Generation Cross-Linking

For bulk projects (10+ articles), Link Engine enables **cross-linking between articles in the same batch**:

#### How It Works

1. Before generation, all planned articles are indexed
2. Each article can link to others being generated
3. URLs are predicted based on your URL pattern
4. Links work immediately upon publishing

#### Example

Generating 20 articles about "Digital Marketing":

* Article about "SEO" can link to "Content Marketing" article
* "Email Marketing" article links to "Automation" article
* All interconnected, building topic authority

***

### Link Quality Signals

Link Engine prioritizes links based on:

| Signal               | Weight | Description                    |
| -------------------- | ------ | ------------------------------ |
| **Relevance Score**  | 40%    | Semantic similarity to content |
| **Domain Authority** | 25%    | Site credibility (external)    |
| **Content Match**    | 20%    | Keyword and topic overlap      |
| **Link Type**        | 15%    | Contextual > navigational      |

***

### Viewing Link Performance

After generation, view:

* Which links were added
* Link placement in content
* Confidence scores for each link
* Internal vs. external breakdown

***

### Advanced: Claude Reranking

For highest-quality linking, enable **Claude Reranking**:

* Uses Claude to score each potential link
* Evaluates contextual appropriateness
* Filters out marginally relevant links
* Requires Anthropic API key

***

### Troubleshooting

#### "No internal links added"

**Causes:**

* Sitemap not imported
* Sitemap has no crawlable URLs
* Content doesn't match any indexed pages

**Solutions:**

* Verify sitemap import completed
* Check that sitemap URLs return valid pages
* Add more pages to your site or lower confidence threshold

#### "Links feel forced"

**Solution:** Raise minimum confidence threshold to 0.8+. This ensures only highly relevant links are included.

#### "Wrong pages being linked"

**Cause:** Page descriptions may not reflect content accurately.

**Solution:** Re-index sitemap after updating meta descriptions.

#### "Bulk cross-links not working"

**Check:** URL pattern matches your actual publishing URLs. Test with one article first.

***

### Best Practices

#### Sitemap Optimization

For best results, ensure your sitemap:

* Is up to date
* Includes all important pages
* Has accurate `<lastmod>` dates
* Contains properly formatted URLs

#### Link Balance

**For SEO articles:**

* 3-5 internal links (distribute topic authority)
* 2-3 external links (cite sources, build trust)

**For product pages:**

* 2-3 internal links (related products/features)
* 1-2 external links (reviews, specifications)

#### Anchor Text

Link Engine uses natural anchor text:

* ✅ "Learn more about content optimization"
* ✅ "According to Google's SEO guidelines"
* ❌ "Click here for more information"
* ❌ "SEO SEO SEO optimization guide"

***

### Related Features

* Bulk Article Generation — Generate at scale with cross-linking
* Content Optimization — Score your linking quality
* Brand Research — Discover competitor link strategies


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/brand-dna/link-engine.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.