DEV Community

appierun
appierun

Posted on

Audit Internal Link Anchor Text Across Your Sitemap with Python (Standard Library Only): Empty, Generic, URL-as-Text and Reused Anchors, CSV Report

Weak anchor text builds up one template at a time. A blog index ships with "Read more" under every excerpt. A hero banner links to the shop through an image with alt="". Someone pastes a raw URL into a paragraph. Two product pages both say "brew guide" but point at different guides. None of it breaks anything, and none of it shows up in a broken link checker. It just means the words on your links say less than they could, to readers, to screen reader users scanning a list of links, and to search engines.

This post builds an anchor text auditor in Python using only the standard library (urllib, urllib.robotparser, html.parser, xml.etree, csv, collections, concurrent.futures). It reads your sitemap or sitemap index, fetches every page, and extracts every internal <a href> with the name a reader would get: the visible text, the alt of any image inside the link, then aria-label, then title. It flags empty, generic, URL-as-text, overlong and javascript: links, notes which part of the page each link sits in (header, nav, main, aside, footer), and rolls everything up per target page. Two CSVs come out: one row per link, and one row per target page with its inbound anchors and a flag when no link to it says anything descriptive.

Google Search Central's link best practices for Google (showing "Last updated 2025-12-10 UTC"), Chrome for Developers' Lighthouse page Links do not have descriptive text (showing "Last updated 2019-05-02 UTC") and the W3C's Understanding Success Criterion 2.4.4: Link Purpose (In Context) were opened on 18 Nov 2026, and every statement attributed to them below comes from those pages. Appie free-tool descriptions are as of 18 Nov 2026, checked on each tool's page that day.

Disclosure: Appie.run publishes this article. Two free tools mentioned near the end are ours. The script does not depend on them.

Where this fits

This is another script in a small standard-library series. An earlier one found orphan pages by comparing sitemap URLs with internal links, which asks whether a page gets linked at all. This one asks what those links say. Another found images missing alt text; image links overlap with that one, because the alt is the anchor text when an image is the whole link. Same approach throughout: parse what the server returns, report what is there, and leave the judgment to a person.

What the guidance actually says (and what it does not)

What anchor text is for. Google's link page defines anchor text as "the visible text of a link" and says it "tells people and Google something about the page you're linking to." Good anchor text "is descriptive, reasonably concise, and relevant to the page that it's on and to the page it links to." Its bad examples are "Click here," "Read more," "website" and "article." Its tip is a good test for any anchor: "Try reading only the anchor text (out of context) and check if it's specific enough to make sense by itself."

Empty links and fallbacks. The same page calls <a href="https://example.com"></a> "Bad (empty link text)." It says that "As a fallback, Google can use the title attribute as anchor text if the <a> element is for some reason empty," and that "For images as links, Google uses the alt attribute of the img element as anchor text." An image link with alt="" and no text is its example of "empty alt text and empty link text."

Length. Google shows a "weirdly long" anchor next to a "more concise" version and warns against cramming keywords into anchor text, which it notes is covered by its spam policies. Lighthouse's best practices say "Keep descriptions concise. Aim for a few words or a short phrase."

Generic phrases. Lighthouse's link text audit flags this list: "click here", "click this", "go", "here", "this", "start", "right here", "more" and "learn more". It also says "Don't use the page's URL as the link description unless you have a good reason to do so."

Accessibility. WCAG 2.2 Success Criterion 2.4.4, Link Purpose (In Context), is Level A. It asks that "The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context." The Understanding page explains why: assistive technology can give users "a list of links that are on the web page," and link text "that is as meaningful as possible will aid users who want to choose from this list of links."

What none of these pages give is a word limit or a rule that every link to a page must use different words. The script's 12-word limit is my own starting line (--max-words). The "same anchor, different targets" check is a prompt to look, not a rule: two links that both say "brew guide" but go to different pages are confusing in a list of links, which is the WCAG concern, and worth a second look for SEO too. And because WCAG allows link context to explain a link, a "Read more" that sits next to a heading can still pass accessibility review in some setups. The script reports; you decide.

How the audit works

  1. Sitemap URLs. It reads a urlset or a sitemap index (recursively, gzip supported) and keeps every <loc>. robots.txt is respected for page fetches.
  2. Links per page. It parses each page's HTML and collects every <a> that has an href. Markup inside <script>, <style>, <template> and <noscript> is ignored. mailto:, tel:, sms:, data: and same-page #fragment links are skipped, and so are links to other hosts (www. and the bare domain count as the same host).
  3. The name of each link. Visible text and any image alt inside the link come first, which is how Google describes reading anchors. If both are empty, it uses aria-label (common on icon links), and then title (Google's stated fallback). The name_from column records which one was used.
  4. Region. It tracks whether each link sits inside header, nav, main, aside or footer. --skip-regions header,nav,footer drops the boilerplate, so a "More" link in the footer of every page does not drown out the real problems in content.
  5. Roll-ups. After every page is parsed, it groups links by target URL (fragment and trailing slash removed) and by normalized anchor text, which is what the target-level and reuse checks need.

What the script flags

  • empty_anchor: Level: link; Meaning: No text, no image alt, no aria-label, no title; What to check: Add text, or alt on the image inside the link
  • generic_anchor: Level: link; Meaning: Text matches the generic list (Lighthouse's, Google's examples, a few CMS defaults, plus --extra-generic); What to check: Rewrite so it names the destination
  • url_as_anchor: Level: link; Meaning: Text is a URL or a bare domain; What to check: Replace with words, unless the URL itself is the point
  • long_anchor: Level: link; Meaning: More than --max-words words (default 12); What to check: Link the key phrase, not the sentence
  • title_only: Level: link; Meaning: Name came only from title; What to check: Move the words into the link text
  • javascript_href: Level: link; Meaning: href starts with javascript:; What to check: Use a real URL; Google's page lists these as "Not recommended"
  • same_anchor_N_targets: Level: link; Meaning: The same (non-generic) text points at N different pages; What to check: Make each anchor specific to its page
  • no_descriptive_anchor: Level: target; Meaning: Every internal link to this page is empty, generic or a URL; What to check: Add at least one descriptive link from content
  • http_404 / blocked_by_robots / fetch_failed / not_html: Level: page; Meaning: The page itself did not load or is not HTML; What to check: Fix the page or remove it from the sitemap

Two limits to know up front. The script sees only the HTML your server returns, so links and text injected by JavaScript are not in the report; Google's page suggests the URL Inspection Tool for checking rendered anchor text. And it reads aria-label only on the <a> itself, not aria-labelledby or text hidden with CSS, so a link that is fine for screen readers can still show up as empty_anchor and need a manual look.

The script

Save as anchor_text_audit.py. No pip install needed.

#!/usr/bin/env python3
"""Audit internal link anchor text across a sitemap (standard library only).

Reads a sitemap or sitemap index, fetches every page, extracts each internal
<a href> with its accessible text (link text, image alt, aria-label, title),
and flags empty, generic, URL-as-text, overlong and javascript: links. It also
rolls links up per target page to find pages that never get a descriptive
anchor, and anchors that point at more than one page. Writes two CSVs.
"""
import argparse
import collections
import concurrent.futures as cf
import csv
import gzip
import re
import sys
import urllib.error
import urllib.parse
import urllib.request
import urllib.robotparser
import xml.etree.ElementTree as ET
from html.parser import HTMLParser

UA = "anchor-text-audit/1.0 (+https://example.com/bot)"
SKIP_TAGS = {"script", "style", "template", "noscript"}
REGION_TAGS = {"header", "nav", "main", "aside", "footer"}
# Lighthouse's list, plus the generic examples on Google's link best practices page,
# plus a few common CMS defaults. Extend with --extra-generic.
GENERIC = {
    "click here", "click this", "go", "here", "this", "start", "right here", "more",
    "learn more", "read more", "website", "article", "continue reading", "details",
    "link", "this page", "see more", "view more", "find out more", "more info",
}
URL_LIKE = re.compile(r"^(https?://|www\.)\S+$|^[a-z0-9-]+(\.[a-z0-9-]+)+(/\S*)?$", re.I)


def fetch(url, timeout=20):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    try:
        with urllib.request.urlopen(req, timeout=timeout) as r:
            return r.status, r.headers.get("Content-Type", ""), r.read(), r.geturl()
    except urllib.error.HTTPError as e:
        return e.code, "", b"", url
    except Exception as e:  # DNS, timeout, refused
        return None, "", str(e).encode(), url


# ---------- sitemap ----------

def strip_ns(tag):
    return tag.rsplit("}", 1)[-1]


def sitemap_urls(url, seen=None):
    seen = seen if seen is not None else set()
    if url in seen:
        return []
    seen.add(url)
    status, _, body, _ = fetch(url)
    if status != 200:
        raise RuntimeError(f"sitemap {url} returned {status}")
    if body[:2] == b"\x1f\x8b":
        body = gzip.decompress(body)
    root = ET.fromstring(body)
    locs = [e.text.strip() for e in root.iter() if strip_ns(e.tag) == "loc" and e.text]
    if strip_ns(root.tag) == "sitemapindex":
        out = []
        for child in locs:
            out.extend(sitemap_urls(child, seen))
        return out
    return locs


# ---------- URLs ----------

def host_key(netloc):
    netloc = netloc.lower()
    return netloc[4:] if netloc.startswith("www.") else netloc


def normalize(url):
    """Drop the fragment and a trailing slash (except the root) so /a and /a/ match."""
    p = urllib.parse.urlsplit(url)
    path = p.path or "/"
    if len(path) > 1 and path.endswith("/"):
        path = path.rstrip("/")
    return urllib.parse.urlunsplit((p.scheme.lower(), p.netloc.lower(), path, p.query, ""))


# ---------- HTML ----------

class LinkParser(HTMLParser):
    """Collects <a href> elements with their text, image alt, aria-label and title."""

    def __init__(self, base):
        super().__init__(convert_charrefs=True)
        self.base = base
        self.skip = 0
        self.regions = []
        self.stack = []      # open <a> elements (nesting is invalid HTML but happens)
        self.links = []

    def handle_starttag(self, tag, attrs):
        a = {k.lower(): (v or "") for k, v in attrs}
        if tag in SKIP_TAGS:
            self.skip += 1
            return
        if self.skip:
            return
        if tag == "base" and a.get("href"):
            self.base = urllib.parse.urljoin(self.base, a["href"])
        elif tag in REGION_TAGS:
            self.regions.append(tag)
        elif tag == "a" and "href" in a:
            self.stack.append({
                "href": a["href"].strip(),
                "text": [],
                "alt": [],
                "aria": a.get("aria-label", "").strip(),
                "title": a.get("title", "").strip(),
                "region": self.regions[-1] if self.regions else "body",
            })
        elif tag == "img" and self.stack:
            self.stack[-1]["alt"].append(a.get("alt", "").strip())

    def handle_startendtag(self, tag, attrs):
        if tag != "a":  # a self-closed <a/> never gets an end tag
            self.handle_starttag(tag, attrs)

    def handle_endtag(self, tag):
        if tag in SKIP_TAGS and self.skip:
            self.skip -= 1
        elif self.skip:
            return
        elif tag in REGION_TAGS and tag in self.regions:
            while self.regions and self.regions.pop() != tag:
                pass
        elif tag == "a" and self.stack:
            self.links.append(self.stack.pop())

    def handle_data(self, data):
        if not self.skip and self.stack:
            self.stack[-1]["text"].append(data)

    def close(self):
        super().close()
        while self.stack:  # unclosed <a> at end of document
            self.links.append(self.stack.pop())


def accessible_name(link):
    """Return (name, source): visible text and img alt first, then aria-label, then title."""
    text = " ".join(" ".join(link["text"]).split())
    alt = " ".join(x for x in link["alt"] if x)
    visible = " ".join(x for x in (text, alt) if x)
    if visible:
        return visible, "text" if text and not alt else ("img-alt" if not text else "text+img-alt")
    if link["aria"]:
        return link["aria"], "aria-label"
    if link["title"]:
        return link["title"], "title"
    return "", "none"


def clean(name):
    return re.sub(r"[\s\u00a0]+", " ", re.sub(r"[^\w\s./:-]", " ", name)).strip().lower()


def link_flags(name, source, href, max_words, generic):
    flags = []
    low = clean(name)
    if href.lower().startswith("javascript:"):
        flags.append("javascript_href")
    if source == "none":
        flags.append("empty_anchor")
        return flags
    if low in generic:
        flags.append("generic_anchor")
    elif URL_LIKE.match(name.strip()):
        flags.append("url_as_anchor")
    if len(name.split()) > max_words:
        flags.append("long_anchor")
    if source == "title":
        flags.append("title_only")
    return flags


# ---------- main ----------

def audit_page(url, robots, site_host, args, generic):
    if robots and not robots.can_fetch(UA, url):
        return url, "blocked_by_robots", []
    status, ctype, body, final = fetch(url, timeout=args.timeout)
    if status != 200:
        return url, f"http_{status}" if status else "fetch_failed", []
    if "html" not in ctype.lower():
        return url, "not_html", []
    charset = re.search(r"charset=([\w-]+)", ctype)
    html = body.decode(charset.group(1) if charset else "utf-8", errors="replace")
    p = LinkParser(final)
    p.feed(html)
    p.close()
    rows = []
    for link in p.links:
        href = link["href"]
        low = href.lower()
        if not href or href.startswith("#") or low.startswith(("mailto:", "tel:", "sms:", "data:")):
            continue
        name, source = accessible_name(link)
        if low.startswith("javascript:"):
            target = ""
        else:
            absu = urllib.parse.urljoin(p.base, href)
            parts = urllib.parse.urlsplit(absu)
            if parts.scheme not in ("http", "https") or host_key(parts.netloc) != site_host:
                continue  # external link: out of scope here
            target = normalize(absu)
        if link["region"] in args.skip_regions:
            continue
        rows.append({
            "source": normalize(url),
            "target": target,
            "anchor": name,
            "name_from": source,
            "region": link["region"],
            "flags": link_flags(name, source, href, args.max_words, generic),
        })
    return url, "ok", rows


def main():
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("sitemap")
    ap.add_argument("--out", default="anchor_text", help="CSV prefix (default anchor_text)")
    ap.add_argument("--max-words", type=int, default=12, help="flag anchors longer than this")
    ap.add_argument("--skip-regions", default="", help="comma list, e.g. header,nav,footer")
    ap.add_argument("--extra-generic", default="", help="comma list of more generic phrases")
    ap.add_argument("--workers", type=int, default=4)
    ap.add_argument("--timeout", type=int, default=20)
    ap.add_argument("--no-robots", action="store_true")
    args = ap.parse_args()
    args.skip_regions = {x.strip() for x in args.skip_regions.split(",") if x.strip()}
    generic = GENERIC | {clean(x) for x in args.extra_generic.split(",") if x.strip()}

    try:
        urls = list(dict.fromkeys(sitemap_urls(args.sitemap)))
    except Exception as e:
        print(f"could not read sitemap: {e}", file=sys.stderr)
        return 2
    site = urllib.parse.urlsplit(urls[0] if urls else args.sitemap)
    site_host = host_key(site.netloc)
    robots = None
    if not args.no_robots:
        robots = urllib.robotparser.RobotFileParser(f"{site.scheme}://{site.netloc}/robots.txt")
        try:
            robots.read()
        except Exception:
            robots = None
    print(f"{len(urls)} URLs in sitemap")

    page_status, links = {}, []
    with cf.ThreadPoolExecutor(max_workers=args.workers) as ex:
        for url, status, rows in ex.map(lambda u: audit_page(u, robots, site_host, args, generic), urls):
            page_status[url] = status
            links.extend(rows)

    # Anchors reused for different pages (ignore empty and generic ones, flagged already).
    by_anchor = collections.defaultdict(set)
    for r in links:
        if r["target"] and r["anchor"] and not set(r["flags"]) & {"generic_anchor", "empty_anchor"}:
            by_anchor[clean(r["anchor"])].add(r["target"])
    for r in links:
        n = len(by_anchor.get(clean(r["anchor"]), ()))
        if n > 1:
            r["flags"].append(f"same_anchor_{n}_targets")

    # Roll up per target page.
    weak = {"generic_anchor", "empty_anchor", "url_as_anchor"}
    targets = collections.defaultdict(lambda: {"links": 0, "descriptive": 0, "anchors": collections.Counter(), "sources": set()})
    for r in links:
        if not r["target"]:
            continue
        t = targets[r["target"]]
        t["links"] += 1
        t["sources"].add(r["source"])
        t["anchors"][r["anchor"] or "(empty)"] += 1
        if not set(r["flags"]) & weak:
            t["descriptive"] += 1

    with open(f"{args.out}_links.csv", "w", newline="") as f:
        w = csv.writer(f)
        w.writerow(["source", "target", "anchor", "name_from", "region", "flags"])
        for r in sorted(links, key=lambda r: (r["source"], r["target"])):
            w.writerow([r["source"], r["target"], r["anchor"], r["name_from"], r["region"], " ".join(r["flags"])])

    target_flags = {}
    with open(f"{args.out}_targets.csv", "w", newline="") as f:
        w = csv.writer(f)
        w.writerow(["target", "inbound_links", "linking_pages", "descriptive_links", "distinct_anchors", "top_anchors", "flags"])
        for url in sorted(targets):
            t = targets[url]
            fl = ["no_descriptive_anchor"] if t["descriptive"] == 0 else []
            target_flags[url] = fl
            top = "; ".join(f"{a} ({c})" for a, c in t["anchors"].most_common(4))
            w.writerow([url, t["links"], len(t["sources"]), t["descriptive"], len(t["anchors"]), top, " ".join(fl)])

    counts = collections.Counter("same_anchor" if fl.startswith("same_anchor_") else fl
                                 for r in links for fl in r["flags"])
    flagged_links = sum(1 for r in links if r["flags"])
    print(f"{sum(1 for s in page_status.values() if s == 'ok')} pages parsed, {len(links)} internal links, "
          f"{len(targets)} target URLs")
    for url, s in sorted(page_status.items()):
        if s != "ok":
            print(f"  page {s}: {url}")
    print("link flags:")
    for k in ("empty_anchor", "generic_anchor", "url_as_anchor", "long_anchor", "title_only",
              "javascript_href", "same_anchor"):
        if counts.get(k):
            print(f"  {k:<16} {counts[k]}")
    nd = [u for u, fl in target_flags.items() if fl]
    print(f"targets with no descriptive anchor: {len(nd)}")
    for u in nd:
        print(f"  {u}  <- {targets[u]['anchors'].most_common()}")
    print(f"CSV written to {args.out}_links.csv ({len(links)} rows) and {args.out}_targets.csv ({len(targets)} rows)")
    bad_pages = any(s != "ok" for s in page_status.values())
    return 1 if (flagged_links or nd or bad_pages) else 0


if __name__ == "__main__":
    sys.exit(main())
Enter fullscreen mode Exit fullscreen mode

A few implementation notes:

  • Why visible text before aria-label. For screen readers, aria-label usually replaces the visible text. For search, Google describes using the text between the tags. The script reports what a reader sees first and only falls back to aria-label when there is nothing visible, so an icon link with aria-label="Cart" is fine and a text link with a misleading aria-label is left for you to spot in the CSV.
  • Why the generic check uses exact matches. "Read more" is generic; "Read more about grind size" is not. Matching whole anchors after stripping punctuation keeps false positives down. Add your own CMS's defaults with --extra-generic "view post,keep reading".
  • Why no_descriptive_anchor matters more than any single link. One "Read more" is not a problem if three other links to the same page say "grind size guide." A page where every inbound link is "Read more" or an empty image is the case worth fixing first.
  • External links are out of scope. They are filtered by host. Point the generic check at them by removing the host comparison if you want both.

Testing it against a local fixture

I built a small site for a made-up coffee roaster, "Fernhill," with one sitemap of 16 URLs. Every page has the same header (a logo image link with alt text, a nav with Shop, Subscriptions, Blog, About and an icon-only cart link with aria-label="Cart") and the same footer (an "About" link labelled "More," a Wholesale link and a mailto: link). The planted problems:

  • Home page: three "Read more" links under blog excerpts, a hero image link to the shop with alt="", an empty link to subscriptions that has only a title, a raw URL as the link text for the wholesale page, and a <noscript> copy of a "click here" link to check it is ignored.
  • Product pages: one links to the pour-over guide as "brew guide" and the other links to the French press guide as "brew guide." One also has a "here" link and the other a javascript: link.
  • Blog post: a "click here" link, and a 26-word link that wraps a whole sentence.
  • Cold brew guide: linked only from a "Read more" and from an image with alt="".
  • Sitemap: /drafts/holiday-blend is disallowed in robots.txt, and /old-menu returns 404.

The fixture is served by a small handler that maps clean URLs to .html files:

"""Serve ./site with clean URLs (/shop -> site/shop.html) on port 8765."""
import functools
import http.server
import os


class Handler(http.server.SimpleHTTPRequestHandler):
    def translate_path(self, path):
        path = path.split("?")[0].split("#")[0].rstrip("/") or "/"
        if path == "/":
            path = "/index.html"
        elif not os.path.splitext(path)[1]:
            path += ".html"
        return super().translate_path(path)

    def log_message(self, *a):
        pass


http.server.ThreadingHTTPServer(("127.0.0.1", 8765),
                                functools.partial(Handler, directory="site")).serve_forever()
Enter fullscreen mode Exit fullscreen mode

First run, everything included:

$ python3 anchor_text_audit.py http://localhost:8765/sitemap.xml --out anchor_text
16 URLs in sitemap
14 pages parsed, 136 internal links, 15 target URLs
  page blocked_by_robots: http://localhost:8765/drafts/holiday-blend
  page http_404: http://localhost:8765/old-menu
link flags:
  empty_anchor     2
  generic_anchor   21
  url_as_anchor    1
  long_anchor      1
  title_only       1
  javascript_href  1
  same_anchor      2
targets with no descriptive anchor: 1
  http://localhost:8765/guides/cold-brew  <- [('(empty)', 1), ('Read more', 1)]
CSV written to anchor_text_links.csv (136 rows) and anchor_text_targets.csv (15 rows)
exit code: 1
Enter fullscreen mode Exit fullscreen mode

The 21 generic anchors are mostly the footer's "More" link, which appears on all 14 pages that loaded. That is a real problem (fixing one template fixes 14 links), but it hides the content problems. Second run, header, nav and footer skipped:

$ python3 anchor_text_audit.py http://localhost:8765/sitemap.xml --out anchor_text_main --skip-regions header,nav,footer
16 URLs in sitemap
14 pages parsed, 24 internal links, 11 target URLs
  page blocked_by_robots: http://localhost:8765/drafts/holiday-blend
  page http_404: http://localhost:8765/old-menu
link flags:
  empty_anchor     2
  generic_anchor   7
  url_as_anchor    1
  long_anchor      1
  title_only       1
  javascript_href  1
  same_anchor      2
targets with no descriptive anchor: 2
  http://localhost:8765/guides/cold-brew  <- [('(empty)', 1), ('Read more', 1)]
  http://localhost:8765/wholesale  <- [('http://localhost:8765/wholesale', 1)]
CSV written to anchor_text_main_links.csv (24 rows) and anchor_text_main_targets.csv (11 rows)
exit code: 1
Enter fullscreen mode Exit fullscreen mode

Note the new target in the second run. /wholesale has a descriptive "Wholesale" link in the footer, so the first run does not flag it, but the only link to it from content is a raw URL. Whether that matters depends on whether you count footer links; the two runs together show both views.

Here are the flagged rows from anchor_text_main_links.csv (host trimmed, long anchor shortened):

source,target,anchor,name_from,region,flags
/,/blog/choosing-green-beans,Read more,text,main,generic_anchor
/,/blog/grind-size,Read more,text,main,generic_anchor
/,/blog/water-for-coffee,Read more,text,main,generic_anchor
/,/shop,,none,main,empty_anchor
/,/subscriptions,Coffee subscription plans,title,main,title_only
/,/wholesale,http://localhost:8765/wholesale,text,main,url_as_anchor
/blog/choosing-green-beans,/guides/pour-over,click here,text,main,generic_anchor
/blog/choosing-green-beans,/subscriptions,subscribers to our four-weekly plan will get first access to...,text,main,long_anchor
/blog/grind-size,/guides/cold-brew,Read more,text,main,generic_anchor
/shop/colombia-huila,,Bag sizes,text,main,javascript_href
/shop/colombia-huila,/guides/french-press,brew guide,text,main,same_anchor_2_targets
/shop/ethiopia-guji,/guides/french-press,here,text,main,generic_anchor
/shop/ethiopia-guji,/guides/pour-over,brew guide,text,main,same_anchor_2_targets
/subscriptions,/guides/cold-brew,,none,main,empty_anchor
/subscriptions,/guides/french-press,Learn more,text,main,generic_anchor
Enter fullscreen mode Exit fullscreen mode

Every planted problem is there, and the <noscript> copy, the mailto: link and the icon cart link are not.

After fixing the fixture

fix_fixture.py rewrote the anchors (for example "Read more" became the post title, the hero image got alt="Shop this week's coffees", "brew guide" became "pour-over brew guide" and "French press guide," the long link was cut to "four-weekly coffee subscription," and the footer "More" became "About us"), replaced the javascript: link with a real page, and removed the 404 and the blocked draft from the sitemap. Rerun:

$ python3 anchor_text_audit.py http://localhost:8765/sitemap.xml --out anchor_text_after
14 URLs in sitemap
14 pages parsed, 136 internal links, 16 target URLs
link flags:
targets with no descriptive anchor: 0
CSV written to anchor_text_after_links.csv (136 rows) and anchor_text_after_targets.csv (16 rows)
exit code: 0
Enter fullscreen mode Exit fullscreen mode

Exit code 0, so this is the state you could hold a site to in CI.

Running it on your own sitemap

python3 anchor_text_audit.py https://example.com/sitemap.xml --workers 2 --out anchor_text
python3 anchor_text_audit.py https://example.com/sitemap.xml --workers 2 --skip-regions header,nav,footer --out anchor_text_main
Enter fullscreen mode Exit fullscreen mode

Options worth knowing:

  • --skip-regions takes any of header,nav,main,aside,footer. Run once with and once without; template problems and content problems need different fixes.
  • --max-words 8 is stricter on length. Card layouts that wrap a title and a description in one <a> will trip long_anchor on every card; that is a template fix, not a content one.
  • --extra-generic "view post,keep reading,more details" adds your theme's defaults to the list.
  • --workers 2 keeps the load polite on production. Every page in the sitemap is fetched once.

Open anchor_text_targets.csv first and filter flags for no_descriptive_anchor. Then sort anchor_text_links.csv by flags and region. Rows that repeat across every page are template fixes; rows on one page are editorial fixes.

If you want to check the sitemap or link list before running the audit, two free tools on our site can help. The Sitemap URL Extractor takes pasted sitemap XML or a sitemap URL and returns one URL per line from urlset loc tags; for a sitemap index it lists the child sitemap locations. The Website URL Extractor collects same-host links from up to 80 HTML pages, or until 12 seconds pass, and skips a host whose robots.txt disallows all crawling. Both ask for a captcha before each run. Neither looks at anchor text; that is what the script is for.

Fixing what it finds

  1. Start with no_descriptive_anchor targets. Add one descriptive link from a relevant content page. That single change fixes the page-level problem even if the "Read more" links stay.
  2. Then template-level generic_anchor rows. A "Read more" under every blog excerpt is one template change. Use the post title as the link, or add the title to the link text.
  3. Fix empty_anchor image links. Give the image an alt that describes the destination, not just the picture. Google's example is alt="add enchiladas to your cart".
  4. Replace url_as_anchor and title_only. Put real words between the tags.
  5. Make reused anchors specific. If "brew guide" goes to two pages, name both guides.
  6. Shorten long_anchor links to the phrase that names the destination, and keep the rest of the sentence as plain text. Google's page also warns against chaining links next to each other with no text between them.
  7. Rerun and diff. Keep each CSV, so a theme update that brings back "Read more" shows up the next week.

Extending it

  • Read aria-labelledby. Resolve the referenced IDs after parsing, so accessible names match what screen readers announce.
  • Capture surrounding text. Store the 15 words around each link, so you can judge "Read more" next to a heading differently from a bare one, as WCAG allows.
  • Compare anchors with the target's title. Fetching each target's <title> and <h1> lets you flag anchors that share no words with the page they point to.
  • Fail CI on regressions only. Compare flag counts per template with the last run and fail when they grow.

FAQ

Is "Read more" bad for SEO?
Google's link best practices list "Read more" as a "too generic" example and recommend anchor text that is descriptive and makes sense out of context. One generic link is not a disaster, but a page whose every inbound link is generic gives readers and Google little to go on.

Does Google use image alt text as anchor text?
Yes. Google's link page says "For images as links, Google uses the alt attribute of the img element as anchor text," so an image link with empty alt and no text has no anchor text at all.

Should I count header and footer links?
Run it both ways. Template links appear on every page and can hide content problems, but a generic footer link is still repeated site-wide, so it is often the cheapest fix of all.

What is a good length for anchor text?
None of the pages cited give a number. Lighthouse says aim for "a few words or a short phrase," and the script's default of 12 words is a starting line you can change with --max-words.

Can I run it in CI?
Yes. It exits 1 when any link, target or page is flagged, 0 when clean and 2 when the sitemap cannot be read. Run it against staging with the options you settled on.

Wrap-up

Anchor text is one of the few on-page signals you can audit from a sitemap with nothing but the HTML. Parse every link, work out the words a reader would get, flag the empty, generic and URL-only ones, and then look at each target page as a whole: does anything that links to it say what it is? Fix the templates first, then the pages nothing describes, and rerun after every theme change.

RG, Founder, Appie.run

Top comments (0)