Add support for version context variables

docs/_docset.yml

@@ -100,6 +100,7 @@ toc:
       - file: sidebars.md
       - file: stepper.md
       - file: substitutions.md
+      - file: version-variables.md
       - file: sundries.md
       - file: tables.md
       - file: tabs.md

docs/syntax/substitutions.md

@@ -3,6 +3,7 @@ sub:
   frontmatter_key: "Front Matter Value"
   a-key-with-dashes: "A key with dashes"
   version: 7.17.0
+  hello-world: "Hello world!"
 ---
 
 # Substitutions
@@ -26,7 +27,7 @@ Doing so will result in a build error.
 
 To use the variables in your files, surround them in curly brackets (`{{variable}}`).
 
-## Example
+### Example
 
 Here are some variable substitutions:
 
@@ -36,6 +37,97 @@ Here are some variable substitutions:
 | {{a-key-with-dashes}} | Front Matter |
 | {{a-global-variable}} | `docset.yml` |
 
+## Mutations
+
+Substitutions can be mutated using a chain of operators seperated by a pipe (`|`).
+
+````markdown
+`{{hello-world | trim | lc | tc}}`
+````
+
+Will trim, lowercase and finally titlecase the contents of the 'hello-world' variable.
+
+### Operators
+
+
+| Operator | Purpose                                            |
+|----------|----------------------------------------------------|
+| `lc`     | LowerCase,                                         |
+| `uc`     | UpperCase,                                         |
+| `tc`     | TitleCase, capitalizes all words,                  |
+| `c`      | Capitalize the first letter,                       |
+| `kc`     | Convert to KebabCase,                              |
+| `sc`     | Convert to SnakeCase,                              |
+| `cc`     | Convert to CamelCase,                              |
+| `pc`     | Convert to PascalCase,                             |
+| `trim`   | Trim common non word characters from start and end |
+
+For variables declaring a semantic version or `Major.Minor` the following operations are also exposed
+
+| Operator | Purpose                                  |
+|----------|------------------------------------------|
+| `M`      | Display only the major component         |
+| `M.x`    | Display major component followed by '.x' |
+| `M.M`    | Display only the major and the minor     |
+| `M+1`    | The next major version                   |
+| `M.M+1`  | The next minor version                   |
+
+### Example
+
+Given the following frontmatter:
+
+```yaml
+---
+sub:
+  hello-world: "Hello world!"
+---
+```
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+* Lowercase: {{hello-world | lc}}
+* Uppercase: {{hello-world | uc}}
+* TitleCase: {{hello-world | tc}}
+* kebab-case: {{hello-world | kc}}
+* camelCase: {{hello-world | tc | cc}}
+* PascalCase: {{hello-world | pc}}
+* SnakeCase: {{hello-world | sc}}
+* CapitalCase (chained): {{hello-world | lc | c}}
+* Trim: {{hello-world | trim}}
+* M.x: {{version.stack | M.x }}
+* M.M: {{version.stack | M.M }}
+* M: {{version.stack | M }}
+* M+1: {{version.stack | M+1 }}
+* M+1 | M.M: {{version.stack | M+1 | M.M }}
+* M.M+1: {{version.stack | M.M+1 }}
+
+:::
+
+:::{tab-item} Markdown
+
+````markdown
+* Lowercase: {{hello-world | lc}}
+* Uppercase: {{hello-world | uc}}
+* TitleCase: {{hello-world | tc}}
+* kebab-case: {{hello-world | kc}}
+* camelCase: {{hello-world | tc | cc}}
+* PascalCase: {{hello-world | pc}}
+* SnakeCase: {{hello-world | sc}}
+* CapitalCase (chained): {{hello-world | lc | c}}
+* Trim: {{hello-world | trim}}
+* M.x: {{version.stack | M.x }}
+* M.M: {{version.stack | M.M }}
+* M: {{version.stack | M }}
+* M+1: {{version.stack | M+1 }}
+* M+1 | M.M: {{version.stack | M+1 | M.M }}
+* M.M+1: {{version.stack | M.M+1 }}
+````
+:::
+
+::::
+
 ## Code blocks
 
 Substitutions are supported in code blocks but are disabled by default. Enable substitutions by adding `subs=true` to the code block.

docs/syntax/version-variables.md

@@ -0,0 +1,70 @@
+# Version Variables
+
+Version are exposed during build using the `{{versions.VERSIONING_SCHEME}}` variable.
+
+For example `stack` versioning variables are exposed as `{{versions.stack}}`.
+
+## Specialized Suffixes.
+
+Besides the current version, the following suffixes are available:
+
+| Version substitution                 | result                            | purpose                                 |
+|--------------------------------------|-----------------------------------|-----------------------------------------| 
+| `{{version.stack}}`                 | {{version.stack}}                 | Current version                         |
+| `{{version.stack.base}}`            | {{version.stack.base}}            | The first version on the new doc system |
+
+## Formatting
+
+Using specialized [mutation operators](substitutions.md#mutations) versions 
+can be printed in any kind of ways.
+
+
+| Version substitution   | result    |
+|------------------------|-----------|
+| `{{version.stack| M.M}}`    |  {{version.stack|M.M}} |
+| `{{version.stack.base | M }}`     | {{version.stack.base | M }} |
+| `{{version.stack | M+1       | M }}` | {{version.stack | M+1 | M }} |
+| `{{version.stack.base | M.M+1 }}` | {{version.stack.base | M.M+1 }} |
+
+## Available versioning schemes.
+
+This is dictated by the [versions.yml](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation.Configuration/versions.yml) configuration file
+
+* `stack`
+* `ece`
+* `ech`
+* `eck`
+* `ess`
+* `self`
+* `ecctl`
+* `curator`
+* `security`
+* `apm_agent_android`
+* `apm_agent_ios`
+* `apm_agent_dotnet`
+* `apm_agent_go`
+* `apm_agent_java`
+* `apm_agent_node`
+* `apm_agent_php`
+* `apm_agent_python`
+* `apm_agent_ruby`
+* `apm_agent_rum`
+* `edot_ios`
+* `edot_android`
+* `edot_dotnet`
+* `edot_java`
+* `edot_node`
+* `edot_php`
+* `edot_python`
+* `edot_cf_aws`
+* `edot_collector`
+
+The following are available but should not be used. These map to serverless projects and have a fixed high version number.
+
+* `all`
+* `ech`
+* `ess` (This is deprectated but was added for backwards-compatibility.)
+
+* `serverless`
+* `elasticsearch`
+* `observability`

src/Elastic.Documentation.Configuration/BuildContext.cs

@@ -100,7 +100,7 @@ public BuildContext(
 			DocumentationSourceDirectory = ConfigurationPath.Directory!;
 
 		Git = gitCheckoutInformation ?? GitCheckoutInformation.Create(DocumentationCheckoutDirectory, ReadFileSystem);
-		Configuration = new ConfigurationFile(this);
+		Configuration = new ConfigurationFile(this, VersionsConfig);
 		GoogleTagManager = new GoogleTagManagerConfiguration
 		{
 			Enabled = false

src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs

@@ -6,6 +6,7 @@
 using DotNet.Globbing;
 using Elastic.Documentation.Configuration.Suggestions;
 using Elastic.Documentation.Configuration.TableOfContents;
+using Elastic.Documentation.Configuration.Versions;
 using Elastic.Documentation.Links;
 using Elastic.Documentation.Navigation;
 using YamlDotNet.RepresentationModel;
@@ -61,7 +62,7 @@ public record ConfigurationFile : ITableOfContentsScope
 		Project is not null
 		&& Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase);
 
-	public ConfigurationFile(IDocumentationContext context)
+	public ConfigurationFile(IDocumentationContext context, VersionsConfiguration versionsConfig)
 	{
 		_context = context;
 		ScopeDirectory = context.ConfigurationPath.Directory!;
@@ -159,6 +160,16 @@ public ConfigurationFile(IDocumentationContext context)
 				}
 			}
 
+			foreach (var (id, system) in versionsConfig.VersioningSystems)
+			{
+				var name = id.ToStringFast(true);
+				var key = $"version.{name}";
+				_substitutions[key] = system.Current;
+
+				key = $"version.{name}.base";
+				_substitutions[key] = system.Base;
+			}
+
 			var toc = new TableOfContentsConfiguration(this, sourceFile, ScopeDirectory, _context, 0, "");
 			TableOfContents = toc.TableOfContents;
 			Files = toc.Files;

src/Elastic.Documentation.Configuration/Versions/Version.cs

@@ -44,11 +44,11 @@ public enum VersioningSystemId
 	[Display(Name = "serverless")]
 	Serverless,
 	[Display(Name = "elasticsearch")]
-	Elasticsearch,
+	ElasticsearchProject,
 	[Display(Name = "observability")]
-	Observability,
+	ObservabilityProject,
 	[Display(Name = "security")]
-	Security,
+	SecurityProject,
 	[Display(Name = "apm_agent_android")]
 	ApmAgentAndroid,
 	[Display(Name = "apm_agent_ios")]

src/Elastic.Markdown/Diagnostics/ProcessorDiagnosticExtensions.cs

@@ -14,32 +14,24 @@ public static class ProcessorDiagnosticExtensions
 {
 	private static string CreateExceptionMessage(string message, Exception? e) => message + (e != null ? Environment.NewLine + e : string.Empty);
 
-	public static void EmitError(this InlineProcessor processor, int line, int column, int length, string message)
-	{
-		var context = processor.GetContext();
-		if (context.SkipValidation)
-			return;
-		var d = new Diagnostic
-		{
-			Severity = Severity.Error,
-			File = processor.GetContext().MarkdownSourcePath.FullName,
-			Column = column,
-			Line = line,
-			Message = message,
-			Length = length
-		};
-		context.Build.Collector.Write(d);
-	}
+	public static void EmitError(this InlineProcessor processor, int line, int column, int length, string message) =>
+		processor.Emit(Severity.Error, line, column, length, message);
 
 
-	public static void EmitWarning(this InlineProcessor processor, int line, int column, int length, string message)
+	public static void EmitWarning(this InlineProcessor processor, int line, int column, int length, string message) =>
+		processor.Emit(Severity.Warning, line, column, length, message);
+
+	public static void EmitHint(this InlineProcessor processor, int line, int column, int length, string message) =>
+		processor.Emit(Severity.Hint, line, column, length, message);
+
+	public static void Emit(this InlineProcessor processor, Severity severity, int line, int column, int length, string message)
 	{
 		var context = processor.GetContext();
 		if (context.SkipValidation)
 			return;
 		var d = new Diagnostic
 		{
-			Severity = Severity.Warning,
+			Severity = severity,
 			File = processor.GetContext().MarkdownSourcePath.FullName,
 			Column = column,
 			Line = line,

src/Elastic.Markdown/DocumentationGenerator.cs

@@ -180,7 +180,13 @@ private void HintUnusedSubstitutionKeys()
 	{
 		var definedKeys = new HashSet<string>(Context.Configuration.Substitutions.Keys.ToArray());
 		var inUse = new HashSet<string>(Context.Collector.InUseSubstitutionKeys.Keys);
-		var keysNotInUse = definedKeys.Except(inUse).ToArray();
+		var keysNotInUse = definedKeys.Except(inUse)
+				// versions keys are injected
+				.Where(key => !key.StartsWith("version."))
+				// reserving context namespace
+				.Where(key => !key.StartsWith("context."))
+				.ToArray();
+
 		// If we have less than 20 unused keys, emit them separately,
 		// Otherwise emit one hint with all of them for brevity
 		if (keysNotInUse.Length >= 20)