The rule
This is the full text. Your agents read it before they write, and a critique checks the output against it.
name: seo-page-essentials description: Sets the on-page SEO basics one web page must show and checks the rendered HTML of that page for indexability, title, headings, opening content, topic-specific content, structured data shape, meta description, image alt text, links, viewport and language. metadata: version: 0.1.0 output: The rendered HTML of one web page, as it will be served
SEO page essentials
What is checked
The output is the rendered HTML of 1 web page, as it will be served. Judge the HTML alone. The target query, the live URL, speed, Core Web Vitals, backlinks, HTTP headers and the rest of the site are not visible and are not judged. Main content means the text a visitor came to read, not navigation, header, footer or sidebar text.
Settings
A company changes these by editing this file and uploading it as a new version.
- SHOULD_BE_INDEXED: yes. The page is meant to appear in search results. Set to no for pages that must stay out of search, which makes C1 N/A.
- TITLE_MAX_CHARS: 60 characters. The display guide for the title. Over this is a note.
- TITLE_FAIL_CHARS: 70 characters. Over this the title fails.
- META_MAX_CHARS: 160 characters. The display guide for the meta description.
- GENERIC_TITLES: "Home", "Untitled", "Welcome", "New page", "Page title", "Document". Titles that name no topic.
- VAGUE_LINK_TEXT: "click here", "here", "read more", "learn more", "more", "link", "this page". Link text that does not say where the link goes.
- PLACEHOLDER_HREFS: "#", "javascript:void(0)", "javascript:;", and an empty href. Links that go nowhere.
Rule
- Indexable as intended
- No robots meta tag says noindex, for example <meta name="robots" content="noindex">.
- A link rel="canonical" is present and its href is an absolute URL, for example https://example.com/guides/compost, not /guides/compost.
- Title
- Exactly 1 title element.
- The title names the page's topic. "Home" or a brand name alone does not.
- The title is at most TITLE_FAIL_CHARS characters, and at most TITLE_MAX_CHARS to avoid a note.
- Headings
- Exactly 1 h1, and it states the page's topic.
- Heading levels step down 1 at a time: h2 then h3, never h2 then h4.
- Heading elements mark sections, not styled text such as a price or a tagline.
- Opening and wording
- The first paragraph after the h1 says what the page offers or answers.
- Topic terms read naturally. The same phrase repeated for its own sake is stuffing.
- Content specific to the topic
- Main content is specific to the page's topic, not filler that could sit on any page.
- Structured data
- Any JSON-LD block is valid JSON and uses a schema.org type that fits the page.
- Meta description, images, links, mobile and language (notes only)
- A meta description is present, reads as a sentence or two, and is within META_MAX_CHARS.
- Images that carry meaning have alt text that describes them. Decorative images have alt="".
- Link text says where the link goes, and no navigation link has a placeholder href.
- A viewport meta tag is present and the html element has a lang attribute.
Checks
Each check gets Pass, Fail, Not covered or N/A. Not covered means the output does not show enough to decide, and it never counts as Pass. If a check requires the output to contain something and it does not, that is Fail, not Not covered. Use N/A only when a check cannot apply, and say why. Quote the HTML in every finding.
C1. No noindex (blocker) Fail if a robots meta tag contains "noindex", for example <meta name="robots" content="noindex, follow">. N/A when SHOULD_BE_INDEXED is no.
C2. Canonical present (blocker) Fail if there is no link element with rel="canonical".
C3. Canonical absolute (blocker) Fail if the canonical href does not start with http:// or https://, for example href="/pricing". N/A when there is no canonical.
C4. Title present (major) Fail if there is no title element.
C5. One title (major) Fail if there is more than 1 title element.
C6. Title names the topic (major) Fail if the title text names no topic, for example a title in GENERIC_TITLES or a brand name alone such as "Acme".
C7. Title within hard limit (major) Fail if the title text has more than TITLE_FAIL_CHARS characters.
C8. H1 present (major) Fail if there is no h1 element.
C9. One H1 (major) Fail if there is more than 1 h1 element.
C10. H1 states the topic (major) Fail if the h1 text does not state the page's topic, for example "Welcome" or "Overview".
C11. Heading levels in order (major) Fail if any heading is followed by a heading more than 1 level deeper, for example an h2 followed by an h4 with no h3 between.
C12. Headings mark sections (major) Fail if a heading element wraps text that is not a section heading, for example a price, a button label or a tagline placed in an h3 for its size.
C13. Opening paragraph says what the page offers (major) Fail if the first paragraph after the h1 does not say what the page offers or answers, for example a paragraph that only greets the reader or describes the company.
C14. No keyword stuffing (major) Fail if a topic term or phrase is repeated so often that the text reads unnaturally, for example the same phrase 3 times in 1 sentence or a run of variants such as "cheap flights, cheapest flights, cheap flight deals".
C15. Content specific to the topic (major) Fail if the main content is generic filler that could sit on a page about any topic, for example "We provide high quality solutions tailored to your needs."
C16. JSON-LD parses (major) Fail if a script element with type="application/ld+json" does not contain valid JSON, for example a trailing comma or an unclosed brace. N/A when the page has no JSON-LD.
C17. Schema type fits the page (major) Fail if the @type in the JSON-LD does not fit the page, for example Product on a blog article or FAQPage on a page with no questions. N/A when the page has no JSON-LD.
C18. Meta description present (minor) Flag if there is no meta element with name="description".
C19. Meta description is a summary (minor) Flag if the meta description content is a list of terms rather than a sentence or two, for example "shoes, running shoes, trail shoes, buy shoes".
C20. Meta description length (minor) Flag if the meta description content has more than META_MAX_CHARS characters.
C21. Title length guide (minor) Flag if the title text has more than TITLE_MAX_CHARS characters.
C22. Meaningful images described (minor) Flag if an img that carries meaning has no alt attribute, an empty alt, or alt text that does not describe it, for example alt="IMG_2041.jpg" or alt="image".
C23. Decorative images silent (minor) Flag if a decorative img, such as a divider or background flourish, has alt text other than alt="".
C24. Link text says where it goes (minor) Flag if a link's text is in VAGUE_LINK_TEXT or otherwise does not say where the link goes.
C25. No placeholder links (minor) Flag if a link meant to navigate has an href in PLACEHOLDER_HREFS or no href at all.
C26. Viewport present (minor) Flag if there is no meta element with name="viewport".
C27. Language declared (minor) Flag if the html element has no lang attribute.
Result
- Fail if any blocker or major check is Fail or Not covered.
- Otherwise Pass. Minor checks never cause Fail.
