Icons

docs/_docset.yml

@@ -1,4 +1,4 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
 # relaxes a few restrictions around toc building and file placement
@@ -85,6 +85,7 @@
       - file: example_blocks.md
       - file: file_inclusion.md
       - file: frontmatter.md
+      - file: icons.md
       - file: images.md
       - file: lists.md
       - file: line_breaks.md

src/Elastic.Documentation.Site/Assets/markdown/icons.css

@@ -0,0 +1,13 @@
+@layer components {
+	.markdown-content {
+		.icon {
+			@apply inline-block align-middle;
+			transform: translateY(-0.05em);
+			svg {
+				width: 1em;
+				height: 1em;
+				fill: currentColor;
+			}
+		}
+	}
+}

src/Elastic.Documentation.Site/Assets/styles.css

@@ -7,6 +7,7 @@
 @import './markdown/list.css';
 @import './markdown/tabs.css';
 @import './markdown/code.css';
+@import './markdown/icons.css';
 @import './copybutton.css';
 @import './markdown/admonition.css';
 @import './markdown/dropdown.css';

src/Elastic.Markdown/Elastic.Markdown.csproj

@@ -36,4 +36,8 @@
     <ProjectReference Include="..\Elastic.Documentation.Configuration\Elastic.Documentation.Configuration.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <EmbeddedResource Include="Myst\Roles\Icons\svgs\*.svg" />
+  </ItemGroup>
+
 </Project>

src/Elastic.Markdown/Myst/Directives/DirectiveParagraphParser.cs

@@ -1,6 +1,7 @@
 // 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.Parsers;
 using Markdig.Syntax;
 

src/Elastic.Markdown/Myst/InlineParsers/HeadingBlockWithSlugParser.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information
 
 using System.Text.RegularExpressions;
+using Elastic.Markdown.Myst.Roles.Icons;
 using Markdig;
 using Markdig.Helpers;
 using Markdig.Parsers;
@@ -30,13 +31,17 @@ public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) { }
 
 public class HeadingBlockWithSlugParser : HeadingBlockParser
 {
+	private static readonly Regex IconSyntax = IconParser.IconRegex();
+
 	public override bool Close(BlockProcessor processor, Block block)
 	{
-		if (block is not HeadingBlock headerBlock)
+		if (block is not HeadingBlock headingBlock)
 			return base.Close(processor, block);
 
-		var text = headerBlock.Lines.Lines[0].Slice.AsSpan();
-		headerBlock.SetData("header", text.ToString());
+		var text = headingBlock.Lines.Lines[0].Slice.AsSpan();
+		// Remove icon syntax from the heading text
+		var cleanText = IconSyntax.Replace(text.ToString(), "").Trim();
+		headingBlock.SetData("header", cleanText);
 
 		if (!HeadingAnchorParser.MatchAnchorLine().IsMatch(text))
 			return base.Close(processor, block);
@@ -49,13 +54,13 @@ public override bool Close(BlockProcessor processor, Block block)
 			var anchor = text.Slice(match.Index, match.Length);
 
 			var newSlice = new StringSlice(header.ToString());
-			headerBlock.Lines.Lines[0] = new StringLine(ref newSlice);
+			headingBlock.Lines.Lines[0] = new StringLine(ref newSlice);
 
 			if (header.IndexOf('$') >= 0)
 				anchor = HeadingAnchorParser.MatchAnchor().Replace(anchor.ToString(), "");
-
-			headerBlock.SetData("anchor", anchor.ToString());
-			headerBlock.SetData("header", header.ToString());
+			headingBlock.SetData("anchor", anchor.ToString());
+			// Remove icon syntax from the header text when setting it as data
+			headingBlock.SetData("header", IconSyntax.Replace(header.ToString(), "").Trim());
 			return base.Close(processor, block);
 		}
 

src/Elastic.Markdown/Myst/MarkdownParser.cs

@@ -14,7 +14,7 @@
 using Elastic.Markdown.Myst.Linters;
 using Elastic.Markdown.Myst.Renderers;
 using Elastic.Markdown.Myst.Roles.AppliesTo;
-
+using Elastic.Markdown.Myst.Roles.Icons;
 using Markdig;
 using Markdig.Extensions.EmphasisExtras;
 using Markdig.Parsers;
@@ -146,6 +146,7 @@ public static MarkdownPipeline Pipeline
 				.UseHeadingsWithSlugs()
 				.UseEmphasisExtras(EmphasisExtraOptions.Default)
 				.UseInlineAppliesTo()
+				.UseInlineIcons()
 				.UseSubstitution()
 				.UseComments()
 				.UseYamlFrontMatter()

src/Elastic.Markdown/Myst/Roles/Icons/IconRole.cs

@@ -0,0 +1,60 @@
+// 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.Diagnostics;
+using System.Text.RegularExpressions;
+using Elastic.Markdown.Diagnostics;
+using Markdig.Parsers;
+
+namespace Elastic.Markdown.Myst.Roles.Icons;
+
+[DebuggerDisplay("{GetType().Name} Line: {Line}, Role: {Role}, Content: {Content}")]
+public class IconsRole : RoleLeaf
+{
+	private static readonly IReadOnlyDictionary<string, string> IconMap;
+	static IconsRole()
+	{
+		var assembly = typeof(IconsRole).Assembly;
+		var iconFolder = $"{assembly.GetName().Name}.Myst.Roles.Icons.svgs.";
+		IconMap = assembly.GetManifestResourceNames()
+			.Where(r => r.StartsWith(iconFolder) && r.EndsWith(".svg"))
+			.ToDictionary(
+				r => r[iconFolder.Length..].Replace(".svg", string.Empty),
+				r =>
+				{
+					using var stream = assembly.GetManifestResourceStream(r);
+					if (stream is null)
+						return string.Empty;
+					using var reader = new StreamReader(stream);
+					return reader.ReadToEnd();
+				}
+			);
+	}
+
+	public IconsRole(string role, string content, InlineProcessor processor) : base(role, content)
+	{
+
+		if (IconMap.TryGetValue(content, out var svg))
+		{
+			Svg = svg;
+			Name = content;
+		}
+		else
+			processor.EmitError(this, Role.Length + content.Length, $"Unknown icon: {content}");
+	}
+
+	public string? Name { get; }
+	public string? Svg { get; }
+}
+
+public partial class IconParser : RoleParser<IconsRole>
+{
+	[GeneratedRegex(@"\{icon\}`([^`]+)`", RegexOptions.Compiled)]
+	public static partial Regex IconRegex();
+
+	protected override IconsRole CreateRole(string role, string content, InlineProcessor parserContext) =>
+		new(role, content, parserContext);
+
+	protected override bool Matches(ReadOnlySpan<char> role) => role is "{icon}";
+}

src/Elastic.Markdown/Myst/Roles/Icons/IconRoleRenderer.cs

@@ -0,0 +1,41 @@
+// 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.Diagnostics.CodeAnalysis;
+using Markdig;
+using Markdig.Parsers.Inlines;
+using Markdig.Renderers;
+using Markdig.Renderers.Html;
+using Markdig.Renderers.Html.Inlines;
+
+namespace Elastic.Markdown.Myst.Roles.Icons;
+
+public class IconRoleHtmlRenderer : HtmlObjectRenderer<IconsRole>
+{
+
+	[SuppressMessage("Reliability", "CA2012:Use ValueTasks correctly")]
+	protected override void Write(HtmlRenderer renderer, IconsRole role)
+	{
+		_ = renderer.Write($"<span aria-label=\"Icon for {role.Name}\" class=\"icon icon-{role.Name}\">");
+		_ = renderer.Write(role.Svg);
+		_ = renderer.Write("</span>");
+	}
+}
+
+public static class InlineAppliesToExtensions
+{
+	public static MarkdownPipelineBuilder UseInlineIcons(this MarkdownPipelineBuilder pipeline)
+	{
+		pipeline.Extensions.AddIfNotAlready<InlineIconExtension>();
+		return pipeline;
+	}
+}
+
+public class InlineIconExtension : IMarkdownExtension
+{
+	public void Setup(MarkdownPipelineBuilder pipeline) => _ = pipeline.InlineParsers.InsertBefore<CodeInlineParser>(new IconParser());
+
+	public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer) =>
+		renderer.ObjectRenderers.InsertBefore<CodeInlineRenderer>(new IconRoleHtmlRenderer());
+}