Auditing metadata.yaml links to Learn

Use this when a generated integration page contains links to learn.netdata.cloud and one of them drifts from the current Learn route.

Why this matters

metadata.yaml is rendered into integration pages on Learn, the website, and the in-app integrations catalog (../SKILL.md:37). A broken Learn URL in metadata therefore becomes a user-visible broken link on multiple surfaces.

Learn routes are not derived from source filenames. They are derived from docs/.map/map.yaml labels and hierarchy, while source-relative /docs/... .md links can be rewritten by Learn ingest (../../learn-site-structure/mapping.md:219). For example, docs/network-flows/visualization/summary-sankey.md is published as /docs/network-flows/visualization/sankey-and-table because the map label is Sankey and Table (docs/.map/map.yaml:515).

Audit command

Extract unique absolute Learn URLs from all metadata files and check their published response:

rg -No "https://learn\\.netdata\\.cloud/docs[^)\\]\\s,\"']+" --glob 'metadata.yaml' . \
  | sed 's/^.*https:/https:/' \
  | sort -u \
  | while read -r url; do
      printf '%s\t' "$url"
      curl -sL -o /dev/null -w '%{http_code}\t%{url_effective}\n' "$url"
    done

For URLs with fragments, also confirm the target anchor exists in the rendered HTML:

curl -A 'Mozilla/5.0' -sL 'https://learn.netdata.cloud/docs/netdata-agent/configuration' \
  | rg 'id="locate-your-config-directory"'

Validate source-relative metadata links locally:

python3 - <<'PY'
import pathlib, re, sys

root = pathlib.Path('.')
pat = re.compile(r'\[[^\]]+\]\(([^)]+)\)')
problems = []

for path in sorted(root.rglob('metadata.yaml')):
    text = path.read_text(errors='replace')
    for match in pat.finditer(text):
        target = match.group(1).strip()
        if target.startswith('/docs/'):
            file = root / target.split('#', 1)[0].lstrip('/')
        elif target.startswith('../') or target.startswith('./'):
            file = (path.parent / target.split('#', 1)[0]).resolve()
        else:
            continue

        if not file.is_file():
            line = text.count('\n', 0, match.start()) + 1
            problems.append((str(path), line, target))

if problems:
    for path, line, target in problems:
        print(f'{path}:{line}: missing linked source file: {target}')
    sys.exit(1)

print('OK: all metadata.yaml /docs and relative markdown links resolve to source files')
PY

Repair rule

• If the link is Markdown text and points to a Netdata source doc, prefer the source-relative /docs/... .md form when the consuming surface supports Learn ingest rewriting.
• If the same metadata is consumed by non-Learn surfaces that do not rewrite source-relative links, keep an absolute https://learn.netdata.cloud/docs/... URL, but derive the slug from docs/.map/map.yaml labels and verify it with curl.
• Do not infer slugs from filenames. Check the map label first, then validate the published URL.

How I figured this out

Files read:

• ../SKILL.md
• ../../learn-site-structure/mapping.md
• docs/.map/map.yaml

Commands run:

• rg -No 'https://learn\.netdata\.cloud/docs...' --glob 'metadata.yaml' .
• curl -sL -o /dev/null -w '%{http_code}\t%{url_effective}\n' <url>
• local source-relative metadata link validation script above.