heddle check --only search-surface
Search Surface Check
The search-surface check records each page's title, H1 and canonical, and fails a build that changes one without the record changing too. Without it, a tidy-up that retitles pages holding page one can cost those rankings, and nobody notices for days. What a search engine ranks a page on, held still unless a change says so.
When Heddle is set up on your site, this check runs on every build alongside 15 others, so a page that fails it is fixed before a buyer or a search engine sees it.
Why it exists
What a search engine ranks a page on, held still unless a change says so.
On the site this came from, one pull request retitled 24 city pages that were holding page one and added a city link to a hub. Two days later the city page that had been #1 for its search had left the top 50, with the hub at #48 in its place.
Every other check passed, because nothing was wrong with any one page. What was missing was a moment where somebody saw that a ranking page's result was about to change.
Two rules:
The surface. Every indexable page's title, H1 and canonical are recorded in heddle/search-surface.json. A build that changes one, drops a page or adds one fails until the record is rewritten (
heddle check <site> --only search-surface --update), which puts the change in the diff where a reviewer sees it. Read the live result before retitling a page that ranks.One owner per local search. A page titled "
in , ST" owns that search. No other page may put the same service and place together in its title or an H1 to H3. Two pages answering one query is how the city page lost to the hub. Linking to the owner is fine.
From lib/checks/search-surface.mjs in the Heddle repository at de0c02b.
Questions
What does the search surface check look for?
Titles, H1s and canonicals against the recorded surface; one page per local search.
Does the search surface check need an AI model?
No. It reads the built pages or the sources directly, so it runs offline and costs nothing per run.
How do I run it?
Build the site, then run node bin/heddle.mjs check <site> --only search-surface from the Heddle repository.
Work with us
Let the agents bring you the leads.
Tell us about your business and who buys from you. On a short call we'll show you the searches your buyers make where you don't show up yet, and what the agents would do about them in their first month.
On the call, for your site
- The searches your buyers makeMeasured, with how many people make each one
- Where you show up, and where you don'tOn Google and in ChatGPT's answers
- The agents' first monthThe pages, fixes and links they would start with