Support `applies_to` in additional directives/components

[bmorelli25]

Summary

Add custom support for applies_to tags in the following components:

• Tabs
• Dropdowns
• Admonitions

Tabs

Automatically convert a single applies_to badge into a tab title, so users can immediately see which version or platform each tab applies to without expanding it.

Behavior

If the applies_to: prop is not null:

• Set the applies_to text as the tab title
• Add the applies_to badge to the top of the tab content
• Error if a tab title exists

Limitations

• Multiple applies_to tags per tab not supported as tab titles would get too long
• This is a short term fix. Some tabs will need need applies_to tab sections each release which would lead to way too many tabs in the widget.

Syntax

::::{tab-set}
:::{tab-item}
applies_to: stack: beta 9.0`
This is where the content for tab #1 goes.
:::
:::{tab-item}
applies_to: stack: ga 9.1`
This is where the content for tab #2 goes.
:::
:::{tab-item}
applies_to: serverless: ga
This is where the content for tab #3 goes.
:::
::::

Output

Drop downs

Make version/platform context visible in dropdown titles so users can make informed choices before expanding the content.

Behavior

If the applies_to: prop is not null:

• Prepend the text of the applies_to badge to the dropdown title
• Add the applies_to badge to the top of the dropdown content

Limitations

• Multiple applies_to tags per dropdown not supported as titles would get too long

Syntax

:::{dropdown} Rules are failing due to number of alerts
applies_to: stack: all
Dropdown content
:::
:::{dropdown} Rules are failing due to number of alerts
applies_to: eck: all
Dropdown content
:::

Output

Admonitions

Allow authors to add applies_to badges to admonitions so users can quickly identify whether the content is relevant to their deployment environment. Admonitions are a little different from tabs and dropdowns as all context is available to the user without having to click on anything.

Behavior

If the applies_to: prop is not null:

• Add an applies_to badge to the beginning of the admonition
• If type is {admonition}, only add an applies_to badge to the admonition heading. Any regular admonition with applies_to prop info should error.

Syntax

:::{tip}
applies_to: eck: all
This is a tip.
:::

:::{admonition}
applies_to: stack: 9.1
Dense vector fields are always indexed as `int8_hnsw`.
:::

Output

[reakaleek]

Is this already done by #1487?

[bmorelli25]

@KOTungseth do we have design on this yet?

[KOTungseth]

Casper is working on the designs, but has been unable to dedicate the time. His plan is to share what he has next week, but if he's unable to, he'll assign someone else.

[colleenmcginnis]

Does this have to be blocked by design? Can we move forward with this and refine the design later like we talked about a couple weeks ago? Writers are starting to feel the pain of not having these available.

[reakaleek]

I guess we can. How do you imagine this to be displayed for tabs, annotations (what are annotations?) and bullet lists?

Does the inline syntax already suffice for this?

[bmorelli25]

I updated the description of this issue with a starting point for how to handle applies_to in the context of tabs, dropdowns, and admonitions. I'll post in #docs-team for feedback.

[eedugon]

should we consider also stepper in case certain steps of a process are applicable only for certain deployment types?
just to ensure we don't forget about that component ;)

[shainaraskas]

@bmorelli25 I think we have a common use case where an annotation is provided specifically to provide version info, so we would want an experience closer to the tabs or dropdowns in that case.

[bmorelli25]

should we consider also stepper in case certain steps of a process are applicable only for certain deployment types?

Good callout. We might be able to survive with tabs nested within a step for now. The problem with all of the solutions above is that they don't scale as we add more and more version differences with new releases. So it might make sense to wait on stepper until we have a better long-term vision for these components