add-docs-links

Add Documentation Links to docs.json

When to use

• User wants to add, change, or remove rows in src/docs.json, or fix broken / unreachable catalog links
• User provides a GitHub URL (blob or raw) to register in the catalog — convert blob → raw, pick refs, verify reachability, shape entries, update meta and generated, and run tests
• User asks to update or fix docs.json entries, contribute to the docs catalog, or align with docs.json tests and CI audit

For edits or removals: find the row by path and/or its docs key; update meta / generated; run tests. Same rules as adds: whitelist, unique path, and src/__tests__/docs.json.test.ts (including baseHashes and the Repository Breakdown table when refs change).

Workflow

1. Resolve raw URL and ref

   • Map the link to owner/repo and file path; build raw https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{file}.
   • Prefer the same ref already used in docs.json for that patternfly/<repo> (copy from an existing path).
   • New patternfly/<repo> (or new ref / rh-uxd/<repo>): after you add URLs, open docs.json.test.ts and update expect(baseHashes.size) and the Repository Breakdown table (including the Total row)—do not guess counts from this skill.
   • New ref for an existing repo: resolve SHA (e.g. commits API) or use a stable tag.

2. Whitelist

   • path must match whitelist.urls in src/options.defaults.ts. See reference.md — URL whitelist. Use https only. Do not widen the whitelist in a catalog-only PR.

3. Reachability

   • Response must be 2xx (e.g. curl -sI -o /dev/null -w "%{http_code}" "<url>"). If not, fix ref or path; do not add a dead link.

4. Unique path

   • Each path appears once in the whole file.

5. Placement in docs

   • New top-level key under docs (e.g. "AiHelpers"): append as the last property inside "docs": { … } (after the current last key’s block). Do not insert mid-file by theme or alphabet.
   • New object in an existing key’s array: append to the end of that array unless the user specifies order.
   • Edits: keep the same key and array index unless the user asks to move.