Add subs support for inline code snippets (#1705)

* Add inline subs

* Reorder docs

* Edit docs

* Rename to role

* Delete demo file

Author: theletterf

docs/syntax/substitutions.md

@@ -4,6 +4,7 @@ sub:
   a-key-with-dashes: "A key with dashes"
   version: 7.17.0
   hello-world: "Hello world!"
+  env-var: "MY_VAR"
 ---
 
 # Substitutions
@@ -25,9 +26,13 @@ subs:
 If a substitution is defined globally it may not be redefined (shaded) in a files `frontmatter`. 
 Doing so will result in a build error.
 
-To use the variables in your files, surround them in curly brackets (`{{variable}}`).
+To use the variables in your files, surround them in curly brackets (`{{variable}}`). Substitutions work in:
 
-### Example
+- Regular text content
+- Code blocks (when `subs=true` is specified)
+- Inline code snippets (when `{subs}` prefix is used)
+
+## Example
 
 Here are some variable substitutions:
 
@@ -170,50 +175,45 @@ cd elasticsearch-{{version}}/
 ::::
 
 
-### MD code block with subs enabled
+## Inline code
 
-::::{tab-set}
+Substitutions are also supported in inline code snippets using the `{subs}` syntax.
 
-:::{tab-item} Output
-
-```bash subs=true
-echo "{{a-global-variable}}"
+```markdown
+{subs}`wget elasticsearch-{{version.stack}}.tar.gz`
 ```
 
-:::
-
-:::{tab-item} Markdown
+### Inline code examples
 
-````markdown
-```bash subs=true
-echo "{{a-global-variable}}"
-```
+::::{tab-set}
 
-````
-:::
- 
-::::
+:::{tab-item} Output
 
-###  MD code block without subs enabled
+Regular inline code: `wget elasticsearch-{{version.stack}}.tar.gz`
 
-::::{tab-set}
+With substitutions: {subs}`wget elasticsearch-{{version.stack}}.tar.gz`
 
-:::{tab-item} Output
+Multiple variables: {subs}`export {{env-var}}={{version.stack}}`
 
-```bash 
-echo "{{a-global-variable}}"
-```
+With mutations: {subs}`version {{version.stack | M.M}}`
 
 :::
 
 :::{tab-item} Markdown
 
 ````markdown
-```bash
-echo "{{a-global-variable}}"
-```
+Regular inline code: `wget elasticsearch-{{version.stack}}.tar.gz`
 
+With substitutions: {subs=true}`wget elasticsearch-{{version.stack}}.tar.gz`
+
+Multiple variables: {subs=true}`export {{env-var}}={{version.stack}}`
+
+With mutations: {subs=true}`version {{version.stack | M.M}}`
 ````
-:::
 
+:::
 ::::
+
+:::{note}
+Regular inline code (without the `{subs=true}` prefix) will not process substitutions and will display the variable placeholders as-is.
+:::

src/Elastic.Markdown/Myst/InlineParsers/SubstitutionInlineCode/SubstitutionInlineCodeBuilderExtensions.cs

@@ -0,0 +1,37 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using Markdig;
+using Markdig.Parsers.Inlines;
+using Markdig.Renderers;
+using Markdig.Renderers.Html.Inlines;
+
+namespace Elastic.Markdown.Myst.InlineParsers.SubstitutionInlineCode;
+
+public static class SubstitutionInlineCodeBuilderExtensions
+{
+	public static MarkdownPipelineBuilder UseSubstitutionInlineCode(this MarkdownPipelineBuilder pipeline)
+	{
+		pipeline.Extensions.AddIfNotAlready<SubstitutionInlineCodeMarkdownExtension>();
+		return pipeline;
+	}
+}
+
+public class SubstitutionInlineCodeMarkdownExtension : IMarkdownExtension
+{
+	public void Setup(MarkdownPipelineBuilder pipeline)
+	{
+		if (!pipeline.InlineParsers.Contains<SubstitutionInlineCodeParser>())
+		{
+			// Insert before CodeInlineParser to intercept {subs=true}`...` patterns
+			_ = pipeline.InlineParsers.InsertBefore<CodeInlineParser>(new SubstitutionInlineCodeParser());
+		}
+	}
+
+	public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
+	{
+		if (!renderer.ObjectRenderers.Contains<SubstitutionInlineCodeRenderer>())
+			_ = renderer.ObjectRenderers.InsertBefore<CodeInlineRenderer>(new SubstitutionInlineCodeRenderer());
+	}
+}

src/Elastic.Markdown/Myst/InlineParsers/SubstitutionInlineCode/SubstitutionInlineCodeParser.cs

@@ -0,0 +1,135 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Buffers;
+using System.Diagnostics;
+using System.Text;
+using System.Text.RegularExpressions;
+using Elastic.Documentation;
+using Elastic.Documentation.Diagnostics;
+using Elastic.Markdown.Diagnostics;
+using Elastic.Markdown.Myst.InlineParsers.Substitution;
+using Elastic.Markdown.Myst.Roles;
+using Markdig.Helpers;
+using Markdig.Parsers;
+using Markdig.Renderers;
+using Markdig.Renderers.Html;
+using Markdig.Syntax;
+using Markdig.Syntax.Inlines;
+
+namespace Elastic.Markdown.Myst.InlineParsers.SubstitutionInlineCode;
+
+[DebuggerDisplay("{GetType().Name} Line: {Line}, Content: {Content}, ProcessedContent: {ProcessedContent}")]
+public class SubstitutionInlineCodeLeaf(string role, string content, string processedContent) : RoleLeaf(role, content)
+{
+	public string ProcessedContent { get; } = processedContent;
+}
+
+public class SubstitutionInlineCodeRenderer : HtmlObjectRenderer<SubstitutionInlineCodeLeaf>
+{
+	protected override void Write(HtmlRenderer renderer, SubstitutionInlineCodeLeaf leaf)
+	{
+		// Render as a code element with the processed content (substitutions applied)
+		_ = renderer.Write("<code");
+		_ = renderer.WriteAttributes(leaf);
+		_ = renderer.Write(">");
+		_ = renderer.WriteEscape(leaf.ProcessedContent);
+		_ = renderer.Write("</code>");
+	}
+}
+
+public partial class SubstitutionInlineCodeParser : RoleParser<SubstitutionInlineCodeLeaf>
+{
+	protected override SubstitutionInlineCodeLeaf CreateRole(string role, string content, InlineProcessor parserContext)
+	{
+		var context = (ParserContext)parserContext.Context!;
+		var processedContent = ProcessSubstitutions(content, context, parserContext, 0, 0);
+		return new SubstitutionInlineCodeLeaf(role, content, processedContent);
+	}
+
+	protected override bool Matches(ReadOnlySpan<char> role) => role.SequenceEqual("{subs}".AsSpan());
+
+	private static readonly Regex SubstitutionPattern = SubstitutionRegex();
+
+	private static string ProcessSubstitutions(string content, ParserContext context, InlineProcessor processor, int line, int column)
+	{
+		var result = new StringBuilder(content);
+		var substitutions = new List<(int Start, int Length, string Replacement)>();
+
+		// Find all substitution patterns
+		foreach (Match match in SubstitutionPattern.Matches(content))
+		{
+			var rawKey = match.Groups[1].Value.Trim().ToLowerInvariant();
+			var found = false;
+			var replacement = string.Empty;
+
+			// Use shared mutation parsing logic
+			var (key, mutationStrings) = SubstitutionMutationHelper.ParseKeyWithMutations(rawKey);
+
+			if (context.Substitutions.TryGetValue(key, out var value) && value is not null)
+			{
+				found = true;
+				replacement = value;
+			}
+			else if (context.ContextSubstitutions.TryGetValue(key, out value) && value is not null)
+			{
+				found = true;
+				replacement = value;
+			}
+
+			if (found)
+			{
+				context.Build.Collector.CollectUsedSubstitutionKey(key);
+
+				// Apply mutations if any
+				if (mutationStrings.Length > 0)
+				{
+					if (mutationStrings.Length >= 10)
+					{
+						processor.EmitError(line + 1, column + match.Index, match.Length, $"Substitution key {{{key}}} defines too many mutations, none will be applied");
+						replacement = value; // Use original value without mutations
+					}
+					else
+					{
+						var mutations = new List<SubstitutionMutation>();
+						foreach (var mutationStr in mutationStrings)
+						{
+							var trimmedMutation = mutationStr.Trim();
+							if (SubstitutionMutationExtensions.TryParse(trimmedMutation, out var mutation, true, true))
+							{
+								mutations.Add(mutation);
+							}
+							else
+							{
+								processor.EmitError(line + 1, column + match.Index, match.Length, $"Mutation '{trimmedMutation}' on {{{key}}} is undefined");
+							}
+						}
+
+						if (mutations.Count > 0)
+							replacement = SubstitutionMutationHelper.ApplyMutations(replacement, mutations);
+					}
+				}
+
+				substitutions.Add((match.Index, match.Length, replacement ?? string.Empty));
+			}
+			else
+			{
+				// We temporarily diagnose variable spaces as hints. We used to not read this at all.
+				processor.Emit(key.Contains(' ') ? Severity.Hint : Severity.Error, line + 1, column + match.Index, match.Length, $"Substitution key {{{key}}} is undefined");
+			}
+		}
+
+		// Apply substitutions in reverse order to maintain correct indices
+		foreach (var (start, length, replacement) in substitutions.OrderByDescending(s => s.Start))
+		{
+			_ = result.Remove(start, length);
+			_ = result.Insert(start, replacement);
+		}
+
+		return result.ToString();
+	}
+
+	[GeneratedRegex(@"\{\{([^}]+)\}\}", RegexOptions.Compiled)]
+	private static partial Regex SubstitutionRegex();
+}

src/Elastic.Markdown/Myst/MarkdownParser.cs

@@ -12,6 +12,7 @@
 using Elastic.Markdown.Myst.FrontMatter;
 using Elastic.Markdown.Myst.InlineParsers;
 using Elastic.Markdown.Myst.InlineParsers.Substitution;
+using Elastic.Markdown.Myst.InlineParsers.SubstitutionInlineCode;
 using Elastic.Markdown.Myst.Linters;
 using Elastic.Markdown.Myst.Renderers;
 using Elastic.Markdown.Myst.Roles.AppliesTo;
@@ -154,6 +155,7 @@ public static MarkdownPipeline Pipeline
 				.UseDiagnosticLinks()
 				.UseHeadingsWithSlugs()
 				.UseEmphasisExtras(EmphasisExtraOptions.Default)
+				.UseSubstitutionInlineCode()
 				.UseInlineAppliesTo()
 				.UseInlineIcons()
 				.UseInlineKbd()

tests/Elastic.Markdown.Tests/Inline/SubstitutionInlineCodeTest.cs

@@ -0,0 +1,43 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using FluentAssertions;
+
+namespace Elastic.Markdown.Tests.Inline;
+
+public class SubstitutionInlineCodeTest(ITestOutputHelper output) : InlineTest(output,
+"""
+---
+sub:
+  version: "8.15.0"
+  env-var: "MY_VAR"
+---
+
+# Testing inline code substitutions
+
+Regular code: `wget elasticsearch-{{version}}.tar.gz`
+
+Code with substitutions: {subs}`wget elasticsearch-{{version}}.tar.gz`
+
+Multiple substitutions: {subs}`export {{env-var}}={{version}}`
+
+With mutations: {subs}`version {{version | M.M}}`
+"""
+)
+{
+	[Fact]
+	public void TestSubstitutionInlineCode()
+	{
+		// Check that regular code blocks are not processed
+		Html.Should().Contain("<code>wget elasticsearch-{{version}}.tar.gz</code>");
+
+		// Check that {subs} inline code blocks have substitutions applied
+		Html.Should().Contain("<code>wget elasticsearch-8.15.0.tar.gz</code>");
+		Html.Should().Contain("<code>export MY_VAR=8.15.0</code>");
+		Html.Should().Contain("<code>version 8.15</code>");
+	}
+
+	[Fact]
+	public void HasNoErrors() => Collector.Diagnostics.Should().HaveCount(0);
+}