---
title: "How I automated internal linking with AI"
url: "https://sarthakmishra.com/library/blog/automating-internal-linking"
description: "Find internal link opportunities with embeddings and a reranker, make an LLM justify each link, and place links at build time instead of editing MDX."
image: "https://sarthakmishra.com/og-images/blog/automating-internal-linking.webp"
---

[View HTML](https://sarthakmishra.com/library/blog/automating-internal-linking) · [Site index](https://sarthakmishra.com/llms.txt)

# How I automated internal linking with AI

Find internal link opportunities with embeddings and a reranker, make an LLM justify each link, and place links at build time instead of editing MDX.

![Magnifying glass examining highlighted lines on overlapping documents, with pink accents and a yellow lightning bolt.](https://sarthakmishra.com/assets/automating-internal-linking-hero-CmnMhnJ4.jpeg)

I built an AI script to add internal links to this site. A week after writing about it, I removed all 44 links it had added.

The script happily linked “learning experience” to an essay about risk. It could explain the connection, and the explanation passed the checks I’d written. I still wouldn’t have added that link myself.

I wanted the script to find useful links. It should scan the writing for a phrase that points to another article, then check whether that article delivers what the phrase suggests. So I tightened the judgment and moved the generated links out of my MDX files. **The script can now replace its own links without touching mine.**

Google’s [link guidance](https://developers.google.com/search/docs/crawling-indexing/links-crawlable) recommends descriptive anchor text and links that help readers understand the current page. That’s the standard I’m aiming for. I haven’t measured any ranking improvements from this (yet).

## Don’t let the script edit your source

Writing Markdown into a Markdown file seemed reasonable. I could review the diff and commit it with the rest of the post. Then the script ran again.

**It treated its previous output as something I’d chosen.** Once a link was in the MDX, the script couldn’t tell it apart from one I’d typed. It counted toward the page’s link allowance and never got reviewed again. I had to find and remove the weak ones myself.

My prompt made this worse. It asked whether the destination “explains, demonstrates, or substantiates” the idea in the sentence. That was broad enough to approve “AI technology” pointing to a shopping app case study, or “AI providers” pointing to a post about AI inference economics. The model could justify both. Neither link told the reader much about what they’d find.

The cleanup pass also deleted a real `/contact` link. It removed URLs missing from its list of published content, and ordinary site pages weren’t in that list. I’d even warned in the first version of this post that it could mistake a valid `/about` link for a dead one. Apparently writing down the bug wasn’t enough. I had to restore the contact link by hand.

Keeping generated links in a separate file gives the script something it can safely replace. I can make its rules stricter and rerun it without first untangling its old output from my writing.

## The pipeline

The script is TypeScript. It reads the site’s published posts, work pages and newsletter issues, finds candidates, and writes the accepted links to a JSON file. A shared function places those links when the site builds.

I run it while working on the content:

```bash
pnpm run inlinks            # writes src/data/editorial/internal-links.json
pnpm run inlinks --dry-run  # lists reranked candidates, no chat calls or writes
```

It’s also part of `pnpm run content:prepare`, which refreshes every AI-generated input the site uses.

The model calls go through the Vercel AI SDK and AI Gateway. I’m using `voyage/voyage-4-large` for embeddings, `voyage/rerank-3` for reranking, and `openai/gpt-6-luna` for summaries and link decisions. You can swap those through one policy object.

From article passages to a link on the built page · No · Yes · No · Yes · Published MDX · Extract prose passages · Embed passages under the article title · Shortlist similar passage pairs · Rerank the shortlist · Model rates fit 3? · No link · Placement succeeds on the parsed post? · Store link in internal-links.json · Build places the link unless the author already links that page

Embeddings and a reranker narrow the search. The model judges the best candidates. The same placement code accepts a link during generation and renders it during the build.

## Parse the post before looking for anchors

An MDX file contains paragraphs, code samples, imports, components and comments. A phrase inside a code sample can look like a perfect anchor to a text search. Turning it into a link would damage the example.

The script parses each body into AST, with remark. It uses the same MDX and Markdown extensions as the site, so the generator and the build agree on where the text is.

It collects paragraph text and skips code blocks, JSX, imports, exports and MDX expressions, including `{/* comments */}`. Link text and inline code stay in the extracted text. The first version dropped inline code, which threw away file names, commands and package names. Those are often the most useful words in a technical paragraph (even when they can’t become the anchor).

Paragraphs are packed into passages of about 600 characters, and long paragraphs split at sentence boundaries. The opening paragraph is kept as its own passage because it never gets a generated link.

## Give each passage its title, then stop adding context

I initially put the article’s title, description, summary, tags and up to twelve headings in front of every passage. A passage mentioning “the cache” could use some context about which cache it meant. I gave it quite a lot.

The prefix was about as long as the 600-character passage itself. Repeating it made the passages from an article look alike, so the similarity scores mostly reflected the article’s overall topic. Changing a description also meant paying to embed every passage again.

Now the embedding input is just the title and the passage:

```ts
export function embeddingInputs(doc: Pick<Doc, 'meta' | 'chunks'>): string[] {
  return doc.chunks.map((chunk) => `${doc.meta.title}\n\n${chunk}`);
}
```

The title gives a short passage some context without burying it. The model gets the article’s description and summary later, when there’s a specific link to judge.

## Use similarity to find candidates, then rerank them

An embedding represents text as a vector. Cosine similarity compares two of those vectors, which gives the script a cheap way to look for related passages.

For each passage after the opening one, it searches the passages in other documents. It skips destinations the post already links to and ignores pairs scoring below `0.5`. It keeps the best passage pair for each destination, then shortlists up to twelve destinations for the source article.

Shared vocabulary can get a pair onto that list. The reranker then reads both passages together and scores their relevance. It gets the source passage as its query and the destination passage, plus one passage on either side, as the text to judge.

Candidates below `0.55` are dropped, and each source passage keeps its best remaining candidate. Service pages can be destinations too. They get a small ranking boost to win close calls, but still have to pass the same score thresholds and link judgment.

The script adds at most three links per page. Each distinct internal destination I’ve already linked to uses one of six available slots. With five manual destinations, there’s room for one generated link. It sends up to twice as many candidates as open slots to the chat model, since most get rejected.

I chose the `0.55` reranking floor by reading the results. At `0.5`, a sentence mentioning “programmatic SEO” in passing got linked to a newsletter that also mentions it in passing. The model called it a perfect fit. The reranker gave it `0.51`, while every other accepted link scored at least `0.67`. Raising the floor removed that bad match. I’d tune it again for a different set of articles.

## Make the model explain what the reader gets

Asking for a yes or no made it too easy for the model to approve a vague connection. The new prompt asks it to name the destination’s subject and the reader’s question before choosing an anchor or rating the fit. Each part has a field in the answer:

```ts
const judgmentSchema = z.object({
  targetSubject: z.string(),
  readerQuestion: z.string(),
  anchorText: z.string(),
  sourceSentence: z.string(),
  targetEvidence: z.string(),
  fit: z.number().int().min(0).max(3),
});
```

`targetSubject` names what the destination article is about, using its title and summary. `readerQuestion` states what someone reading the source passage would want to know next. That gives me something to check when reviewing a suggestion. A question the passage never raises is a good reason to reject the link.

The anchor has to name the destination’s subject well enough that you can predict what you’ll get by clicking it. The prompt includes the generic phrases that failed before, such as “learning experience” and “AI technology”, as examples to reject.

The rating makes the cutoff explicit:

| Fit | What the destination offers at this sentence                                                                 |
| --- | ------------------------------------------------------------------------------------------------------------ |
| 0   | Nothing relevant.                                                                                            |
| 1   | A shared topic, tool, company, audience or vocabulary.                                                       |
| 2   | Related material, but the sentence makes a different point or the destination only partly covers the anchor. |
| 3   | The obvious next read. The anchor names the destination’s main subject, and the sentence is about it.        |

**Only a 3 becomes a link.** Two posts using Astro get a 1 unless there’s a more specific reason to connect them.

The model can read the passages before and after the source for context, but it must copy the sentence and anchor from the source passage itself. Code checks that both are there, that the anchor is plain text, and that it passes the length and stopword rules. The evidence sentence must also appear in the destination text the model saw.

An exact quote can still be a lousy justification. These checks catch invented evidence and unsuitable anchors. I still have to judge whether the link makes sense.

In one full run, 58 candidates reached this stage and 8 survived. The model rejected 3 as unrelated, 33 as sharing only a topic, and 13 as related but making a different point. One more failed the evidence check. **Most of the candidates shared a topic and nothing more.**

## Store the links separately and place them at build time

An accepted link becomes a record in `src/data/editorial/internal-links.json`:

```json
{
  "target": "/blog/setting-up-traefik-from-local-to-production",
  "anchor": "set up Traefik",
  "passage": "You set up Traefik, open ports 80 and 443, configure Let's Encrypt, and deploy your services with Docker Compose.",
  "evidence": "With Traefik properly configured, I can now deploy services with confidence.",
  "score": 0.8155127763748169
}
```

The passage locates the link and the anchor says which words to wrap. The evidence and score let me review why the link was suggested. Placement doesn’t use them.

One function, `placeLinks`, decides whether a record can go into a post. The passage must appear exactly once in the eligible paragraphs, and the anchor must appear once as whole words inside it. The anchor also has to fit inside a single run of plain text. The function skips the opening paragraph, headings, code, components and existing links, and rejects anchors that cross formatting.

Before any of that, it checks the links already in the post:

```ts
const manual = linkedTargets(tree);
const placed = new Set<string>();
return links.map((link) => {
  const target = targetPath(link.target);
  if (manual.has(target)) return 'manual-target';
  if (placed.has(target)) return 'duplicate';
  if (!place(tree, link)) return 'unplaceable';
  placed.add(target);
  return 'applied';
});
```

**A link I write always takes priority.** If I link a page anywhere in the post, the generated link to that page is skipped. I can choose a better sentence or anchor without changing the generator.

The generator runs this function before accepting a link, and the build uses it again when rendering the page. That keeps both sides under the same placement rules. It runs before the plugin that turns straight quotes into curly ones, so those substitutions don’t break the match.

The stored file also records a fingerprint of the published content it was generated from. Editing a title, description or prose makes the links stale. The content check warns, and the build drops links it can no longer place while keeping the rest. Running `pnpm run inlinks` again refreshes them.

That’s why I unwrapped those 44 links back to plain text. The MDX now contains only the links I wrote. Changing the generator’s policy replaces its output in the JSON file on the next run.

## Cache rejections too

Every paid call is cached, keyed by the exact text sent and the model that read it:

| Cache           | What makes an entry reusable                              |
| --------------- | --------------------------------------------------------- |
| Passage vectors | Same embedding model and same title-plus-passage text     |
| Rerank scores   | Same reranker, source passage and destination passage     |
| Article summary | Same chat model and same summary prompt                   |
| Link judgments  | Same chat model and same judgment prompt, accepted or not |

The model belongs in the cache key. Otherwise, changing embedding models could leave the script comparing vectors from different models just because the text hadn’t changed.

Rejected candidates get cached too. The old script paid to ask about the same bad links on every run. There’s no reason to ask again until the input or model changes.

Adding a post costs calls for its new passages and the uncached candidates it takes part in. A dry run does retrieval and reranking without chat calls. That’s how I tuned the score thresholds, and at this site’s size those runs cost cents.

## Test placement without calling a model

The placement rules have deterministic answers, so their tests run on parsed Markdown with no model at all. They cover the opening paragraph, repeated passages, partial words, headings, code, components, existing links, formatting boundaries and the manual-link priority. The judgment tests mock the model and check that anything below a fit of 3 is rejected, along with invented evidence, sentences copied from context and generic anchors.

I review the model’s taste by reading its suggestions. The code’s ability to put a link in the right place is something a test can settle. A broken placement rule shouldn’t need a paid model call to show up.

## Eight links was enough

That full run covered 50 posts, work pages and newsletter issues, and produced 8 links. The old script had written 44 over several runs. I could loosen the filters to get more, but I’d rather leave a paragraph alone than send someone to a barely related article.

The search still compares passages across documents, so the work grows roughly with the square of the corpus. It’s fine for this site. I haven’t measured where it stops being fine.

The decision I’d carry into another project is to **keep generated suggestions separate from authored content**. It gives me room to change the prompt, reject an earlier result, or replace the model without cleaning up its old edits by hand. That was worth rebuilding the script for.

## Media sources

### From article passages to a link on the built page

```mermaid
flowchart TD
A[Published MDX] --> B[Extract prose passages]
B --> C[Embed passages under the article title]
C --> D[Shortlist similar passage pairs]
D --> E[Rerank the shortlist]
E --> F{Model rates fit 3?}
F -->|No| G[No link]
F -->|Yes| H{Placement succeeds on the parsed post?}
H -->|No| G
H -->|Yes| I[Store link in internal-links.json]
I --> J[Build places the link unless the author already links that page]
class E blue
class F yellow
class H yellow
class J green
```

## Structured data

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "@id": "https://sarthakmishra.com/#website",
      "url": "https://sarthakmishra.com/",
      "name": "Sarthak Mishra",
      "publisher": {
        "@id": "https://sarthakmishra.com/#person"
      },
      "inLanguage": "en"
    },
    {
      "@type": "Person",
      "@id": "https://sarthakmishra.com/#person",
      "name": "Sarthak Mishra",
      "url": "https://sarthakmishra.com/about",
      "jobTitle": "Design Engineer",
      "image": "https://sarthakmishra.com/og-images/sarthak-mishra.webp",
      "sameAs": [
        "https://github.com/SarthakMishra",
        "https://www.linkedin.com/in/itssarthakmishra/",
        "https://x.com/MishraMishry"
      ]
    },
    {
      "@type": "WebPage",
      "@id": "https://sarthakmishra.com/library/blog/automating-internal-linking#webpage",
      "url": "https://sarthakmishra.com/library/blog/automating-internal-linking",
      "name": "How I automated internal linking with AI - Sarthak",
      "description": "Find internal link opportunities with embeddings and a reranker, make an LLM justify each link, and place links at build time instead of editing MDX.",
      "inLanguage": "en",
      "isPartOf": {
        "@id": "https://sarthakmishra.com/#website"
      },
      "mainEntity": {
        "@id": "https://sarthakmishra.com/library/blog/automating-internal-linking#content"
      },
      "breadcrumb": {
        "@id": "https://sarthakmishra.com/library/blog/automating-internal-linking#breadcrumb"
      }
    },
    {
      "@id": "https://sarthakmishra.com/library/blog/automating-internal-linking#content",
      "url": "https://sarthakmishra.com/library/blog/automating-internal-linking",
      "name": "How I automated internal linking with AI",
      "description": "Find internal link opportunities with embeddings and a reranker, make an LLM justify each link, and place links at build time instead of editing MDX.",
      "mainEntityOfPage": {
        "@id": "https://sarthakmishra.com/library/blog/automating-internal-linking#webpage"
      },
      "author": {
        "@id": "https://sarthakmishra.com/#person"
      },
      "datePublished": "2026-10-19T00:00:00.000Z",
      "dateModified": "2026-10-31T00:00:00.000Z",
      "inLanguage": "en",
      "keywords": [
        "ai",
        "typescript",
        "automation",
        "embeddings",
        "seo"
      ],
      "@type": "BlogPosting",
      "headline": "How I automated internal linking with AI",
      "publisher": {
        "@id": "https://sarthakmishra.com/#person"
      },
      "image": "https://sarthakmishra.com/og-images/blog/automating-internal-linking.webp"
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://sarthakmishra.com/library/blog/automating-internal-linking#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://sarthakmishra.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Blog",
          "item": "https://sarthakmishra.com/library/blog"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "How I automated internal linking with AI",
          "item": "https://sarthakmishra.com/library/blog/automating-internal-linking"
        }
      ]
    }
  ]
}
```
