GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: Expect concept-id in front matter

Open
#85 1 comment 1 reaction 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.