GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

§6.2: what is a leading-slash link relative to?

Open Beginner friendly
#344 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.