Resolve icon shortcodes to inline SVG + style grid cards

Adds mkdocs-material icon shortcode support so :material-*:, :octicons-*:
and :fontawesome-*: resolve to inline SVG instead of rendering as literal
text. The icon set (Material Design Icons, Octicons, FontAwesome Free -
~10k icons) ships as a gzipped JSON embedded resource, decompressed once
on first use via IconRegistry. TwemojiExtension gains an IconInline parser
and IconRenderer that carry attr_list classes (e.g. { .lg .middle }).

Also styles `.grid.cards` (md_in_html card grids) and `.twemoji` icon
sizing so grid-card landing pages render correctly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

src/Netdocs.Core/Markdown/Emoji/IconRegistry.cs

@@ -0,0 +1,61 @@
+using System.IO.Compression;
+using System.Reflection;
+using System.Text.Json;
+
+namespace Netdocs.Core.Markdown.Emoji;
+
+/// <summary>
+/// Resolves mkdocs-material icon shortcodes (<c>:material-*:</c>, <c>:octicons-*:</c>,
+/// <c>:fontawesome-*:</c>) to inline SVG. The icon set (Material Design Icons, Octicons,
+/// FontAwesome Free) is bundled as a gzipped JSON embedded resource and decompressed
+/// once on first use.
+/// </summary>
+public static class IconRegistry
+{
+    public sealed record Icon(string Path, string ViewBox);
+
+    private static readonly Lazy<IReadOnlyDictionary<string, Icon>> Icons = new(Load);
+
+    /// <summary>Number of icons available (for diagnostics/tests).</summary>
+    public static int Count => Icons.Value.Count;
+
+    /// <summary>Look up an icon by shortcode name (without the surrounding colons),
+    /// e.g. <c>material-application</c> or <c>octicons-arrow-right-24</c>.</summary>
+    public static Icon? Get(string name) =>
+        Icons.Value.TryGetValue(name, out var icon) ? icon : null;
+
+    /// <summary>True when the name looks like an icon shortcode we might resolve.</summary>
+    public static bool IsIconName(string name) =>
+        name.StartsWith("material-", StringComparison.Ordinal)
+        || name.StartsWith("octicons-", StringComparison.Ordinal)
+        || name.StartsWith("fontawesome-", StringComparison.Ordinal)
+        || name.StartsWith("simple-", StringComparison.Ordinal);
+
+    /// <summary>Render an icon as an inline SVG string, or null when unknown.</summary>
+    public static string? RenderSvg(string name)
+    {
+        var icon = Get(name);
+        if (icon is null) return null;
+        return $"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"{icon.ViewBox}\"><path d=\"{icon.Path}\"></path></svg>";
+    }
+
+    private static IReadOnlyDictionary<string, Icon> Load()
+    {
+        var assembly = typeof(IconRegistry).Assembly;
+        using var stream = assembly.GetManifestResourceStream("icons/icons.json.gz");
+        if (stream is null)
+            return new Dictionary<string, Icon>();
+
+        using var gz = new GZipStream(stream, CompressionMode.Decompress);
+        using var doc = JsonDocument.Parse(gz);
+
+        var map = new Dictionary<string, Icon>(StringComparer.Ordinal);
+        foreach (var prop in doc.RootElement.EnumerateObject())
+        {
+            var p = prop.Value.GetProperty("p").GetString() ?? "";
+            var v = prop.Value.GetProperty("v").GetString() ?? "0 0 24 24";
+            map[prop.Name] = new Icon(p, v);
+        }
+        return map;
+    }
+}

src/Netdocs.Core/Markdown/Emoji/TwemojiExtension.cs

@@ -17,10 +17,19 @@ public sealed class TwemojiInline : LeafInline
     public required string Shortcode { get; init; }
 }
 
+/// <summary>Inline node for an icon shortcode (<c>:material-*:</c> etc.) resolved to inline SVG.</summary>
+public sealed class IconInline : LeafInline
+{
+    public required string Name { get; init; }
+    public required string Svg { get; init; }
+}
+
 /// <summary>
 /// Parses <c>:shortcode:</c> emoji using Markdig's built-in shortcode table and emits a
 /// <see cref="TwemojiInline"/> so it can be rendered as a Twemoji SVG image (mirrors
-/// mkdocs-material's <c>pymdownx.emoji</c> + twemoji generator).
+/// mkdocs-material's <c>pymdownx.emoji</c> + twemoji generator). Shortcodes that aren't
+/// emoji but resolve to a bundled icon (<c>:material-*:</c>, <c>:octicons-*:</c>,
+/// <c>:fontawesome-*:</c>) emit an <see cref="IconInline"/> with inline SVG.
 /// </summary>
 public sealed class TwemojiInlineParser : InlineParser
 {
@@ -48,19 +57,63 @@ public override bool Match(InlineProcessor processor, ref StringSlice slice)
         if (p > end || text[p] != ':') return false;
 
         var shortcode = text.Substring(start, p - start + 1);
-        if (!Map.TryGetValue(shortcode, out var unicode)) return false;
-
         var startPosition = processor.GetSourcePosition(start, out var line, out var column);
-        processor.Inline = new TwemojiInline
+
+        if (Map.TryGetValue(shortcode, out var unicode))
         {
-            Unicode = unicode,
-            Shortcode = shortcode,
-            Span = new(startPosition, processor.GetSourcePosition(p)),
-            Line = line,
-            Column = column,
-        };
-        slice.Start = p + 1;
-        return true;
+            processor.Inline = new TwemojiInline
+            {
+                Unicode = unicode,
+                Shortcode = shortcode,
+                Span = new(startPosition, processor.GetSourcePosition(p)),
+                Line = line,
+                Column = column,
+            };
+            slice.Start = p + 1;
+            return true;
+        }
+
+        // Not a Unicode emoji — try the bundled icon set (material/octicons/fontawesome).
+        var name = shortcode.Trim(':');
+        if (IconRegistry.IsIconName(name) && IconRegistry.RenderSvg(name) is { } svg)
+        {
+            processor.Inline = new IconInline
+            {
+                Name = name,
+                Svg = svg,
+                Span = new(startPosition, processor.GetSourcePosition(p)),
+                Line = line,
+                Column = column,
+            };
+            slice.Start = p + 1;
+            return true;
+        }
+
+        return false;
+    }
+}
+
+/// <summary>Renders an <see cref="IconInline"/> as an inline SVG wrapped in a
+/// <c>&lt;span class="twemoji"&gt;</c>, carrying any attr_list classes/attributes
+/// (e.g. <c>{ .lg .middle }</c>) so mkdocs-material icon usage renders identically.</summary>
+public sealed class IconRenderer : HtmlObjectRenderer<IconInline>
+{
+    protected override void Write(HtmlRenderer renderer, IconInline obj)
+    {
+        if (!renderer.EnableHtmlForInline) return;
+
+        var attrs = obj.TryGetAttributes();
+        renderer.Write("<span class=\"twemoji");
+        if (attrs?.Classes is { Count: > 0 } classes)
+            foreach (var c in classes)
+                renderer.Write(' ').Write(c);
+        renderer.Write('"');
+        if (!string.IsNullOrEmpty(attrs?.Id))
+            renderer.Write(" id=\"").Write(attrs!.Id).Write('"');
+        if (attrs?.Properties is { Count: > 0 } props)
+            foreach (var prop in props)
+                renderer.Write(' ').Write(prop.Key).Write("=\"").Write(prop.Value ?? "").Write('"');
+        renderer.Write('>').Write(obj.Svg).Write("</span>");
     }
 }
 
@@ -119,7 +172,12 @@ public void Setup(MarkdownPipelineBuilder pipeline)
 
     public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
     {
-        if (renderer is HtmlRenderer html && !html.ObjectRenderers.Contains<TwemojiRenderer>())
-            html.ObjectRenderers.Insert(0, new TwemojiRenderer(_baseUrl));
+        if (renderer is HtmlRenderer html)
+        {
+            if (!html.ObjectRenderers.Contains<TwemojiRenderer>())
+                html.ObjectRenderers.Insert(0, new TwemojiRenderer(_baseUrl));
+            if (!html.ObjectRenderers.Contains<IconRenderer>())
+                html.ObjectRenderers.Insert(0, new IconRenderer());
+        }
     }
 }

src/Netdocs.Core/Markdown/Emoji/data/icons.json.gz

@@ -24,4 +24,14 @@
       <LogicalName>theme/assets/%(RecursiveDir)%(Filename)%(Extension)</LogicalName>
     </EmbeddedResource>
   </ItemGroup>
+  <!--
+    Bundled icon set (Material Design Icons, Octicons, FontAwesome Free) used to
+    resolve `:material-*:` / `:octicons-*:` / `:fontawesome-*:` shortcodes to inline
+    SVG, mirroring mkdocs-material. Stored gzipped (~1.3MB) and decompressed lazily.
+  -->
+  <ItemGroup>
+    <EmbeddedResource Include="Markdown\Emoji\data\icons.json.gz">
+      <LogicalName>icons/icons.json.gz</LogicalName>
+    </EmbeddedResource>
+  </ItemGroup>
 </Project>

src/Netdocs.Core/Netdocs.Core.csproj

@@ -343,6 +343,78 @@ body {
 }
 
 
+/* ---------------------------------------------------------------------------
+   Grid cards (`<div class="grid cards" markdown>` + a bullet list, the
+   mkdocs-material landing-page pattern). Lays the list items out as responsive
+   cards and styles inline icons (`:material-*:{ .lg .middle }`).
+   --------------------------------------------------------------------------- */
+.md-typeset .grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+  gap: 0.8rem;
+  margin: 1em 0;
+}
+
+.md-typeset .grid.cards > ul {
+  display: contents;
+}
+
+.md-typeset .grid.cards > ul > li,
+.md-typeset .grid > .card {
+  margin: 0;
+  padding: 0.8rem;
+  border: 0.05rem solid var(--md-default-fg-color--lightest);
+  border-radius: 0.2rem;
+  box-shadow: var(--nd-code-shadow);
+  transition: border-color 0.25s, box-shadow 0.25s;
+}
+
+.md-typeset .grid.cards > ul > li:hover,
+.md-typeset .grid > .card:hover {
+  border-color: var(--md-accent-fg-color);
+  box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.1);
+}
+
+.md-typeset .grid.cards > ul > li > hr {
+  margin: 0.6rem 0;
+}
+
+.md-typeset .grid.cards > ul > li > :first-child {
+  margin-top: 0;
+}
+
+.md-typeset .grid.cards > ul > li > :last-child {
+  margin-bottom: 0;
+}
+
+/* Inline icons emitted from `:material-*:` / `:octicons-*:` / `:fontawesome-*:`. */
+.md-typeset .twemoji {
+  display: inline-flex;
+  height: 1.125em;
+  vertical-align: text-top;
+}
+
+.md-typeset .twemoji svg {
+  width: 1.125em;
+  height: 1.125em;
+  fill: currentColor;
+}
+
+.md-typeset .twemoji.lg svg {
+  width: 2.2em;
+  height: 2.2em;
+}
+
+.md-typeset .twemoji.xl svg {
+  width: 3em;
+  height: 3em;
+}
+
+.md-typeset .twemoji.middle {
+  vertical-align: middle;
+}
+
+
 /* ---------------------------------------------------------------------------
    Calculator plugin (```calc fences -> interactive forms). Styles the input
    grid and the computed-output cards. Uses Material CSS custom properties so

src/Netdocs.Theme.Material/assets/netdocs.css

@@ -120,6 +120,36 @@ public void Emoji_RendersTwemojiImage()
         Assert.Contains("title=\":smile:\"", html);
     }
 
+    [Fact]
+    public void Icons_RegistryLoadsBundledSet()
+    {
+        // The embedded icon dataset should decompress and expose thousands of icons.
+        Assert.True(Netdocs.Core.Markdown.Emoji.IconRegistry.Count > 5000);
+        Assert.NotNull(Netdocs.Core.Markdown.Emoji.IconRegistry.Get("material-home"));
+        var svg = Netdocs.Core.Markdown.Emoji.IconRegistry.RenderSvg("material-home");
+        Assert.NotNull(svg);
+        Assert.Contains("<svg", svg);
+        Assert.Contains("<path", svg);
+    }
+
+    [Fact]
+    public void Icons_MaterialShortcodeRendersInlineSvg()
+    {
+        var html = Render("Launch :material-home: now\n");
+        Assert.Contains("class=\"twemoji", html);
+        Assert.Contains("<svg", html);
+        Assert.DoesNotContain(":material-home:", html); // shortcode fully resolved
+    }
+
+    [Fact]
+    public void Icons_ShortcodeCarriesAttrListClasses()
+    {
+        var html = Render("Big :material-home:{ .lg .middle } icon\n");
+        Assert.Contains("<svg", html);
+        Assert.Contains("lg", html);
+        Assert.Contains("middle", html);
+    }
+
     [Fact]
     public void Emoji_ZwjSequenceKeepsVariationSelector()
     {