diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index d87aca295..c7b172d86 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -422,9 +422,37 @@ applies_to: This allows you to annotate various facets as defined in [](../migration/versioning.md) -## Inline Examples +## Look and feel -### Stack +### Block + +```{applies_to} +stack: preview 9.1 +serverless: planned + +apm_agent_dotnet: ga 1.0.0 +apm_agent_java: beta 1.0.0 +edot_dotnet: preview 1.0.0 +edot_python: +edot_node: ga 1.0.0 +elasticsearch: preview 9.0.0 +security: removed 9.0.0 +observability: deprecated 9.0.0 +``` + +### Inline + +#### In text + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, +sit amet auctor odio. Donec ac placerat nunc. {applies_to}`stack: preview` Aenean scelerisque viverra lectus +nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictum. + +- {applies_to}`elasticsearch: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. +- {applies_to}`observability: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. +- {applies_to}`security: preview` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. Aenean scelerisque viverra lectus nec dignissim. + +#### Stack | `applies_to` | result | |--------------------------------------------|--------------------------------------| @@ -455,7 +483,7 @@ This allows you to annotate various facets as defined in [](../migration/version | `` {applies_to}`stack: removed 9.1` `` | {applies_to}`stack: removed 9.1` | | `` {applies_to}`stack: removed 99.0` `` | {applies_to}`stack: removed 99.0` | -### Serverless +#### Serverless | `applies_to` | result | |-------------------------------------------------|-------------------------------------------| diff --git a/docs/testing/req.md b/docs/testing/req.md index f0667c4a5..526abebc6 100644 --- a/docs/testing/req.md +++ b/docs/testing/req.md @@ -1,7 +1,26 @@ +--- +applies_to: + stack: preview 9.0, ga 9.1 +--- + # Requirements +```{applies_to} +stack: preview 9.0, ga 9.1 +``` + + +{applies_to}`stack: preview 9.0` This tutorial is based on Elasticsearch 9.0. +This tutorial is based on Elasticsearch 9.0. This tutorial is based on Elasticsearch 9.0. +This tutorial is based on Elasticsearch 9.0. + +what + + To follow this tutorial you will need to install the following components: + + - An installation of Elasticsearch, based on our hosted [Elastic Cloud](https://www.elastic.co/cloud) service (which includes a free trial period), or a self-hosted service that you run on your own computer. See the Install Elasticsearch section above for installation instructions. - A [Python](https://python.org) interpreter. Make sure it is a recent version, such as Python 3.8 or newer. diff --git a/src/Elastic.Documentation.Site/Assets/markdown/applies-to.css b/src/Elastic.Documentation.Site/Assets/markdown/applies-to.css index eb0e63844..a021fd476 100644 --- a/src/Elastic.Documentation.Site/Assets/markdown/applies-to.css +++ b/src/Elastic.Documentation.Site/Assets/markdown/applies-to.css @@ -1,88 +1,48 @@ @layer components { - .applies, - .applies-inline { + .applies { cursor: default; + @apply text-subdued; + [data-tippy-content]:not([data-tippy-content='']) { - cursor: help; - border-radius: 9999px; - &:hover { - text-decoration: underline; - } + @apply cursor-help; } - .applicable-meta-removed { - color: var(--color-red-90); - } - .applicable-meta-ga { - color: var(--color-green-90); - } - .applicable-meta-technical-preview { - color: var(--color-blue-elastic-80); - } - .applicable-meta-deprecated { - color: var(--color-pink-90); + .applicable-info { + @apply border-grey-20 inline-grid cursor-default grid-cols-[auto_1fr_auto] rounded-full border-[1px] bg-white pt-1.5 pr-3 pb-1.5 pl-3; } - .applicable-meta-beta { - color: var(--color-poppy-90); + + .applicable-name, + .applicable-meta { + @apply text-xs text-nowrap; } - .applicable-meta-planned { - color: var(--color-grey-90); + + .applicable-separator { + width: 1px; + height: 100%; + background-color: var(--color-grey-20); + margin-left: calc(var(--spacing) * 2); + margin-right: calc(var(--spacing) * 2); } } - .applies { - @apply font-sans; - border-bottom: 1px solid var(--color-grey-20); - padding-bottom: calc(var(--spacing) * 3); - font-variant: all-petite-caps; + .applies.applies-block { + @apply border-b-grey-20 flex flex-wrap gap-2 border-b-1 pb-4; + } - .applicable-info { - padding: calc(var(--spacing) * 0.5); - padding-left: calc(var(--spacing) * 2); - padding-right: calc(var(--spacing) * 2); - margin: calc(var(--spacing) * 0.5); - display: inline-block; - font-size: 0.8em; - border-radius: 0.4em; - background-color: var(--color-white); - border: 1px solid var(--color-grey-20); - } - .applicable-version { - font-weight: bold; - margin-left: calc(var(--spacing) * 0.5); - font-variant: none; - font-size: 0.87em; + .applies.applies-inline { + display: inline-block; + vertical-align: bottom; + .applicable-separator { + margin-left: calc(var(--spacing) * 1.5); + margin-right: calc(var(--spacing) * 1.5); } - .applicable-lifecycle { - font-weight: bold; - } - } - .applies-inline { - @apply font-sans; - font-variant: all-petite-caps; .applicable-info { - cursor: default; - padding: calc(var(--spacing) * 0.5); - padding-left: calc(var(--spacing) * 2); - padding-right: calc(var(--spacing) * 2); - margin-left: calc(var(--spacing) * 0.5); - margin-right: calc(var(--spacing) * 0.5); - display: inline-block; - font-size: 0.8em; - border-radius: 0.4em; - background-color: var(--color-white); - border: 1px solid var(--color-grey-20); - font-weight: normal; - } - .applicable-version { - font-weight: bold; - margin-left: calc(var(--spacing) * 0.5); - font-variant: none; - font-size: 0.87em; + @apply rounded-sm pt-1 pr-1.5 pb-1 pl-1.5; } - .applicable-lifecycle { - font-weight: bold; + .applicable-name, + .applicable-meta { + font-size: 0.65em; } } } diff --git a/src/Elastic.Documentation.Site/Assets/theme.css b/src/Elastic.Documentation.Site/Assets/theme.css index 81fd8af2b..46e1d7b27 100644 --- a/src/Elastic.Documentation.Site/Assets/theme.css +++ b/src/Elastic.Documentation.Site/Assets/theme.css @@ -23,6 +23,7 @@ --color-ink: #343741; --color-ink-light: #535966; --color-ink-dark: #1c1e23; + --color-subdued: #516381; --color-blue-sky: #36b9ff; --color-blue-midnight: #20377d; diff --git a/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml b/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml index 50f99fb2d..1a357020f 100644 --- a/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml +++ b/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml @@ -11,7 +11,7 @@ @if (appliesTo.Stack is not null) { @RenderProduct( - "Elastic Stack", + "Stack", "Part of the versioned Elastic Stack\n\nAvailable in ECH, ECE, ECK, and self-managed deployments, unless otherwise stated", VersioningSystemId.Stack, appliesTo.Stack @@ -21,34 +21,37 @@ { if (appliesTo.Deployment.Ece is not null) { - @RenderProduct("ECE", + @RenderProduct("ECE", "Elastic Cloud Enterprise", - VersioningSystemId.Ece, + VersioningSystemId.Ece, appliesTo.Deployment.Ece ) } + if (appliesTo.Deployment.Eck is not null) { @RenderProduct( - "ECK", + "ECK", "Elastic Cloud on Kubernetes", - VersioningSystemId.Eck, + VersioningSystemId.Eck, appliesTo.Deployment.Eck ) } + if (appliesTo.Deployment.Ess is not null) { @RenderProduct( - "ECH", - "Elastic Cloud Hosted", + "ECH", + "Elastic Cloud Hosted", VersioningSystemId.Ess, appliesTo.Deployment.Ess ) } + if (appliesTo.Deployment.Self is not null) { @RenderProduct( - "Self-Managed", + "Self-Managed", "Self-managed Elastic deployments", VersioningSystemId.Self, appliesTo.Deployment.Self @@ -60,9 +63,9 @@ if (appliesTo.Serverless.AllProjects is not null) { @RenderProduct( - "Serverless", + "Serverless", "Elastic Cloud Serverless: Fully-managed Elastic, available in Elastic Cloud", - VersioningSystemId.Serverless, + VersioningSystemId.Serverless, appliesTo.Serverless.AllProjects ) } @@ -77,27 +80,27 @@ appliesTo.Serverless.Elasticsearch ) } + if (appliesTo.Serverless.Observability is not null) { @RenderProduct( - "Serverless Observability", - "Serverless Observability projects", + "Serverless Observability", + "Serverless Observability projects", VersioningSystemId.Observability, appliesTo.Serverless.Observability ) } + if (appliesTo.Serverless.Security is not null) { @RenderProduct( "Serverless Security", "Serverless Security projects", - VersioningSystemId.Security, + VersioningSystemId.Security, appliesTo.Serverless.Security ) } - } - } @if (appliesTo.Product is not null) { @@ -106,27 +109,119 @@ @if (appliesTo.ProductApplicability is not null) { var pa = appliesTo.ProductApplicability; - if (pa.Ecctl is not null) { + if (pa.Ecctl is not null) + { @RenderProduct("ECCTL", "Elastic Cloud Control", VersioningSystemId.Ecctl, pa.Ecctl) - ; } - if (pa.Curator is not null) { @RenderProduct("Curator", "", VersioningSystemId.Curator, pa.Curator); } - if (pa.ApmAgentAndroid is not null) { @RenderProduct("APM Agent Android", "", VersioningSystemId.ApmAgentAndroid, pa.ApmAgentAndroid); } - if (pa.ApmAgentDotnet is not null) { @RenderProduct("APM Agent .NET", "", VersioningSystemId.ApmAgentDotnet, pa.ApmAgentDotnet); } - if (pa.ApmAgentGo is not null) { @RenderProduct("APM Agent Go", "", VersioningSystemId.ApmAgentGo, pa.ApmAgentGo); } - if (pa.ApmAgentIos is not null) { @RenderProduct("APM Agent iOS", "", VersioningSystemId.ApmAgentIos, pa.ApmAgentIos); } - if (pa.ApmAgentJava is not null) { @RenderProduct("APM Agent Java", "", VersioningSystemId.ApmAgentJava, pa.ApmAgentJava); } - if (pa.ApmAgentNode is not null) { @RenderProduct("APM Agent Node.js", "", VersioningSystemId.ApmAgentNode, pa.ApmAgentNode); } - if (pa.ApmAgentPhp is not null) { @RenderProduct("APM Agent PHP", "", VersioningSystemId.ApmAgentPhp, pa.ApmAgentPhp); } - if (pa.ApmAgentPython is not null) { @RenderProduct("APM Agent Python", "", VersioningSystemId.ApmAgentPython, pa.ApmAgentPython); } - if (pa.ApmAgentRuby is not null) { @RenderProduct("APM Agent Ruby", "", VersioningSystemId.ApmAgentRuby, pa.ApmAgentRuby); } - if (pa.ApmAgentRum is not null) { @RenderProduct("APM Agent RUM", "", VersioningSystemId.ApmAgentRum, pa.ApmAgentRum); } - if (pa.EdotIos is not null) { @RenderProduct("EDOT iOS", "", VersioningSystemId.EdotIos, pa.EdotIos); } - if (pa.EdotAndroid is not null) { @RenderProduct("EDOT Android", "", VersioningSystemId.EdotAndroid, pa.EdotAndroid); } - if (pa.EdotDotnet is not null) { @RenderProduct("EDOT .NET", "", VersioningSystemId.EdotDotnet, pa.EdotDotnet); } - if (pa.EdotJava is not null) { @RenderProduct("EDOT Java", "", VersioningSystemId.EdotJava, pa.EdotJava); } - if (pa.EdotNode is not null) { @RenderProduct("EDOT Node.js", "", VersioningSystemId.EdotNode, pa.EdotNode); } - if (pa.EdotPhp is not null) { @RenderProduct("EDOT PHP", "", VersioningSystemId.ApmAgentPhp, pa.EdotPhp); } - if (pa.EdotPython is not null) { @RenderProduct("EDOT Python", "", VersioningSystemId.EdotPython, pa.EdotPython); } + ; + } + + if (pa.Curator is not null) + { + @RenderProduct("Curator", "", VersioningSystemId.Curator, pa.Curator) + ; + } + + if (pa.ApmAgentAndroid is not null) + { + @RenderProduct("APM Agent Android", "Application Performance Monitoring Agent for Android", VersioningSystemId.ApmAgentAndroid, pa.ApmAgentAndroid) + ; + } + + if (pa.ApmAgentDotnet is not null) + { + @RenderProduct("APM Agent .NET", "Application Performance Monitoring Agent for .NET", VersioningSystemId.ApmAgentDotnet, pa.ApmAgentDotnet) + ; + } + + if (pa.ApmAgentGo is not null) + { + @RenderProduct("APM Agent Go", "Application Performance Monitoring Agent for Go", VersioningSystemId.ApmAgentGo, pa.ApmAgentGo) + ; + } + + if (pa.ApmAgentIos is not null) + { + @RenderProduct("APM Agent iOS", "Application Performance Monitoring Agent for iOS", VersioningSystemId.ApmAgentIos, pa.ApmAgentIos) + ; + } + + if (pa.ApmAgentJava is not null) + { + @RenderProduct("APM Agent Java", "Application Performance Monitoring Agent for Java", VersioningSystemId.ApmAgentJava, pa.ApmAgentJava) + ; + } + + if (pa.ApmAgentNode is not null) + { + @RenderProduct("APM Agent Node.js", "Application Performance Monitoring Agent for Node.js", VersioningSystemId.ApmAgentNode, pa.ApmAgentNode) + ; + } + + if (pa.ApmAgentPhp is not null) + { + @RenderProduct("APM Agent PHP", "Application Performance Monitoring Agent for PHP", VersioningSystemId.ApmAgentPhp, pa.ApmAgentPhp) + ; + } + + if (pa.ApmAgentPython is not null) + { + @RenderProduct("APM Agent Python", "Application Performance Monitoring Agent for Python", VersioningSystemId.ApmAgentPython, pa.ApmAgentPython) + ; + } + + if (pa.ApmAgentRuby is not null) + { + @RenderProduct("APM Agent Ruby", "Application Performance Monitoring Agent for Ruby", VersioningSystemId.ApmAgentRuby, pa.ApmAgentRuby) + ; + } + + if (pa.ApmAgentRum is not null) + { + @RenderProduct("APM Agent RUM", "Application Performance Monitoring Agent for Real User Monitoring", VersioningSystemId.ApmAgentRum, pa.ApmAgentRum) + ; + } + + if (pa.EdotIos is not null) + { + @RenderProduct("EDOT iOS", "Elastic Distributions of OpenTelemetry for iOS", VersioningSystemId.EdotIos, pa.EdotIos) + ; + } + + if (pa.EdotAndroid is not null) + { + @RenderProduct("EDOT Android", "Elastic Distributions of OpenTelemetry for Android", VersioningSystemId.EdotAndroid, pa.EdotAndroid) + ; + } + + if (pa.EdotDotnet is not null) + { + @RenderProduct("EDOT .NET", " Elastic Distributions of OpenTelemetry for .NET", VersioningSystemId.EdotDotnet, pa.EdotDotnet) + ; + } + + if (pa.EdotJava is not null) + { + @RenderProduct("EDOT Java", "Elastic Distributions of OpenTelemetry for Java", VersioningSystemId.EdotJava, pa.EdotJava) + ; + } + + if (pa.EdotNode is not null) + { + @RenderProduct("EDOT Node.js", "Elastic Distributions of OpenTelemetry for Node.js", VersioningSystemId.EdotNode, pa.EdotNode) + ; + } + + if (pa.EdotPhp is not null) + { + @RenderProduct("EDOT PHP", "Elastic Distributions of OpenTelemetry for PHP", VersioningSystemId.ApmAgentPhp, pa.EdotPhp) + ; + } + + if (pa.EdotPython is not null) + { + @RenderProduct("EDOT Python", "Elastic Distributions of OpenTelemetry for Python", VersioningSystemId.EdotPython, pa.EdotPython) + ; + } } @functions { @@ -134,10 +229,9 @@ private IHtmlContent RenderProduct(string name, string description, VersioningSystemId versioningSystemName, AppliesCollection applications) { var versioningSystem = Model.VersionsConfig.GetVersioningSystem(versioningSystemName); - + foreach (var applicability in applications) { - var lifecycleTooltip = ""; var badgeText = name; var lifecycleClass = applicability.GetLifeCycleName().ToLowerInvariant().Replace(" ", "-"); @@ -154,6 +248,7 @@ { lifecycleTooltip = "This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."; } + break; case ProductLifecycle.Beta: if (TryGetRealVersion(applicability, out var betaVersion) && betaVersion > versioningSystem.Current) @@ -191,30 +286,42 @@ badgeText = "Removal planned"; lifecycleTooltip = "We plan to remove this functionality in a future update. Plans may change without notice."; } + break; } if ( - applicability.Version is null - && applicability.Lifecycle != ProductLifecycle.Deprecated + applicability.Version is null + && applicability.Lifecycle != ProductLifecycle.Deprecated && applicability.Lifecycle != ProductLifecycle.Removed && versioningSystem.Id is VersioningSystemId.Stack or VersioningSystemId.Self or VersioningSystemId.Ece or VersioningSystemId.Eck ) { lifecycleTooltip += $"\n\nApplies to version {versioningSystem.Base} and later - may have been introduced in a previous version"; } - + var badgeTextChanged = badgeText != name; - @name - - @if (applicability.Lifecycle != ProductLifecycle.GenerallyAvailable && !badgeTextChanged) - { - @applicability.GetLifeCycleName() + @name + + @{ + var showLifeCycle = applicability.Lifecycle != ProductLifecycle.GenerallyAvailable && !badgeTextChanged; + var showVersion = applicability.Version is not null and not AllVersions; } - @if (applicability.Version is not null and not AllVersions) + + @if (!string.IsNullOrEmpty(name) && (showLifeCycle || showVersion)) { - @if (versioningSystem.Current >= applicability.Version) + + } + + @if (showLifeCycle) + { + @applicability.GetLifeCycleName() + } + @if (showVersion) + { + @if (versioningSystem.Current >= applicability.Version!) { @applicability.Version @@ -222,18 +329,20 @@ } else { - - @badgeText - + @badgeText } - } + } } + return HtmlString.Empty; } + } + @functions { + private static bool TryGetRealVersion(Applicability applicability, [NotNullWhen(true)] out SemVersion? version) { version = null; @@ -245,4 +354,5 @@ return false; } + } diff --git a/src/Elastic.Markdown/Myst/Directives/AppliesTo/AppliesToView.cshtml b/src/Elastic.Markdown/Myst/Directives/AppliesTo/AppliesToView.cshtml index 7610f59e2..12996274f 100644 --- a/src/Elastic.Markdown/Myst/Directives/AppliesTo/AppliesToView.cshtml +++ b/src/Elastic.Markdown/Myst/Directives/AppliesTo/AppliesToView.cshtml @@ -1,6 +1,6 @@ @using Elastic.Markdown.Myst.Components @inherits RazorSlice -

+

@await RenderPartialAsync(ApplicableToComponent.Create(Model))

diff --git a/src/Elastic.Markdown/Myst/FrontMatter/Applicability.cs b/src/Elastic.Markdown/Myst/FrontMatter/Applicability.cs index cefd1f04e..a50a421bd 100644 --- a/src/Elastic.Markdown/Myst/FrontMatter/Applicability.cs +++ b/src/Elastic.Markdown/Myst/FrontMatter/Applicability.cs @@ -108,7 +108,7 @@ public record Applicability public string GetLifeCycleName() => Lifecycle switch { - ProductLifecycle.TechnicalPreview => "Technical Preview", + ProductLifecycle.TechnicalPreview => "Preview", ProductLifecycle.Beta => "Beta", ProductLifecycle.Development => "Development", ProductLifecycle.Deprecated => "Deprecated", diff --git a/src/Elastic.Markdown/Myst/Roles/AppliesTo/ApplicableToRole.cshtml b/src/Elastic.Markdown/Myst/Roles/AppliesTo/ApplicableToRole.cshtml index df7f628c6..48295cb1b 100644 --- a/src/Elastic.Markdown/Myst/Roles/AppliesTo/ApplicableToRole.cshtml +++ b/src/Elastic.Markdown/Myst/Roles/AppliesTo/ApplicableToRole.cshtml @@ -1,6 +1,6 @@ @using Elastic.Markdown.Myst.Components @inherits RazorSlice - + @await RenderPartialAsync(ApplicableToComponent.Create(Model)) diff --git a/src/Elastic.Markdown/Page/Index.cshtml b/src/Elastic.Markdown/Page/Index.cshtml index 2338c753e..390e38a37 100644 --- a/src/Elastic.Markdown/Page/Index.cshtml +++ b/src/Elastic.Markdown/Page/Index.cshtml @@ -61,7 +61,7 @@ @(new HtmlString(Markdown.ToHtml("# " + Model.TitleRaw))) @if (Model.AppliesTo is not null) { -

+

@await RenderPartialAsync(ApplicableToComponent.Create(new ApplicableToViewModel { AppliesTo = Model.AppliesTo, diff --git a/tests/authoring/Inline/AppliesToRole.fs b/tests/authoring/Inline/AppliesToRole.fs index e5583c25f..90cea9ea1 100644 --- a/tests/authoring/Inline/AppliesToRole.fs +++ b/tests/authoring/Inline/AppliesToRole.fs @@ -29,15 +29,14 @@ This is an inline {applies_to}`stack: preview 9.1` element. let ``validate HTML: generates link and alt attr`` () = markdown |> convertsToHtml """

This is an inline - + Elastic Stack +Available in ECH, ECE, ECK, and self-managed deployments, unless otherwise stated">Stack + - - Planned - + Planned