GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

[Question] Weird use of headings

Open
#246 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

I’m a bit confused about how headings are used in OKF:

* Why use the `title` frontmatter field instead of just treating the first-level heading as such?
* What’s up with multiple first-level headings (`#`) in the same file? Those should be second-level (`##`).

The first-level heading is supposed to be unique and contain the document’s display name (as opposed to the file name, which is typically a shorter identifier and often in snake case or kebab case).

Contributor guide

Open the contributing guide

Research direction

Review the repository's existing OKF files and their title frontmatter and heading structure to determine the documented convention. Compare files containing multiple first-level headings, then document or clarify whether the first-level heading must be unique and how display names should relate to filenames.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.