docs-navigation-linkinglisted

Fix the dead ends and orphan pages in your docs. Walks the full doc graph to find broken internal links, pages nothing links to, generic anchor text ("click here"), over-deep hierarchies and missing next-step links between related pages. Cross-file — requires the whole graph, not one page.
Docsbook-io/docs-skills · ★ 1 · Data & Documents · score 75

Install: claude install-skill Docsbook-io/docs-skills

# docs-navigation-linking — Navigation and Linking Analysis ## Workflow 1. **Gather the docs** — get the list of pages in scope and read their content. If a semantic/graph search tool over the markdown is available (self-hosted `markdown-lsp`, or a connected Docsbook workspace), prefer it — faster and cheaper than scanning files; otherwise read the files directly with `grep`/`find`. Prioritize Tier 1 pages (quick-start, pricing, auth, install) first. This skill requires the full doc graph — do not run on a single page in isolation. 2. **Build link sets** — extract all `href` values from every page; compare to the full page list to identify orphans and broken links. 3. **Apply checklist** — check internal links, orphan pages, anchor text quality, navigation hierarchy, next steps / cross-references, and external links. 4. **Produce report** — return one JSON issue object per finding, sorted by severity. ## Guardrails - Do not edit any documentation files — surface findings only. - This skill is cross-file: orphan detection requires the full graph. Never run on a single page in isolation. - The root index/home page is expected to have no inbound links from docs — exclude it from orphan detection. - Checking external link validity requires HTTP requests — ask the user before making outbound calls. - Confirm Tier 1 pages with the user before flagging navigation accessibility as medium vs. high severity. ## Inputs This skill needs two things, by whatever means are available: