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
```