You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/syntax/applies.md
+6-18Lines changed: 6 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,27 +55,15 @@ Both versioned and unversioned products use the same lifecycle tags, but only ve
55
55
56
56
## When and where to use `applies_to`
57
57
58
-
The `applies_to` tag can be added at different levels in the documentation: [page-level](#page-annotations), [section-level](#section-annotations), and [inline](#inline-applies-to). Each level uses slightly different syntax and serves a specific purpose:
59
-
*[Page-level](#page-annotations) tagging is **mandatory** and must be included in the frontmatter. It defines the overall applicability of the page across products, deployments, and environments. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md).
58
+
✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments.
60
59
61
-
When the context differs from what was specified at the page level in a specific section or part of the page, it is appropriate to re-establish it.
60
+
❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes.
62
61
63
-
*[Section-level](#section-annotations) annotation lets you show or hide specific sections of content depending on the target context. This is helpful when only a part of a page varies between products or versions.
64
-
*[Inline tagging](#inline-applies-to) allows fine-grained annotations within paragraphs or definition lists. It’s useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content.
62
+
The `applies_to` metadata can be added at different levels in the documentation:
65
63
66
-
### When to use `applies_to`
67
-
68
-
Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability.
69
-
70
-
Use version tagging when:
71
-
* A feature is introduced (e.g., preview, beta, or ga)
72
-
* A feature is deprecated (e.g., deprecated)
73
-
* A feature is removed (e.g., removed)
74
-
75
-
You don’t need version tagging for:
76
-
* Typos, formatting, or style changes
77
-
* Long-standing features being documented for the first time
78
-
* Content updates that don’t reflect a feature lifecycle change
64
+
*[Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments.
65
+
*[Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions.
66
+
*[Inline](#inline-applies-to) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content.
0 commit comments