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.