Resources · Internal linking

Rewrite internal links with clarity, not keyword pressure.

Use the anchor scanner and replacement assistant to find over-optimized link text, then revise it so readers and search engines can understand the destination before they click.

A safe editorial process

Scan, review, then improve.

The tools are intentionally conservative. Detection is automatic, but the final wording decision belongs to a human editor who understands the article and the destination page.

1. Scan

Run the read-only scanner against the Markdown export or content directory. It reports the file, line, destination, suspicion score, and reasons for the flag.

2. Review

Check whether the destination is informational, commercial-investigation, or transactional. The anchor should accurately predict what the visitor will find after clicking.

3. Apply carefully

Use the companion rewriter only after review. It creates timestamped backups before changing a file, so the edit can be reversed.

Read-only scan

Find suspicious anchors

The scanner checks Markdown, reference-style Markdown, and inline HTML links. It does not edit content.

python3 tools/scan_keyword_stuffed_anchors.py content

# Save a review report
python3 tools/scan_keyword_stuffed_anchors.py content \
  --json /tmp/anchor-scan.json

Suggestion assistant

Review before applying

Suggestion mode is the default. When you deliberately apply changes, the script creates timestamped backups unless you explicitly disable them.

python3 tools/rewrite_keyword_stuffed_anchors.py content

# Apply only after review
python3 tools/rewrite_keyword_stuffed_anchors.py content \
  --apply --yes

Use --report /tmp/anchor-rewrites.json to save suggestions for review.

Destination-aware wording

Describe the page that actually opens.

A neighborhood guide should sound like a guide. A listings page should invite a search. Avoid using one commercial phrase as the anchor for every destination.

DestinationPreferAvoid as the default
Neighborhood articleExplore the White Eagle neighborhood guideWhite Eagle homes for sale Naperville IL
Neighborhood hubBrowse Naperville neighborhood guidesBest Naperville subdivision listings
Search pageSearch current Naperville homesNaperville real estate
Valuation pageRequest a home valuationBest Naperville real estate agent
Buyer planningUse the buyer planning checklistBuy a home in Naperville
Seller guidanceBrowse seller guidanceSell your Naperville home fast

Editorial checklist

Before you publish a replacement.

  • Would a reader predict the destination correctly from the anchor alone?
  • Does the anchor match informational, commercial-investigation, or transactional intent?
  • Does the surrounding sentence explain why the link is useful?
  • Have you preserved the URL, checked the link, and reviewed the backup before publishing?