GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Absolute links (§5.1) don't resolve correctly in non-OKF-aware renderers
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
§5.1 defines `/`-prefixed links as relative to the bundle root. [link](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/d44368c15e38e7c92481c5992e4f9b5b421a801d/okf/SPEC.md?plain=1#L238-L247). That's a
valid layer on top of markdown — CommonMark specifies link *syntax*, not
resolution — so the files stay valid markdown. The concern is resolution
in any viewer that isn't OKF-aware.
A browser resolves `/tables/customers.md` against the host origin; GitHub
resolves it against the repo root. Neither is the bundle root once the
bundle is nested in a larger repo — which §3 explicitly allows ("a
subdirectory within a larger repository"). In those cases the absolute
links mislink or 404.
This cuts against the zero-tooling portability goal: the *text* is still
readable with `cat`, but the *links* only resolve correctly in an
OKF-aware consumer (or when the bundle happens to sit at the serving
root).
The relative form in §5.2 (`./other.md`) resolves correctly in every
renderer; it only breaks when files move. So §5.1 trades
renderer-portability for move-stability — yet it's the "recommended"
form.
Questions:
- Is this tradeoff intentional?
- Should the spec note that §5.1 links require an OKF-aware resolver, or
recommend §5.2 for bundles meant to be browsed raw?
Contributor guide
Research direction
Read SPEC.md §3 and §5.1–§5.2, including the linked lines 238–247, to understand bundle placement and link-resolution rules. Decide with maintainers whether the renderer-portability tradeoff is intentional; done means the specification clearly documents the resolver requirement or the recommended form for raw browsing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100