internal-linking · git:20261105.12a3bbd · 2026-11-05 · sha256 021f853d5f550e2b
internal-linking git:20261105.12a3bbdA
Immutable. This exact content never changes and is served at /api/v1/blob/021f853d5f550e2b.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_uhxtqnzhfd5rdmzx/021f853d5f550e2bb69715c7bd0313b68b038c7926a4c5e905aeb0e725c6bd28.json
Then /plugin install internal-linking@markdownregistry-uhxtqnzhfd5rdmzx in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: internal-linking description: Audit internal link counts, anchor text quality, broken same-host links (--check-links), and sitemap-only orphan pages across a site. --- # internal-linking — Internal Linking & Orphan Risk Analysis ## 1. Description & Activation Criteria Activate `internal-linking` when the user wants to: - Audit internal link distribution (`O10-internal`, `O10-internal-many`), replace vague anchor text (`O11-generic-anchors`), find broken internal links (`T16-broken-links`), or identify orphaned pages discovered only via `sitemap.xml`. - Improve crawl depth, topical clustering, and internal PageRank flow. ## 2. Inputs & Prerequisites - **Target**: Live `http(s)` URL or local build directory. - **Recommended flags**: - `--crawl sitemap`: Seeds the crawl from `sitemap.xml` so sitemap-listed pages with zero inbound links from other crawled pages are flagged as `Possibly orphaned pages`. - `--check-links`: Verifies same-host internal link targets (bounded at 100 HTTP checks per run, honoring `robots.txt` and skipping already-audited 200 URLs) to surface `T16-broken-links` (`P1`). ## 3. Step-by-Step Workflow 1. **Run a sitemap-seeded crawl with link verification**: - Execute `npx one-step-seo audit <url> --pages 25 --crawl sitemap --check-links --out ./seo-report`. 2. **Fix broken internal links first (`T16-broken-links`, P1)**: - Inspect `T16-broken-links` evidence in each `report[-N].json` (e.g., `GET https://example.com/gone -> http status 404`) and update or remove dead hrefs. 3. **Eliminate dead-end and orphaned pages (`O10-internal`, `Possibly orphaned pages`)**: - Identify pages where `report.page.internalLinks === 0` (`O10-internal` P1) or `report.page.internalLinks < 2` (surfaced in the site dashboard's `Internal linking & dead-end risk` section) and add contextual outbound internal links to related hub or detail pages. - Inspect `index.md` / `index.html` for sitemap-only orphan pages and link to them from relevant category or pillar pages. 4. **Balance excessive link density (`O10-internal-many`, P2)**: - On pages with `>200` internal links (`O10-internal-many`), trim mega-menu or footer link bloat so primary contextual links carry clearer weight. 5. **Upgrade generic anchor text (`O11-generic-anchors`, P3)**: - Replace repeated exact-match generic anchors (`click here`, `read more`, `learn more`, `here`, `link`, `more`) with descriptive 2–5 word phrases naming the destination topic. ## 4. Tools & CLI Commands ```bash # Multi-page internal link, orphan, and broken-link audit npx one-step-seo audit https://example.com --pages 25 --crawl sitemap --check-links --out ./seo-report # Single-page broken-link and anchor-text check npx one-step-seo page https://example.com/blog/post --check-links --skills internal-linking --out ./seo-report ``` ## 5. Evidence Requirements - Quote `report.page.internalLinks` and `report.page.externalLinks` for each audited page. - Quote the exact broken target URLs and HTTP statuses from `T16-broken-links` evidence. - Quote the exact generic anchor strings flagged by `O11-generic-anchors` and the orphan URLs listed in `index.md`. ## 6. Expected Outputs 1. **Broken Link Remediation List**: Source page -> Broken target URL -> Status code -> Replacement URL. 2. **Orphan & Dead-End Page Map**: Orphaned URLs needing inbound links and dead-end pages needing outbound links. 3. **Anchor Text Upgrades**: Before/after anchor text rewrites. ## 7. Limitations & External Data - **Bounded link budget**: `--check-links` caps verification at `MAX_LINK_CHECKS` (100 same-host requests per run) to remain fast and polite. - **Orphan scope**: Orphan detection is relative to the crawled page set (`--pages` up to 200); a page unlinked from the first N pages may still have links from uncrawled archive pages. ## 8. Safety & Approval Rules - `--check-links` automatically respects `robots.txt` and SSRF IP protections; never manually fetch disallowed or private network targets. ## 9. Examples ```bash # Audit internal links and check up to 100 same-host targets on a documentation site npx one-step-seo audit https://docs.example.com --pages 20 --crawl sitemap --check-links --out ./seo-report ```