Building a Hebrew-First SEO Plugin (“Project Spark”) — Part 18 of 20

Automated internal linking is the highest-risk SEO feature you can build: it rewrites stored content across the whole site. Project Spark’s SILO engine — keyword-to-URL rules applied site-wide, plus link-graph analysis — shipped only after we answered one question convincingly: how do you machine-edit thousands of posts and never corrupt one?

Key takeaway: Never run find-and-replace regex over raw post content. Safe automated linking requires HTML tokenization (so you only touch real text nodes), page-builder detection (so you never touch serialized builder data), and a dry-run-first workflow with per-post preview.

Why internal linking is worth the risk

Before the safety engineering, the case for the feature. Internal links are among the most underused levers in technical SEO: they tell crawlers which pages matter, they concentrate topical authority into pillar pages, and they carry real readers deeper into the site. A SILO structure — topic clusters in which supporting articles link up to a pillar page and the pillar links back down — turns a flat pile of posts into a hierarchy that both crawlers and language models can understand.

The problem is labour. Maintaining consistent keyword-to-URL linking by hand across hundreds or thousands of posts is exactly the kind of repetitive, rule-based work that begs for automation — and exactly the kind of automation that, done naively, destroys the content it was meant to improve. The client’s site mixed classic editor posts, page-builder layouts, and Hebrew/Latin keyword rules; a corruption in any of them would be a production incident on a live business. So the engineering question was never “can we insert links automatically?” — that is an afternoon of work. It was “can we make the worst case boring?”

Why naive linking destroys sites

The tempting implementation — regex keyword replacement over post_content — fails catastrophically in three ways:

1. It links inside markup. A keyword occurring inside an attribute, a heading, an existing link, or a code block becomes nested garbage. A keyword that happens to appear inside an image’s alt text becomes an anchor tag inside an attribute value — instantly invalid HTML that renders as visible tag soup.
2. It corrupts page builders. Elementor and friends store layouts as structured JSON in meta; other builders use dense shortcode markup in content. Injecting an anchor tag into serialized JSON doesn’t add a link — it destroys the page. The failure is not degraded; it is total: the layout no longer parses, and the editor may not open it again.
3. It over-links. Unbounded replacement turns every occurrence of a keyword into a link, producing spam that reads badly and ranks worse. A keyword that appears forty times becomes forty identical links — a pattern search engines have treated as manipulation for two decades.

There is a fourth, quieter failure: irreversibility. A naive implementation writes the modified content back over the original with no record of what it changed. When the site owner notices a problem a week later, there is nothing to revert to except a backup — if one exists, and if they can afford to lose a week of other edits.

The safe design

• Tokenize, then edit. Content is parsed so replacements happen only in genuine text nodes — never inside existing anchors, code/pre blocks, scripts, styles, or headings. The skip list is explicit and deliberate: existing anchors because nested links are invalid; code and preformatted blocks because their text is literal by definition; headings because a heading is a structural element, not link inventory. Tokenization-first means the engine can never even see an attribute value or a tag name as replaceable text — a whole category of corruption becomes structurally impossible rather than carefully avoided.
• Detect builders and step aside. A registry recognizes the major page builders — the four dominant ones cover most of the market — by their fingerprints: the metadata markers and content signatures each builder leaves. Builder-managed content is skipped entirely — the honest answer, since safely editing four proprietary formats is a product in itself. This is the same restraint argument as the read-only Google integration in Part 10: the feature that refuses to act where it cannot act safely is more valuable than the feature that tries.
• Budget the links. Per-post caps per keyword, first-occurrence-only linking, and case-sensitivity as an explicit choice per rule (essential when rules mix Hebrew and Latin keywords — Hebrew has no letter case, so a case-insensitive default is meaningless for one half of the rule set and load-bearing for the other).
• Dry-run everything. Every apply operation has a preview mode showing exactly which posts change and what replacements occur — same code path, write disabled — plus a full strip operation to reverse everything. Machine edits you can’t preview and can’t undo are not features; they’re incidents.
• Batch with bounded memory (Part 16): site-wide applies process posts in small batches with cache clears between, so memory stays flat on shared hosting regardless of site size.

The dry-run discipline, in detail

Two implementation decisions make the preview trustworthy rather than decorative.

First, the preview and the apply share one code path. The dry run executes the entire replacement pipeline — tokenization, rule matching, budgeting — and simply withholds the final write. A preview implemented as separate “estimation” logic drifts from the real behaviour over time, and a drifted preview is worse than none: it teaches operators to trust a lie. Same path, one flag, no drift.

Second, the undo shipped before the feature. The strip operation — remove every link the engine ever inserted, across the whole site — was built and tested before the apply was exposed to users. That ordering is a policy worth stating: for any feature that performs bulk edits, build the reversal first. It changes the psychology of every subsequent decision; nobody ships a risky edge case quietly when the undo already exists to be tested against it.

The workflow that operators actually experience: define rules → dry-run site-wide → review the per-post change list → apply in batches → spot-check → and know that one action reverses everything. Machine editing became boring, which was the goal.

The analysis layer

Rewriting is half the feature; understanding the link graph is the other half. The engine builds a site-wide graph and surfaces: orphan pages (no inbound links — invisible to crawlers traversing the site), inbound/outbound counts per post, and contextual suggestions ranked by shared taxonomy with a boost for orphans, so editors strengthen weak pages first. The suggestion scoring is deliberately explainable — shared categories weigh more than shared tags, orphans get promoted — because an editor who understands why a suggestion appears can judge it; an opaque score just gets ignored.

A subtle correctness detail from a real bug: on sites using plain ?p=123 permalinks, query-string “cleanup” during URL normalization was destroying every internal link in the graph — tracking parameters must be stripped, but permalink-bearing parameters preserved. On affected sites the graph reported every page as an orphan, which reads as “your internal linking is catastrophically broken” when the truth was “the analyzer broke your URLs while reading them.” Silent, site-wide, and found only by tests. The fix distinguishes parameter types: analytics and campaign parameters are noise to strip; content-identifying parameters are the address itself.

Hebrew notes

Keyword matching in Hebrew needs word-boundary logic that respects Unicode (ASCII \b misfires around Hebrew letters), and mixed-direction anchor text inherits all the bidi discipline from Part 2. Tokenization-first design makes both problems tractable because you’re always operating on clean text nodes: boundary detection runs on real words, not on markup fragments, and inserted anchors wrap complete text runs so the bidirectional algorithm has unambiguous material to work with.

Anatomy of a linking rule

The operator-facing unit of the whole engine is the rule, and its shape encodes most of the safety thinking. Each rule carries five decisions: the keyword to match; the target URL it should link to; a per-post limit (how many times this rule may fire on a single post — default once); a case-sensitivity flag (meaningful for Latin keywords, irrelevant for Hebrew, and therefore an explicit per-rule choice rather than a global default); and a cluster label that groups related rules under a topic.

The cluster label is what turns a pile of rules into a SILO. Rules that share a cluster describe one topic neighbourhood — a pillar page and its supporting keywords — and the engine can then reason at the cluster level: suggest cluster structures automatically from the site’s existing categories, report which clusters are thin, and show the operator a topic-shaped view instead of a rule-shaped one. Grouping also keeps the rule list maintainable at scale; a hundred flat rules are unmanageable, but a dozen clusters of eight are an editorial plan.

Two small defaults carry disproportionate weight. The per-post limit defaults to one because the first occurrence of a keyword is nearly always the right link position, and every additional occurrence adds reader annoyance faster than SEO value. And new rules always run through the dry-run first — not as a recommendation but as the interface’s natural flow: the preview button is where the workflow leads, and the apply button lives behind the preview’s results. Interfaces teach habits; this one teaches caution.

Questions to ask any internal-linking tool

If you are evaluating an automated linking product — or reviewing one you built — five questions separate the safe from the dangerous:

1. Does it parse HTML into a tree, or run pattern replacement over raw content?
2. What happens on a page built with Elementor, Divi, Beaver Builder, or Bricks — does it detect and skip, or edit blind?
3. Can you preview every change, per post, before anything is written — and does the preview run the real pipeline?
4. Is there a one-action undo covering everything the tool has ever inserted?
5. What are the link budgets — per keyword, per post — and are they enforced or advisory?

A vendor who cannot answer all five crisply is describing the naive implementation with better marketing.

FAQ

How do I automate internal linking in WordPress safely?

Parse HTML and edit only text nodes, skip page-builder-managed content, cap links per post, preview changes in a dry-run mode, and keep a one-click reversal operation.

What is a SILO structure in SEO?

An internal-linking architecture where topic clusters link hierarchically — pillar pages connected to supporting content — concentrating topical authority and helping crawlers understand site structure.

What are orphan pages?

Published pages with no internal links pointing to them. Crawlers rarely find them, and they waste content investment. Link-graph analysis surfaces them for fixing.

Why do automated links break Elementor pages?

Builders store layouts as serialized JSON or shortcodes; injecting HTML into that data corrupts the structure. Safe tools detect builder content and skip it.

How many internal links should one page have?

There is no fixed number, but automated tools should link each keyword once per page at most, keep totals modest, and prioritize links that help readers — dozens of repeated anchors read as spam.

Can automated internal linking be undone?

Only if the tool was designed for it. Insist on a full reversal operation that strips every link the tool ever inserted — built and tested before the linking feature itself ships.

Previous: Part 17: Building an Accessible, RTL-Ready Admin UI
Next: Part 19: Coexisting With Other SEO Plugins, Gracefully