Index of every page on this site: llms.txt
All skills
googleapis avatar

/docsite-link-sweep

@a5dc5d4
by Google APIsgoogleapis/mcp-toolbox17k stars
1,805
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/googleapis/mcp-toolbox/docsite-link-sweep

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referenceslink-forms.md

≈618 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Link forms, path mapping, and traps

How a docs path becomes a URL in mcp-toolbox, and the link traps that follow from it.

Path to URL mapping

.hugo/hugo.toml mounts ../docs/en as content at the site root, and sets defaultContentLanguageInSubdir = false.

  • A rendered URL contains no /en/ prefix and no /docs/ prefix.
  • URLs are pretty paths. docs/en/integrations/postgres/source.md becomes /integrations/postgres/source/.

Canonical link form

Use a file-relative path that ends in .md, for example [Postgres](../postgres/source.md).

  • Directory style (../postgres/): Hugo resolves it. Lychee fails it.
  • Site-absolute (/integrations/postgres/source/): lychee passes it. It breaks versioned builds.

Why a site-absolute link leaks

Hugo does not prefix a hand-written absolute path with baseURL. The same page deploys to three different roots:

  • A merge to main deploys to https://mcp-toolbox.dev/dev/.
  • A release deploys to https://mcp-toolbox.dev/<version>/.
  • A PR preview deploys to /.

A link such as [CLI](/reference/cli/) always resolves to mcp-toolbox.dev/reference/cli/. It sends the reader out of /dev/ or out of an archived release, and into the latest release.

Shortcode-generated links

Some links exist only in the HTML that Hugo renders:

  • {{< compatible-sources >}}: the sources that support a tool.
  • {{< list-tools >}}: the tools under a source.
  • {{< samples-gallery >}}, {{< list-prebuilt-configs >}}, {{< list-db >}}: directory listings.
  • {{< include >}}, {{< regionInclude >}}: inlined external content.
  • shared_tools frontmatter: injected tool links for a managed database.

To check these links, build the site and crawl public/ with lychee.

Common traps

  • ignoreFiles in hugo.toml. A listed file exists on disk, so lychee passes it. Hugo does not render it, so the live page returns 404.
  • No type: docs. An _index.md without type: docs falls back to the standard Docsy layout, which renders no child page links.
  • Leaf promoted to section. When foo.md becomes foo/_index.md, every old link to foo.md breaks.
  • Two getting-started directories. Both docs/en/getting-started/ and docs/en/documentation/getting-started/ exist. Resolve a relative path against the actual target file.
  • Missing alias. When you rename or move a page, add an aliases: frontmatter entry. Without it, external bookmarks go dead.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill is safe and provides a utility for maintaining documentation links in the googleapis/mcp-toolbox repository. It uses standard tools to identify and fix internal links while ensuring that significant changes or external link failures are reported for human review.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at a5dc5d4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for googleapis/mcp-toolbox/docsite-link-sweep