onpage-optimization · diff
git:20261105.f7f8170 to git:20261105.12a3bbd
7 added, 7 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: onpage-optimization
description: Audit and optimize page titles, meta descriptions, H1-H6 heading hierarchies, image alt text and dimensions, favicon, and Open Graph / Twitter social cards.
---
# onpage-optimization — On-Page Metadata & Heading Optimization
## 1. Description & Activation Criteria
Activate `onpage-optimization` when the user wants to:
- Audit or improve `<title>`, `<meta name="description">`, `<h1>`–`<h6>` structure, image `alt` and `width`/`height` attributes, favicons, and Open Graph / Twitter social sharing tags.
- Fix snippet truncation, missing metadata, skipped heading levels (`O04-headings`), empty headings (`O04-heading-empty`), or H1-to-title topical drift (`O03-h1-drift`).
- Run a focused on-page audit via `--skills onpage-seo` (or alias `--skills onpage-optimization`).
## 2. Inputs & Prerequisites
- **Target**: URL, local `.html` file, or build directory.
- **Calibrated thresholds (`lib/checks.mjs` -> `THRESHOLDS`)**:
- - `<title>`: `30–65` characters (`O01-title-missing` P0, `O01-title-short` P2, `O01-title-long` P2).
- - `<meta name="description">`: `70–165` characters (`O02-meta-missing` P1, `O02-meta-short` P2, `O02-meta-long` P2).
+ - `<title>`: `30–60` characters (`O01-title-missing` P0, `O01-title-short` P2, `O01-title-long` P2).
+ - `<meta name="description">`: `120–155` characters (`O02-meta-missing` P1, `O02-meta-short` P2, `O02-meta-long` P2).
- `<h1>`: Exactly 1 per page (`O03-h1-missing` P1, `O03-h1-multi` P1) sharing key terms with `<title>` (`O03-h1-drift` P3).
## 3. Step-by-Step Workflow
1. **Run an on-page and accessibility audit**:
- Execute `npx one-step-seo page <target> --skills onpage-seo,accessibility-ux --out ./seo-report`.
2. **Inspect document identity (`O01`, `O02`, `O03`)**:
- - Check `report.page.title` (`titleLength`), `report.page.metaDescription` (`metaDescriptionLength`), and `report.page.h1`.
+ - Check `report.page.title` (`report.page.title.length`), `report.page.metaDescription` (`report.page.metaDescription.length`), and `report.page.h1`.
- Ensure `<title>` and `<h1>` share at least one substantive keyword token so `O03-h1-drift` passes and users see a consistent headline after clicking from search results.
3. **Audit heading hierarchy (`O04-headings`, `O04-heading-empty`, `O05-h2`)**:
- - Verify headings never skip levels (e.g., `<h1>` directly to `<h3>`), contain visible text (`O04-heading-empty`), and divide pages of 300+ words with `<h2>` subheadings (`O05-h2`).
+ - Verify headings never skip levels (e.g., `<h1>` directly to `<h3>`), contain visible text (`O04-heading-empty`), and divide pages of 600+ words with `<h2>` subheadings (`O05-h2`).
4. **Verify image and social metadata (`O08-alt`, `O09-img-dims`, `O06-og`, `O07-favicon`, `W01-social`, `W02-og-url`)**:
- Confirm every informative `<img>` has descriptive `alt` text (`alt=""` is valid only for decorative images) and explicit `width` + `height` attributes (`O09-img-dims`) to prevent Cumulative Layout Shift (CLS).
- Check `og:title`, `og:description`, `og:image`, `og:url`, and `twitter:card`.
5. **Draft or preview fixes**:
- For local files with missing tags, preview additive fixes with `npx one-step-seo fix <file> --only title,description,og,og-url,twitter-card,favicon`.
## 4. Tools & CLI Commands
```bash
# Audit on-page SEO and accessibility rules
npx one-step-seo page https://example.com --skills onpage-optimization,accessibility-ux --out ./seo-report
# Preview local metadata fixes without modifying files
npx one-step-seo fix ./dist/index.html --url https://example.com/ --lang en
```
## 5. Evidence Requirements
- - Quote the exact current `<title>` and its character count (`page.titleLength`), current `<meta name="description">` and its character count (`page.metaDescriptionLength`), and all `<h1>` texts (`page.h1`).
+ - Quote the exact current `<title>` and its character count (`report.page.title` and `report.page.title.length`, or `O01-*` evidence), current `<meta name="description">` and its character count (`report.page.metaDescription` and `report.page.metaDescription.length`, or `O02-*` evidence), and all `<h1>` texts (`report.page.h1`).
- Quote the exact count of images missing `alt` or `width`/`height` from `O08-alt` and `O09-img-dims` evidence.
## 6. Expected Outputs
- 1. **Current vs Recommended Metadata Table**: Current value, character count, issue ID, and proposed replacement within calibrated character ranges (`30–65` chars for title, `70–165` chars for meta description).
+ 1. **Current vs Recommended Metadata Table**: Current value, character count, issue ID, and proposed replacement within calibrated character ranges (`30–60` chars for title, `120–155` chars for meta description).
2. **Heading Outline Audit**: Current H1–H6 progression and fixes for skipped or empty headings.
3. **Image & Social Tag Checklist**: Missing `alt`, `width`/`height`, Open Graph, and Twitter card snippets.
## 7. Limitations & External Data
- - **Automated CLI checks**: Title/meta presence and length, H1 count and title overlap, heading level sequence, empty headings, H2 presence on 300+ word pages, image `alt` and `width`/`height` attributes, favicon link, Open Graph, and Twitter card tags.
+ - **Automated CLI checks**: Title/meta presence and length, H1 count and title overlap, heading level sequence, empty headings, H2 presence on 600+ word pages, image `alt` and `width`/`height` attributes, favicon link, Open Graph, and Twitter card tags.
- **Advisory / manual judgment**: Writing compelling copy or describing specific image contents (`O08-alt`) requires human or agent inspection of the page subject and image asset.
- **External data**: Live SERP pixel-width truncation and click-through rate (CTR) experiments require Google Search Console Performance data.
## 8. Safety & Approval Rules
- Never auto-populate `alt` text with filenames or keyword-stuffed strings; describe the actual image content or use `alt=""` if purely decorative.
- Never overwrite existing `<title>` or `<meta name="description">` tags without showing the user the proposed copy first.
## 9. Examples
```bash
# Run on-page optimization checks on a local HTML file
npx one-step-seo page ./dist/pricing.html --skills onpage-optimization --offline --out ./seo-report
```