Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for context-specific admonitions #94

Open
lcawl opened this issue Dec 5, 2024 · 0 comments
Open

Add support for context-specific admonitions #94

lcawl opened this issue Dec 5, 2024 · 0 comments

Comments

@lcawl
Copy link

lcawl commented Dec 5, 2024

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:

Image

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:

Image

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
  • 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant