docs-builder
Loading

Badge usage and placement

As you continue contributing to documentation and more versions are released, you might have questions about how to integrate applies_to badges in cumulative documentation.

Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs:

  • Pages: Provide signals that a page applies to the reader.
  • Headings: Provide signals about a section’s scope so a user can choose to read or skip it as needed.
  • Lists: Identify features in a list of features that are exclusive to a specific context, or that were introduced in a specific version or comparing differing requirements, limits, and other simple, mirrored facts.
  • Definition lists: Identify settings or options that are exclusive to a specific context, or that were introduced in a specific version.
  • Tabs: Provide two sets of procedures when one or more steps in a process differs between contexts or versions.
  • Admonitions: Draw attention to happy differences and basic clarifications.
  • Sibling pages: When the information is too complex to be addressed with only the other content patterns.

At a high level, you should follow these badge placement principles:

  • Place badges where they're most visible but least disruptive to reading flow
  • Consider scanning patterns - readers often scan for relevant information
  • Ensure badges don't break the natural flow of content
  • Use consistent placement patterns within similar content types
  • Consider visual grouping - readers must naturally associate the badge with its corresponding content, no more, no less

There are more specific guidelines on badge placement to follow when using specific elements.

Page frontmatter

Use applies_to in a page's frontmatter to provide signals that a page applies to the reader.

Warning

Do not use section-level or inline annotations with the page title.

Use section annotations on the next line after a heading when the entire content between that heading and the next heading of the same or higher level is version or product-specific.

For example, on the Observability AI Assistant page, all the content in this section is only applicable to Elastic Stack versions 9.1.0 and later.

Correct use of applies_to with headings
Warning

Do not use inline annotations with headings.

Rendering error when using inline applies_to with headings

Reorganize content as needed so the applies_to badge is relevant to the entire contents of the list item. This could mean distinguishing between deployment types, products, lifecycles, or versions. Placing the badge at the beginning of the list item, allows the reader to scan the list for the item that is relevant to them.

For example, the Alerting and action settings in Kibana page lists how the default value for the xpack.actions.preconfigured.<connector-id>.config.defaultModel setting varies in Serverless/Stack and across versions.

The recommended placement of applies_to badges in definition lists varies based on what part(s) of the list item relate to the badge.

This means using an inline annotation at the end of the same line as the term. For example, on the Kibana Advanced settings page, the entire banners:linkColor option is only available in Elastic Stack 9.1.0 and later.

Correct use of applies_to with definition list item
Warning

Do not put the applies_to badge at the beginning or end of the definition if it relates to the entire contents of the item.

Incorrectly using inline applies_to with a definition list item

This might include labeling just one of multiple paragraphs, or one item in an ordered or unordered list. For example, on the Google Gemini Connector page, the default model is different depending on the deployment type and version of the Elastic Stack. These differences should be called out with their own applies_to badges.

In this example, the applies_to badges should be at the beginning of each list item as described in the guidelines for lists.

Correctly using inline applies_to in a portion of a definition list item

The recommended placement in tables varies based on what part(s) of the table related to the applies_to label.

Add the badge to the end of the first column to indicate that it applies to all cells in a row.

For example, the Streaming Input page includes a table that contains one setting per row and a new setting is added in 9.0.4.

In some cases it might be appropriate to add column dedicated to applicability, but you should avoid adding specific Markdown real estate to the page layout and causing existing tables with content from long before the base version, for example Elastic Stack 9.0.0, look incomplete.

In the same example as above, creating a column dedicated to applicability would likely take up unnecessary space and could cause confusion since the majority of rows include content that has been available long before 9.0.0.

Add the badge to the end of the content in a cell to indicate that it applies to that one cell only.

For example, the Collect application data page includes a table that compares functionality across two methods for collecting APM data, and only one of the methods is in technical preview.

Tip

If the one cell that the badge applies to is in the first column, consider formatting the content using something other than a table (for example, a definition list) to avoid confusion with the previous scenario in which adding the badge to the first column indicates that the badge applies to the whole row.

For example, the Parse AWS VPC Flow Log page includes new information relevant to 9.2.0 and later about a setting that already existed before 9.2.0. In this example, the applies_to badges should be at the beginning of each list item as described in the guidelines for lists.

Tip

If needed, break the contents of the cell into multiple lines using <br> to isolate the content you're labeling or consider not using a table to format the related content.

In the future (elastic/docs-builder#1436), tabs will be able to accept applies_to information. Until then, if an applies_to badge is relevant to the entire tab item, add the badge to the beginning of the content.

In the future (elastic/docs-builder#1436), admonitions will be able to accept applies_to information. Until then, if an applies_to badge is relevant to the entire admonition, add the badge to the beginning of the content.

In the future (elastic/docs-builder#1436), dropdowns will be able to accept applies_to information. Until then, if an applies_to badge is relevant to the entire dropdown, add the badge to the beginning of the content.

To specify applies_to information for a code block, refer to Cumulative docs example scenarios > Code block content varies.

To specify applies_to information for an image, refer to Cumulative docs example scenarios > Screenshots vary.