GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: Inline citation as default convention for coupling claims to evidence
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
Adopt inline hyperlinks on claim text (rather than footnote-style Citations sections) as the default citation convention in OKF concept bodies. This couples each claim directly to its supporting evidence, eliminating the mental mapping step between a claim in the body and a citation at the bottom.
## Motivation
OKF's current Citations section is a separate block at the bottom of a concept file. This works for academic citation conventions where a numbered reference list is expected, but it breaks the coupling between a claim and its evidence. A reader (human or agent) encountering a claim must scroll to the bottom, find the citation, and mentally map it back to the claim. For agent consumers, this means an extra parse-and-join step to reconstruct the claim-to-source mapping.
## Proposal
Recommend inline citation as the primary convention. Inline citations SHOULD be placed on the claim text itself: `[the specific claim](url)` rather than `claim text ([source](url))`. The link reads as part of the sentence and the evidence is adjacent to the assertion.
The existing Citations section remains available for:
- Grouped references that support multiple claims
- Sources that are cited indirectly (e.g., see also)
- Bibliographic metadata too long for inline placement
## Relationship to Spec
This does not require a spec change. It is a best-practice convention for body content. Permissive consumers read the body regardless of citation style. Informed consumers can extract citation graphs by parsing inline links instead of cross-referencing a separate section.
## Complementary Mechanism
Inline citations handle claim-level evidence. The proposed SOURCES body section (issue #92) handles file-level provenance between concepts. Together they form a complete evidence chain: every sentence-level claim traces to a URL, and every file-level claim traces to supporting files one layer deeper.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)
Contributor guide
Assessment
This issue has not been assessed yet.