Add support for context-specific admonitions

[lcawl]

Relates to #49, https://github.com/elastic/docs-builder-example/blob/main/docs/source/markup/admonitions.md

In order to support versioning in the new docs system, we need to add some built-in admonitions or "directives" that are context-specific and can be applied at the section, paragraph, or line-level.

In the existing doc system, they look like this:

However this is insufficient for features have varied states across multiple contexts. For example something can be GA in one context but tech preview in another.

In the new doc system, we should have a way to accomplish something like this:

You can see an example of how we played with extending the admonitions in the old system to accomplish this in elastic/docs#3121

Similar to the page-level metadata, we think that that admonitions need to communicate the following dimensions:

• Deployment type. For example:
  • Elastic Cloud Hosted
  • Elastic Cloud Serverless
  • Elastic Cloud Enterprise
  • Elastic Cloud Kubernetes
  • Self-managed (need to confirm the terminology for this Elastic Stack on-prem self-managed context)
• Availability / product stage
  • technical preview (exists in current docs system per https://github.com/elastic/docs?tab=readme-ov-file#beta-dev-and-preview-experimental)
  • beta (ditto)
  • dev (ditto, though it's uncertain whether it's ever used or still needed)
  • deprecated (exists in current docs system per https://github.com/elastic/docs?tab=readme-ov-file#additions-and-deprecations)
  • coming (ditto)
  • discontinued (historically we've immediately removed content when the feature ceases to be supported, but this might not be the case with pages that contain information that spans versions)
  • unavailable (for content that doesn't exist in a specific context and is never coming or not coming anytime soon)
  • ga (replaces "added" in the current docs system since it was not entirely clear how/if that overlapped with beta/preview states)
• Version
  • Only required for some admonitions (e.g. deprecated in X.Y.Z, ga in YYYY-MM-DD) and contexts (e.g. not necessary for serverless admonitions until/if we start versioning it)

TIP: As in our current docs system, we think it's a good idea to make those category values derived rather than something every writer has to type out, since terminology for things like ESS/Elastic Cloud/Elastic Cloud Hosted have changed and might change again. However these directives are implemented should also support future additions if we add new dimensions (e.g. new product phases or deployment types).

NOTE: We haven't gotten input from the design team yet on the best possible way to make these admonitions informative but not too disruptive. We will also work on writer guidelines so that we don't end up with misuse or over-use.

[Mpdreamz]

Partially implemented by #103.

The popovers are not implemented but will wait for confirmation of the current implementation and initial UX design for this feature.

@lcawl do we really need the inline annotations? I fear this will become visually super noisy.

Do we have examples where this would be really beneficial?

E.g in the example what does the deprecation mean? It's listed as available in the heading.

[lcawl]

@lcawl do we really need the inline annotations? I fear this will become visually super noisy.

Do we have examples where this would be really beneficial?

I think it's a good idea to dig deeper into this. From a quick search in the elasticsearch repo for "deprecated:[", for example, the 89 occurrences seem to be in the settings-type reference content. So perhaps if we're shifting reference content to a different yaml- or template-based format that's the more important place to support a method to accomplish line-level admonitions.

Will seek more examples of where/if this applies to narrative content next week.

[lcawl]

Here are the stats from the main or master branch in these repos for the line-level admonitions:

Repo	added	beta	coming	deprecated	dev	experimental / preview	Narrative example
cloud	0	0	0	0	0	2	Release notes
kibana	5	7	0	22	0	22	Manage cases
elasticsearch	4	19	0	89	0	43 / 38	ESQL limitations, Index management
observability_docs	2	8	0	2	0	26	Manage cases, Collect application data, Send data...
security_docs	1	8	0	0	5	5	Event filters, Manage detection alerts, Create a detection rule

In general, most of those occurrences are either (a) reference pages, (b) could have been paragraph- or section-level admonitions. I've added links to some of the few "real" line-level occurrences that mostly appear in ordered lists.

[Mpdreamz]

Thank you for the in-depth research Lisa!

For most of the real use cases I am still personally not a fan of inline admonitions.

e.g:

Why do I care this particular feature was introduced in 8.15.0 I am looking at the 8.17.0 docs which I am assuming are up too date with all the features.

The same is true even if I was looking at the 8.15.0 docs. The callout conveys little information and is the wrong place to advertise new features IMO.

If I was looking at the 8.14.0 docs seeing this doc would make me assume the whole doc is not relevant to me since its mentions a new step not available to me.

[lcawl]

Why do I care this particular feature was introduced in 8.15.0 I am looking at the 8.17.0 docs which I am assuming are up too date with all the features.

I think the trick will be that there will not be 8.15.0 or 8.17.0 docs anymore, there will just be a single "current" version of the page if all goes to plan. So if someone is using a version of the product that doesn't include the ability to do a particular step, it's worth calling out. I have worked on some alerting content where new features are added, for example, but it doesn't prevent you from accomplishing the overall task, just with or without some of those new features.

IMO if it's possible to have paragraph-level admonitions within a numbered list (i.e. to make it clear that the entire step is not relevant in a particular context), that would address the need in all the examples I found.

[KOTungseth]

I agree with Martijn’s concern that line-level admonitions could create unnecessary visual clutter. Our goal is to keep the documentation clear and scannable, avoiding disruption to the reading flow. Section-level admonitions strike the right balance between conveying important information and maintaining readability.

Admonitions should serve as high-level flags to provide critical context to users. If we focus on section-level admonitions, we can avoid overloading users with granular annotations that could obscure the main purpose of the content.

For example, instead of marking a single sentence or line as deprecated or version-specific, a section-level admonition at the beginning of the task can provide the same value while maintaining clarity.

• Consistency — Users expect a consistent pattern in how we convey information. Introducing line-level variations could lead to confusion.
• Task continuity — Users are less likely to get "lost" when the admonition applies to an entire section rather than being interwoven into a task step.
• Future-proofing and simplification — Section-level admonitions make the documentation more maintainable. Instead of updating or removing multiple line-level notes, writers only need to adjust the section-level callout when changes occur.

I propose we move forward with section-level admonitions as the default approach, with the exception of reference and configuration content where individual settings need granular version details.

[Mpdreamz]

Closing this. Let's refocus on inline annotations when the need arrises during the migration.

The other directive is implemented 🎉