feat(theme): friendly social link tooltips instead of raw icon names

Social links previously used the raw icon name (e.g. "fontawesome/solid/rss")
as their hover tooltip, which is meaningless to visitors. Add a `social_label`
template helper that derives a human-friendly label from an icon name — mapping
well-known brands/terms to proper casing (rss -> "RSS Feed", x-twitter ->
"X (Twitter)", globe -> "Website", ...) and title-casing the last path segment
for anything else (some/cool-thing -> "Cool Thing").

The header and footer social partials now resolve each link's label as: an
explicit `name` field on the entry (new, optional) first, otherwise the derived
`social_label`. The resolved value is used for both `title` and `aria-label`,
improving usability and accessibility.

Adds tests for the curated map, title-case fallback, and blank input, and
documents `name` / `social_label` under the theme reference.

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

Author: Netdocs

docs-site/docs/reference/theme.md

@@ -210,15 +210,17 @@ Material's Jinja partials map fairly directly onto Scriban. The common substitut
 | `{{ config.site_name }}` | `{{ config.site_name }}` (unchanged) |
 
 Use the trim markers `{{~` / `~}}` to strip surrounding whitespace, and the theme helpers
-(`social_icon`, `strip_slash`, `base_url`) instead of Material's Jinja filters. For example,
-an override that renders the configured social links in the header:
+(`social_icon`, `social_label`, `strip_slash`, `base_url`) instead of Material's Jinja filters.
+For example, an override that renders the configured social links in the header:
 
 ```html
 {{~ if extra.social ~}}
 <div class="header-social">
   {{~ for link in extra.social ~}}
+  {{~ label = link.name ~}}
+  {{~ if !label || (label | string.strip) == "" ~}}{{~ label = social_label link.icon ~}}{{~ end ~}}
   <a href="{{ link.link }}" class="md-social__link md-header__button md-icon"
-     title="{{ link.icon }}" target="_blank" rel="noopener">{{ social_icon link.icon }}</a>
+     title="{{ label }}" aria-label="{{ label }}" target="_blank" rel="noopener">{{ social_icon link.icon }}</a>
   {{~ end ~}}
 </div>
 {{~ end ~}}
@@ -227,7 +229,9 @@ an override that renders the configured social links in the header:
 ## Social links & icons
 
 Configure the links shown in the header and footer under `extra.social`. Each entry has an
-`icon` name (Material/FontAwesome-style, e.g. `fontawesome/brands/github`) and a `link`:
+`icon` name (Material/FontAwesome-style, e.g. `fontawesome/brands/github`) and a `link`. You
+can optionally add a `name` to control the hover tooltip / `aria-label`; when omitted, a
+friendly label is derived automatically from the icon (see [Tooltips & labels](#tooltips--labels)):
 
 ```json
 {
@@ -236,7 +240,7 @@ Configure the links shown in the header and footer under `extra.social`. Each en
       "social": [
         { "icon": "fontawesome/brands/github", "link": "https://github.com/you/repo" },
         { "icon": "fontawesome/brands/mastodon", "link": "https://fosstodon.org/@you" },
-        { "icon": "material/rss", "link": "feed_rss_created.xml" }
+        { "icon": "material/rss", "link": "feed_rss_created.xml", "name": "Subscribe via RSS" }
       ]
     }
   }
@@ -260,6 +264,23 @@ substring, so both the Material (`material/github`) and FontAwesome
 | `mail` / `email` / `envelope` | Email |
 | *(anything else)* | Globe (generic link) |
 
+### Tooltips & labels
+
+Each social link needs readable hover text for usability and accessibility. The theme resolves
+the label in this order:
+
+1. An explicit `name` on the entry (e.g. `"name": "Subscribe via RSS"`) — always wins.
+2. Otherwise the `social_label` helper derives a friendly name from the icon: it takes the last
+   path segment and maps well-known ones to proper casing — `fontawesome/solid/rss` → **RSS
+   Feed**, `fontawesome/brands/x-twitter` → **X (Twitter)**, `fontawesome/brands/linkedin` →
+   **LinkedIn**, `fontawesome/solid/globe` → **Website**, and so on.
+3. Anything unrecognised is title-cased from its last segment, so `simple/my-service` still
+   reads as **My Service** rather than the raw icon path.
+
+The resolved label is used for both the `title` (tooltip) and `aria-label`. Set an explicit
+`name` whenever the icon alone is ambiguous — for example a generic globe that actually points
+to your main website.
+
 ### Custom icons
 
 Add or override glyphs without editing the theme by supplying `extra.social_icons` — a map

src/Netdocs.Core/Templating/ThemeTemplateLoader.cs

@@ -45,6 +45,7 @@ public static void Register(ScriptObject globals, IDictionary<string, object?>?
 
         var overrides = ExtractIconOverrides(model);
         globals.Import("social_icon", (string? name) => SocialIcon(name ?? "", overrides));
+        globals.Import("social_label", static (string? name) => SocialLabel(name ?? ""));
         globals.Import("nav_icon", (string? name) => NavIcon(name ?? "", overrides));
 
         var versioner = (model is not null && model.TryGetValue("asset_versioner", out var v) ? v as AssetVersioner : null)
@@ -101,6 +102,82 @@ private static string SocialIcon(string name, IReadOnlyDictionary<string, string
     private static string Svg(string path) =>
         $"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"{path}\"/></svg>";
 
+    /// <summary>
+    /// Turns an icon name into a human-friendly label for tooltips / <c>aria-label</c>s
+    /// (e.g. <c>fontawesome/solid/rss</c> → "RSS Feed", <c>fontawesome/brands/x-twitter</c> →
+    /// "X (Twitter)"). Falls back to a title-cased version of the last path segment for anything
+    /// not in the curated map, so unknown icons still read nicely (e.g. <c>some/cool-thing</c> →
+    /// "Cool Thing"). Sites can always override this per-link via a <c>name</c> field in config.
+    /// </summary>
+    public static string SocialLabel(string name)
+    {
+        if (string.IsNullOrWhiteSpace(name)) return string.Empty;
+
+        // Use the last path segment (mkdocs-style names look like "fontawesome/brands/github").
+        var seg = name.Trim().Trim('/');
+        var slash = seg.LastIndexOf('/');
+        if (slash >= 0) seg = seg[(slash + 1)..];
+        var key = seg.ToLowerInvariant();
+
+        return key switch
+        {
+            "github" => "GitHub",
+            "gitlab" => "GitLab",
+            "bitbucket" => "Bitbucket",
+            "discord" => "Discord",
+            "slack" => "Slack",
+            "reddit" => "Reddit",
+            "rss" or "feed" or "square-rss" => "RSS Feed",
+            "globe" or "link" or "house" or "home" or "web" or "earth" or "language" => "Website",
+            "x-twitter" or "twitter" or "x" => "X (Twitter)",
+            "mastodon" => "Mastodon",
+            "bluesky" or "butterfly" => "Bluesky",
+            "linkedin" or "linkedin-in" => "LinkedIn",
+            "youtube" or "youtube-play" => "YouTube",
+            "facebook" or "facebook-f" => "Facebook",
+            "instagram" => "Instagram",
+            "threads" => "Threads",
+            "tiktok" => "TikTok",
+            "twitch" => "Twitch",
+            "telegram" => "Telegram",
+            "whatsapp" => "WhatsApp",
+            "signal" => "Signal",
+            "matrix" or "matrix-org" => "Matrix",
+            "envelope" or "email" or "mail" or "at" => "Email",
+            "phone" => "Phone",
+            "stack-overflow" or "stackoverflow" => "Stack Overflow",
+            "hacker-news" or "hackernews" or "y-combinator" => "Hacker News",
+            "docker" => "Docker",
+            "kubernetes" => "Kubernetes",
+            "npm" => "npm",
+            "nuget" => "NuGet",
+            "steam" => "Steam",
+            "patreon" => "Patreon",
+            "ko-fi" => "Ko-fi",
+            "paypal" => "PayPal",
+            "medium" => "Medium",
+            "dev" or "dev-to" => "DEV Community",
+            "keybase" => "Keybase",
+            "spotify" => "Spotify",
+            "soundcloud" => "SoundCloud",
+            _ => TitleCase(key),
+        };
+    }
+
+    /// <summary>Title-cases a dash/underscore/space separated token: "cool-thing" → "Cool Thing".</summary>
+    private static string TitleCase(string value)
+    {
+        var words = value.Split(['-', '_', ' '], StringSplitOptions.RemoveEmptyEntries);
+        for (var i = 0; i < words.Length; i++)
+        {
+            var w = words[i];
+            words[i] = w.Length == 1 ? char.ToUpperInvariant(w[0]).ToString()
+                                     : char.ToUpperInvariant(w[0]) + w[1..];
+        }
+        return words.Length == 0 ? value : string.Join(' ', words);
+    }
+
+
     /// <summary>
     /// Resolves a nav/badge icon to inline markup. Resolution order: custom <c>extra.social_icons</c>
     /// override → curated Material glyph (<see cref="MaterialIcons"/>) → brand glyph

src/Netdocs.Theme.Material/templates/partials/footer.html

@@ -34,7 +34,9 @@
       {{~ if extra.social ~}}
       <div class="md-social">
         {{~ for link in extra.social ~}}
-        <a href="{{ link.link }}" target="_blank" rel="noopener" title="{{ link.icon }}" class="md-social__link">{{ social_icon link.icon }}</a>
+        {{~ label = link.name ~}}
+        {{~ if !label || (label | string.strip) == "" ~}}{{~ label = social_label link.icon ~}}{{~ end ~}}
+        <a href="{{ link.link }}" target="_blank" rel="noopener" title="{{ label }}" aria-label="{{ label }}" class="md-social__link">{{ social_icon link.icon }}</a>
         {{~ end ~}}
       </div>
       {{~ end ~}}

src/Netdocs.Theme.Material/templates/partials/social.html

@@ -1,17 +1,22 @@
 {{~ # ---------------------------------------------------------------------------
    # partials/social.html — Social links shown at the right of the header.
    #
-   # Data:  `extra.social` in your config — a list of { icon, link } entries.
+   # Data:  `extra.social` in your config — a list of { icon, link, name? } entries.
    #        `social_icon <name>` resolves an icon name (e.g. "fontawesome/brands/github")
    #        to an inline SVG.
+   #        `social_label <name>` derives a friendly tooltip/label from the icon name
+   #        (e.g. "fontawesome/solid/rss" -> "RSS Feed"). Set an explicit `name` on the
+   #        entry to override the auto-derived label.
    #
    # Override: drop a file at `<custom_dir>/partials/social.html` to change how the
    #        social links render, without touching the header. Return nothing to hide them.
    # --------------------------------------------------------------------------- ~}}
 {{~ if extra.social ~}}
 <nav class="md-header__social" aria-label="Social">
   {{~ for link in extra.social ~}}
-  <a href="{{ link.link }}" class="md-header__button md-icon" title="{{ link.icon }}" target="_blank" rel="noopener">{{ social_icon link.icon }}</a>
+  {{~ label = link.name ~}}
+  {{~ if !label || (label | string.strip) == "" ~}}{{~ label = social_label link.icon ~}}{{~ end ~}}
+  <a href="{{ link.link }}" class="md-header__button md-icon" title="{{ label }}" aria-label="{{ label }}" target="_blank" rel="noopener">{{ social_icon link.icon }}</a>
   {{~ end ~}}
 </nav>
 {{~ end ~}}

tests/Netdocs.Core.Tests/SocialIconTests.cs

@@ -59,4 +59,28 @@ public void CustomIconOverrideIsUsed()
         var html = Render("fontawesome/brands/bluesky", extra);
         Assert.Contains("d=\"M1 2 3 4\"", html);
     }
+
+    [Theory]
+    [InlineData("fontawesome/brands/github", "GitHub")]
+    [InlineData("fontawesome/brands/discord", "Discord")]
+    [InlineData("fontawesome/brands/reddit", "Reddit")]
+    [InlineData("fontawesome/solid/rss", "RSS Feed")]
+    [InlineData("fontawesome/solid/globe", "Website")]
+    [InlineData("fontawesome/brands/x-twitter", "X (Twitter)")]
+    [InlineData("fontawesome/brands/linkedin", "LinkedIn")]
+    [InlineData("fontawesome/brands/youtube", "YouTube")]
+    [InlineData("material/email", "Email")]
+    public void SocialLabelMapsKnownIconsToFriendlyNames(string icon, string expected)
+        => Assert.Equal(expected, TemplateFunctions.SocialLabel(icon));
+
+    [Theory]
+    [InlineData("some/cool-thing", "Cool Thing")]
+    [InlineData("simple/my_service", "My Service")]
+    [InlineData("bare-name", "Bare Name")]
+    public void SocialLabelTitleCasesUnknownIcons(string icon, string expected)
+        => Assert.Equal(expected, TemplateFunctions.SocialLabel(icon));
+
+    [Fact]
+    public void SocialLabelReturnsEmptyForBlank()
+        => Assert.Equal("", TemplateFunctions.SocialLabel("  "));
 }