Lint required frontmatter fields #249
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Putting this in draft while I get all docs content to pass the linter in this PR: |
|
Amplify deployment status
|
ptgott
force-pushed
the
paul.gottschling/2025-06-25-lint-frontmatter
branch
from
8282179 to
418bb30
Compare
ptgott
added a commit
to gravitational/teleport
that referenced
this pull request
Jun 25, 2025
We are rolling out standard `product` and `type` frontmatter fields for each docs page, letting us use this metadata to perform operations on pages that fall under a certain type or product. For example, we could generate product-specific landing pages using the `product` field. This change acts in tandem with gravitational/docs-website#249, which lints the frontmatter of each docs page to enforce the `product` and `type` fields. Note that some guides have "Reference" in the title but are really more like conceptual guides, providing information about how aspects of Teleport work instead of a comprehensive reference of possible inputs. Note that this change marks category index pages as having type `other`. It might make sense to add a type for `index`, but this is something we can modify when we need to perform operations on category index pages.
ptgott
added a commit
to gravitational/teleport
that referenced
this pull request
Jul 9, 2025
We are rolling out standard `product` and `type` frontmatter fields for each docs page, letting us use this metadata to perform operations on pages that fall under a certain type or product. For example, we could generate product-specific landing pages using the `product` field. This change acts in tandem with gravitational/docs-website#249, which lints the frontmatter of each docs page to enforce the `product` and `type` fields. Note that some guides have "Reference" in the title but are really more like conceptual guides, providing information about how aspects of Teleport work instead of a comprehensive reference of possible inputs. Note that this change marks category index pages as having type `other`. It might make sense to add a type for `index`, but this is something we can modify when we need to perform operations on category index pages.
Require a `product` field and `type` field. We will use this to ensure that every docs page specifies the Teleport product it belongs to (e.g., Identity Governance) and the kind of guide it is (e.g., how-to guide). We plan to use these fields to create custom views of pages in the docs that match a particular category or combination of categories.
ptgott
added a commit
to gravitational/teleport
that referenced
this pull request
Jul 9, 2025
We are rolling out standard `product` and `type` frontmatter fields for each docs page, letting us use this metadata to perform operations on pages that fall under a certain type or product. For example, we could generate product-specific landing pages using the `product` field. This change acts in tandem with gravitational/docs-website#249, which lints the frontmatter of each docs page to enforce the `product` and `type` fields. Note that some guides have "Reference" in the title but are really more like conceptual guides, providing information about how aspects of Teleport work instead of a comprehensive reference of possible inputs. Note that this change marks category index pages as having type `other`. It might make sense to add a type for `index`, but this is something we can modify when we need to perform operations on category index pages.
ptgott
force-pushed
the
paul.gottschling/2025-06-25-lint-frontmatter
branch
from
26e11fb to
104853d
Compare
- Expect there to be a `labels` frontmatter key with a list of values. One value must be a product name and one value must be a guide type. Arbitrary additional values are allowed.. - Don't allow arbitrary label values: label values must be within an approved list. - Allow guides to omit a product or type label, e.g., if no label is applicable. - Allow multiple label values for product and guide type.
ptgott
force-pushed
the
paul.gottschling/2025-06-25-lint-frontmatter
branch
from
104853d to
7658ee1
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Require a
productfield andtypefield. We will use this to ensure that every docs page specifies the Teleport product it belongs to (e.g., Identity Governance) and the kind of guide it is (e.g., how-to guide). We plan to use these fields to create custom views of pages in the docs that match a particular category or combination of categories.