Introduce substitutions for previous versions

Author: cotti

docs/syntax/substitutions.md

@@ -236,3 +236,9 @@ id:
 ```
 
 A shorthand format is also available. Using `{{.id}}` is equivalent to `{{product.id}}`.
+
+## Previous stack version
+
+Products with a matching legacy URL mapping can access their previous version:
+
+Example: `{{version.stack.previous}}` produces {{version.stack.previous}}.

src/Elastic.Documentation.Configuration/BuildContext.cs

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

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

@@ -8,6 +8,7 @@
 using Elastic.Documentation.Configuration.Suggestions;
 using Elastic.Documentation.Configuration.TableOfContents;
 using Elastic.Documentation.Configuration.Versions;
+using Elastic.Documentation.Configuration.LegacyUrlMappings;
 using Elastic.Documentation.Links;
 using Elastic.Documentation.Navigation;
 using YamlDotNet.RepresentationModel;
@@ -63,7 +64,7 @@ public record ConfigurationFile : ITableOfContentsScope
 		Project is not null
 		&& Project.Equals("Elastic documentation", StringComparison.OrdinalIgnoreCase);
 
-	public ConfigurationFile(IDocumentationSetContext context, VersionsConfiguration versionsConfig, ProductsConfiguration productsConfig)
+	public ConfigurationFile(IDocumentationSetContext context, VersionsConfiguration versionsConfig, ProductsConfiguration productsConfig, LegacyUrlMappingConfiguration legacyUrlMappingsConfig)
 	{
 		_context = context;
 		ScopeDirectory = context.ConfigurationPath.Directory!;
@@ -167,16 +168,21 @@ public ConfigurationFile(IDocumentationSetContext context, VersionsConfiguration
 				}
 			}
 
-			foreach (var (id, system) in versionsConfig.VersioningSystems)
+			foreach (var (id, system, previousVersion) in
+					 versionsConfig.VersioningSystems.Select(kvp =>
+						 (kvp.Key, kvp.Value,
+							 legacyUrlMappingsConfig.Mappings.FirstOrDefault(m =>
+								 m.Product.VersioningSystem == kvp.Value)?.LegacyVersions.FirstOrDefault() ?? string.Empty)))
 			{
 				var name = id.ToStringFast(true);
 				var alternativeName = name.Replace('-', '_');
 				_substitutions[$"version.{name}"] = system.Current;
 				_substitutions[$"version.{alternativeName}"] = system.Current;
 				_substitutions[$"version.{name}.base"] = system.Base;
 				_substitutions[$"version.{alternativeName}.base"] = system.Base;
+				_substitutions[$"version.{name}.previous"] = previousVersion;
+				_substitutions[$"version.{alternativeName}.previous"] = previousVersion;
 			}
-
 			foreach (var product in productsConfig.Products.Values)
 			{
 				var alternativeProductId = product.Id.Replace('-', '_');