GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
§6.2: what is a leading-slash link relative to?
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
§6.2 lists path forms, including:
> a bundle-relative path beginning with `/`
The reference bundles use that form. In `acme_retail`, `policies/returns.md` links to `[tables/orders](/tables/orders.md)`, and the target exists at `/tables/orders.md`.
Reading §6.2 literally, the leading slash means bundle root, so that link resolves and the bundle is internally consistent. That is how we implemented it.
I have also seen the other reading in the wild: the leading slash treated as an ordinary relative path, resolving to `policies/tables/orders.md`, which does not exist and is reported as a dangling link. Under that reading the official sample bundles contain broken links.
Both readings are defensible from the sentence alone, because it names the form without saying what the slash is relative to. One word would settle it, something like:
> a bundle-relative path beginning with `/`, resolved from the bundle root
## Why it is worth settling
- The reference bundles depend on the first reading, so the spec and its own samples disagree under the second.
- It is not confined to samples. `invertase/react-native-firebase` ships an OKF bundle whose index links pages with leading slashes, and it has a large number of readers.
- §11 tells consumers not to reject a bundle for broken cross-links, which softens the consequence but does not remove it: a validator still has to decide what to report, and today two of them report opposite things about the same file.
Happy to send a PR with the clarifying words if that is easier than a discussion.
Contributor guide
Research direction
Start with §6.2 in the specification and compare its wording with the leading-slash links in the acme_retail reference bundle. Confirm that the clarification resolves those links consistently with §11 and that the resulting wording clearly defines the base used for resolution.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100