GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Spec: state that [[wikilinks]] are out of scope and SHOULD be canonicalized to standard markdown links (§5)
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
§5 already says concepts link via **standard markdown links**, absolute (recommended) or relative. That's the right call. But the spec is currently *silent* on the double-square-bracket `[[wikilink]]` syntax, and I think one short clause would prevent a predictable interoperability mess.
**The gap:** OKF explicitly takes inspiration from Obsidian-style vaults and wiki tooling, where `[[wikilinks]]` are the dominant link form. Authors coming from those tools will type `[[…]]` by habit. Because the spec doesn't say whether that's in or out of scope, producers and consumers will quietly disagree about whether to support it — exactly the kind of fragmentation OKF exists to remove.
**Why wikilinks specifically don't fit OKF:** wikilink resolution assumes a *flat, globally-unique* namespace — `[[proposal]]` means "the file/concept named proposal." But OKF deliberately doesn't have that namespace. The hierarchy is producer-defined, `index.md` and `log.md` recur in every directory, and concept titles aren't required to be unique. OKF effectively *encourages duplicate filenames across folders* — so `[[proposal]]` is ambiguous in a way that `/work/a/proposal.md` is not. The very thing that makes wikilinks ergonomic (resolve-by-name) is the thing OKF's structure breaks.
**Proposed addition — a new §5.4, roughly:**
> ### 5.4 Wikilinks are out of scope
>
> OKF links are standard markdown links only (§5.1, §5.2). The `[[wikilink]]` form is **not** part of OKF: because OKF permits the same filename in multiple directories, a name-based `[[target]]` reference cannot be resolved unambiguously.
>
> However, because human authors frequently write `[[…]]` (it is lighter to type and easier to edit), tools SHOULD be lenient on input. A consumer MAY accept `[[…]]` and, where it does, SHOULD **canonicalize** it to a standard markdown link, resolving the target by path. Producers SHOULD emit standard markdown links. A `[[…]]` that cannot be resolved unambiguously SHOULD be surfaced for human disambiguation rather than dropped.
**Spirit of the clause:** *have compassion for humans about links.* People shouldn't be scolded for typing the easy thing; the tooling — and especially the agents — should do the cross-reference bookkeeping *for* them. This is the same observation the OKF blog post leans on (LLMs don't mind the link-bookkeeping that bores people). Accepting human-friendly input and quietly canonicalizing it is precisely where an agent earns its keep.
Glad to send this as a PR against `SPEC.md` if the direction's agreeable (I'll sign the CLA).
---
*Drafted by AI (Claude Code, Opus 4.8) under the direction of Peter Kaminski, who has reviewed it and takes full responsibility for its content.*
Contributor guide
Assessment
This issue has not been assessed yet.