GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: Expect concept-id in front matter
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
The proposal as written breaks markdown assumptions with respect to absolute links. Markdown editors that are unaware of the larger bundle hierarchy will follow absolute links differently. For the sake of distribution of the bundle into another location or context, and avoiding an entirely new path notation, this is a necessity. However, some mechanism to reacquire the base of the bundle could allow aware markdown readers to follow links without further knowledge of the entire bundle.
Proposal: Add to [4.1 Frontmatter](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md#41-frontmatter) Recommended fields
* 'concept-id' - Full path to this concept file in the bundle, without the '.md'
This author recommends 'concept-id' take precedence above 'title' in recommendation order.
The presence of this field highlights to a markdown reader that it is part of a larger knowledge structure. It also declares the path, which can be backtracked to find the base and thus correctly follow links to other files and concepts.
While this introduces data duplication, and thus introduces potential for falling out of sync, this is no different from link to the file found in '/index.md'. A change in concept id due to file movement demands similar update to both locations. And one could argue something similar to 'concept-id' is necessary to find the '/index.md' to make such update, barring out of channel context information about the bundle.
Compare with frontmatter field 'canonical' proposed in [issue 49](https://github.com/GoogleCloudPlatform/knowledge-catalog/issues/49), which also declares a similar concept id.
Contributor guide
Assessment
This issue has not been assessed yet.