okf: recommend relative cross-links over absolute (§5.1/§5.2)#165
Open
jeromeetienne wants to merge 1 commit into
Open
okf: recommend relative cross-links over absolute (§5.1/§5.2)#165jeromeetienne wants to merge 1 commit into
jeromeetienne wants to merge 1 commit into
Conversation
SPEC §5.1 recommended /-prefixed absolute (bundle-relative) links, but these only resolve in an OKF-aware consumer. A raw renderer resolves a leading / against its own root (host origin in a browser, repo root on GitHub), which is not the bundle root once the bundle is nested as a subdirectory within a larger repository (allowed by §3), so the links mislink or 404. The reference implementation had already voted against the spec: the agent prompt forbids leading /, and every cross-link in the shipped bundles is relative. This aligns the spec with that reality. - Swap §5.1/§5.2 so relative links are §5.1 and marked recommended. - Reframe absolute links as §5.2, documenting that they require an OKF-aware resolver and the browser/GitHub/nested-subdir failure mode. - Update the §4.3/§4.4 examples to use the recommended relative form.
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
Author
|
i signed the CLA 
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #157
Problem
SPEC §5.1 recommended
/-prefixed absolute (bundle-relative) links, butthese only resolve correctly in an OKF-aware consumer. A raw renderer resolves
a leading
/against its own root — the host origin in a browser, the reporoot on GitHub — which is not the bundle root once the bundle is nested as a
subdirectory within a larger repository (which §3 explicitly allows). In that
case the links mislink or 404, cutting against OKF's zero-tooling portability
goal.
The reference implementation had already voted against the spec on this:
reference_instruction.md) forbids leading/("Never start a link with
/(that breaks GitHub rendering)").bundles/*/concept files is relative.So the spec recommended absolute → the agent forbade absolute → the bundles use
relative. The only thing out of step was the "recommended" label in the spec.
Change
Adopt resolution (1) from the issue — recommend relative links, keep absolute
as a supported OKF-aware-only form:
with the rationale that they resolve in any standard renderer (
cat, browser,GitHub, editor preview) without OKF tooling. Noted drawback: breaks if a
document moves.
OKF-aware resolver and spelling out the browser/GitHub/nested-subdirectory
failure mode.
so the spec's own examples model the guidance.
Spec-text only — no code changes; this aligns the spec with what the reference
agent and bundles already do.