Merge pull request 'docs(site): use real Gitea logo for header social link' (#106) from feat-starlight-gitea-icon into main

Reviewed-on: #106

docs/site/.gitignore

@@ -3,6 +3,9 @@ dist/
 # generated types
 .astro/
 
+# starlight-plugin-icons safelist cache
+.starlight-icons/
+
 # dependencies
 node_modules/
 

docs/site/README.md

@@ -26,6 +26,18 @@ The [`starlight-llms-txt`](https://www.npmjs.com/package/starlight-llms-txt)
 plugin emits `llms.txt`, `llms-full.txt`, and `llms-small.txt` alongside the
 built pages — no configuration needed, it just walks the generated content.
 
+## Icons
+
+[`starlight-plugin-icons`](https://docs.rettend.me/starlight-plugin-icons)
++ [UnoCSS](https://unocss.dev) (`uno.config.ts`) render icons from any
+[Iconify](https://icones.js.org) set as `i-<collection>:<name>` classes.
+The Gitea link in the header uses it (see
+`src/components/starlight/SocialIcons.astro`) to show the real Gitea logo
+instead of Starlight's generic `code-branch` icon. Sidebar (`sidebar:
+true`) and codeblock (`codeblock: true`) icon support are wired up in
+`astro.config.mjs` but unused so far — see the plugin docs for the
+`icon:` sidebar syntax if you want to add them.
+
 ## Development
 
 ```fish title="local dev server"

docs/site/astro.config.mjs

@@ -1,5 +1,6 @@
 import { defineConfig } from 'astro/config';
-import starlight from '@astrojs/starlight';
+import UnoCSS from 'unocss/astro';
+import Icons from 'starlight-plugin-icons';
 import starlightLinksValidator from 'starlight-links-validator';
 import starlightCatppuccin from '@catppuccin/starlight';
 import starlightLlmsTxt from 'starlight-llms-txt';
@@ -9,7 +10,12 @@ export default defineConfig({
   prerenderConflictBehavior: 'ignore',
   site: 'https://fish.rootiest.fyi',
   integrations: [
-    starlight({
+    UnoCSS(),
+    ...Icons({
+      sidebar: true,
+      codeblock: true,
+      extractSafelist: true,
+      starlight: {
         title: 'Rootiest Fish Config',
         description: 'Reference manual for the rootiest fish configuration.',
         favicon: '/favicon.svg',
@@ -23,6 +29,9 @@ export default defineConfig({
             href: 'https://git.rootiest.dev/rootiest/fish-config',
           },
         ],
+        components: {
+          SocialIcons: './src/components/starlight/SocialIcons.astro',
+        },
         head: [
           {
             tag: 'script',
@@ -48,6 +57,7 @@ export default defineConfig({
           },
         },
         sidebar,
+      },
     }),
   ],
 });

docs/site/package.json

@@ -12,9 +12,13 @@
   "dependencies": {
     "@astrojs/starlight": "^0.41.4",
     "@catppuccin/starlight": "^2.1.0",
+    "@iconify-json/pajamas": "^1.2.15",
+    "@unocss/astro": "^66.7.5",
     "astro": "^7.0.2",
     "sharp": "^0.35.3",
     "starlight-links-validator": "^0.25.2",
-    "starlight-llms-txt": "^0.11.0"
+    "starlight-llms-txt": "^0.11.0",
+    "starlight-plugin-icons": "^1.1.6",
+    "unocss": "^66.7.5"
   }
 }

docs/site/src/components/starlight/SocialIcons.astro

@@ -0,0 +1,46 @@
+---
+import config from 'virtual:starlight/user-config';
+import { Icon } from '@astrojs/starlight/components';
+
+// Maps a social link's `label` to a UnoCSS iconify icon class, letting a
+// link use an icon outside Starlight's built-in set (e.g. a real Gitea
+// logo instead of the generic `code-branch` icon).
+const customIcons: Record<string, string> = {
+  Gitea: 'i-pajamas:gitea',
+};
+
+const links = config.social || [];
+---
+
+{
+  links.length > 0 && (
+    <>
+      {links.map(({ label, href, icon }) => {
+        const customIcon = customIcons[label];
+        return (
+          <a href={href} rel="me" class="sl-flex">
+            <span class="sr-only">{label}</span>
+            {customIcon ? <span class={`social-icon ${customIcon}`} aria-hidden="true" /> : <Icon name={icon} />}
+          </a>
+        );
+      })}
+    </>
+  )
+}
+
+<style>
+  @layer starlight.core {
+    a {
+      color: var(--sl-color-text-accent);
+      padding: 0.5em;
+      margin: -0.5em;
+    }
+    a:hover {
+      color: var(--sl-color-white);
+    }
+    .social-icon {
+      width: 1em;
+      height: 1em;
+    }
+  }
+</style>

docs/site/uno.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'unocss';
+import { presetStarlightIcons } from 'starlight-plugin-icons/uno';
+
+export default defineConfig({
+  presets: [presetStarlightIcons()],
+});