---
name: docsite-link-sweep
description: >-
  Sweep the googleapis/mcp-toolbox docs for broken and non-canonical links, report each finding with its cause, and apply the safe class of internal link fixes. CI does not check links on this repo, so this skill is the only link check that runs. Use when a maintainer asks for a link sweep or a docs health check, before a release, or after a docs reorg, page rename, or directory move. Example requests: "check the docs for broken links", "link sweep", "fix the dead links in docs/". The skill edits the working tree and makes one commit. It never pushes, never opens a PR, and never rewrites external links or ambiguous targets.
title: docsite-link-sweep
canonical_url: https://skilld.dev/gh/googleapis/mcp-toolbox/docsite-link-sweep
last_updated: 2026-10-15T14:30:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/DEVELOPER.md](https://skilld.dev/api/skills-raw/googleapis/mcp-toolbox/docsite-link-sweep/references/DEVELOPER.md), [references/link-forms.md](https://skilld.dev/api/skills-raw/googleapis/mcp-toolbox/docsite-link-sweep/references/link-forms.md).
>
> If the user asked to install this Skill, run `npx skilld install googleapis/mcp-toolbox/docsite-link-sweep`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/docsite-link-sweep`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/googleapis/mcp-toolbox/docsite-link-sweep) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/docsite-link-sweep`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/docsite-link-sweep --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/docsite-link-sweep --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Docsite Link Sweep (mcp-toolbox)

**No link check runs in CI.** Both link checker workflows are disabled at the GitHub Actions
level, so a broken link now merges without warning and nobody files the weekly report issue.
Run this skill yourself. Nothing else catches these.

The skill drives two tools, and each one misses what the other catches:

- **Lychee** resolves a link as a filesystem path or a network URL. It knows nothing about Hugo.
- **Hugo** resolves a `.md` link to a pretty URL and generates links from shortcodes. It never checks an external URL.

The skill covers the gap. It applies safe mechanical fixes to internal links. It reports external and ambiguous failures for a maintainer to decide.

## Prerequisites

- **Clean git working tree.** Commit or stash docs changes before you start.
- **`lychee`.** Install with `brew install lychee`, or run `docker run --rm -v "$PWD:/input" lycheeverse/lychee`. Lychee is now the only external URL check anywhere in this repo. Without it, run the grep and build passes, then report that external URLs went unchecked.
- **`hugo`**, Extended v0.146.0 or later, for shortcode and build verification.

Default scope is `README.md` and `docs/en/`. Sweep the full scope by default, because no CI pass has covered these files since the workflows went dark. Narrow to the changed markdown files only when the maintainer asks to check one PR.

## References

- [`DEVELOPER.md`](https://skilld.dev/api/skills-raw/googleapis/mcp-toolbox/docsite-link-sweep/references/DEVELOPER.md): canonical link rules. Its "Link Checking and Fixing with Lychee" section says the repo uses lychee for link checks. That claim is stale for CI. The link rules and the `.lycheeignore` guidance in it remain correct.
- [`references/link-forms.md`](https://skilld.dev/api/skills-raw/googleapis/mcp-toolbox/docsite-link-sweep/references/link-forms.md): path-to-URL mapping, version leaks, and Hugo traps.
- [`.lycheeignore`](https://github.com/googleapis/mcp-toolbox/blob/main/.lycheeignore): excluded domains and URLs. The local lychee CLI still reads this file, so it still applies. Every entry must carry a comment.
- [`link_checker.yaml`](https://github.com/googleapis/mcp-toolbox/blob/main/.github/workflows/link_checker.yaml) and [`link_checker_report.yaml`](https://github.com/googleapis/mcp-toolbox/blob/main/.github/workflows/link_checker_report.yaml): both disabled. The YAML still declares a `pull_request` trigger and a weekly `schedule`, so read the workflow state, not the file. Check with `gh api repos/googleapis/mcp-toolbox/actions/workflows`. Treat these files as the reference for flags to reuse, not as a check that runs.

## 1. Detect

Run lychee. Keep the two `--exclude` patterns. `neo4j+` and `bolt://` are database schemes, and lychee cannot fetch them:

```bash
lychee --quiet --no-progress --exclude '^neo4j\+.*' --exclude '^bolt://.*' README.md docs/

# For a PR, limit the scope to changed files:
git diff --name-only --diff-filter=ACMRT origin/main...HEAD -- '*.md'
```

Then grep for the structural problems lychee cannot see:

```bash
# Directory-style links. Hugo resolves these, lychee fails them.
grep -rnE "\]\(\.\.?/[^)]*\)" docs/en --include=*.md | grep -vE "\.md(#[^)]*)?\)"

# Site-absolute links. These leak across versioned deploys.
grep -rnE "\]\(/[^)]*\)" docs/en --include=*.md

# Hardcoded domain URLs.
grep -rn "https://mcp-toolbox.dev/" docs/en --include=*.md

# Section indexes with no `type: docs`. Docsy then renders no child links.
find docs/en -name _index.md \
  -not -path '*/tools/*' -not -path '*/samples/*' -not -path '*/prebuilt-configs/*' \
  -exec grep -L "^type: docs" {} +
```

The three excluded paths hold frontmatter-only wrapper files. `CLAUDE.md` requires them to stay minimal, so they are expected hits and not findings. Without the exclusions this check returns about 58 files instead of 1.

For a deep sweep, build the site and crawl the rendered HTML. This is the only pass that sees shortcode-generated links:

```bash
cd .hugo && hugo --minify --config hugo.cloudflare.toml
lychee --offline --base-url public public
```

## 2. Classify

Fix only safe, unambiguous internal links. Report everything else.

| Category | Action | Criteria |
|---|---|---|
| **Safe to fix** | Rewrite in place to a file-relative `.md` link | • Directory link<br>• Site-absolute `[Text](/path/)`<br>• Hardcoded `https://mcp-toolbox.dev/...`<br>• Moved file with exactly one obvious git successor<br>• Renamed heading anchor |
| **Needs decision** | Report with a recommendation. Do not apply. | • Target is missing or deleted<br>• Several candidate targets after a split or reorg<br>• Link points into an `ignoreFiles` path (see `hugo.toml`)<br>• `_index.md` has no `type: docs` |
| **External** | Report `file:line`, URL, and status | • External URL returns 404, 403, or 500 |
| **Ignore-worthy** | Propose a commented `.lycheeignore` regex | • Endpoint is auth-walled, rate-limited, or flaky |

**Canonical link rule:** use a file-relative path that ends in `.md`, for example `[Example](../folder/file.md)`. Never use a site-absolute `/...` path or a directory `/.../` path.

## 3. Verify

Check every modified file against both checkers:

```bash
lychee --quiet --no-progress --offline <modified-files>
cd .hugo && hugo --environment development
```

## 4. Commit and report

```bash
git checkout -b docs/fix-docsite-links
git commit -am "docs: fix broken docsite links"
```

Stop there. Print the report, then give the maintainer the push and PR commands to run.

## Rules

- **Verify both ways.** Every fix must pass offline `lychee` and `hugo --environment development`.
- **Never guess an external URL.** If an external link is dead, report it. Do not substitute a replacement.
- **Never invent a missing target.** A missing internal page belongs in "Needs your decision".
- **Canonical format only.** Use file-relative `.md`. Never add an internal link to `.lycheeignore`.
- **Propose only.** Never push a branch and never open a PR.

## Output format

```text
## Docsite link sweep: <scope>, <X> findings
Checked: lychee (<status>) | Hugo build (<status>) | <N> files changed

**Fixed and verified** (<count>)
| file:line | was | now | reason |

**Needs your decision** (<count>)
| file:line | target | problem | recommendation |

**External, report only** (<count>)
| file:line | url | status |

**Proposed .lycheeignore entries** (<count>)
| pattern | reason |

**Structural** (<count>)
- <file>: <issue>

**Apply:**
git push -u origin docs/fix-docsite-links
gh pr create --title "docs: fix broken docsite links"
```
