Add tag descriptions with hover tooltips (#229)

* Add tag descriptions with hover tooltips

Introduce a centralized tag registry (src/content/tags.yaml) with descriptions for all 13 content tags. Add a new tags content collection with custom YAML loader. Enhance the Tag component to display descriptions in a tooltip when hovering over tags. Update blog pages to load and pass tag descriptions to the Tag component.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* Simplify tag tooltip to use title attribute

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: just-be-dev

src/components/Tag.astro

@@ -5,15 +5,17 @@ interface Props {
   count?: number;
   url?: string;
   class?: string;
+  description?: string;
 }
 
-const { id, tag, count, url = "/blog", class: className } = Astro.props;
+const { id, tag, count, url = "/blog", class: className, description } = Astro.props;
 const tagUrl = `${url}?tag=${encodeURIComponent(tag)}`;
 ---
 
 <a
   id={id}
   href={tagUrl}
+  title={description}
   class:list={[
     "bg-2 text-accent hocus:bg-0 hocus:invert group flex items-center outline-none font-medium border-2 border-fg-0",
     className,

src/content.config.ts

@@ -13,6 +13,8 @@ import {
   urlsSchema,
   redirectsSchema,
   redirectsFileSchema,
+  tagEntrySchema,
+  tagsFileSchema,
 } from "./content/schemas";
 
 const blog = defineCollection({
@@ -103,6 +105,30 @@ const redirects = defineCollection({
   schema: redirectsSchema,
 });
 
+const tags = defineCollection({
+  loader: {
+    name: "tags-loader",
+    load: ({ store, logger }) => {
+      logger.info("Loading tags");
+
+      const tagsPath = join(process.cwd(), "src/content/tags.yaml");
+      const tagsContent = readFileSync(tagsPath, "utf-8");
+      const rawData = loadYAML(tagsContent);
+      const data = tagsFileSchema.parse(rawData);
+
+      for (const tag of data.tags) {
+        store.set({
+          id: tag.name,
+          data: { description: tag.description },
+        });
+      }
+
+      logger.info(`Loaded ${data.tags.length} tags`);
+    },
+  },
+  schema: tagEntrySchema,
+});
+
 export const collections = {
   blog,
   projects,
@@ -112,4 +138,5 @@ export const collections = {
   talks,
   urls,
   redirects,
+  tags,
 };

src/content/schemas.ts

@@ -90,3 +90,17 @@ export const redirectsFileSchema = z.object({
     }),
   ),
 });
+
+export const tagEntrySchema = z.object({
+  description: z.string(),
+});
+
+// Schema for the tags YAML file structure
+export const tagsFileSchema = z.object({
+  tags: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string(),
+    }),
+  ),
+});

src/content/tags.yaml

@@ -0,0 +1,39 @@
+tags:
+  - name: ai
+    description: Artificial intelligence, large language models, and machine learning
+
+  - name: api
+    description: API design, standards, and integration patterns
+
+  - name: claude
+    description: Anthropic's Claude AI assistant and related tooling
+
+  - name: data
+    description: Data management, storage, and processing
+
+  - name: infrastructure
+    description: Backend systems, deployment, and platform engineering
+
+  - name: interoperability
+    description: Standards and protocols for system-to-system communication
+
+  - name: mcp
+    description: Model Context Protocol, Anthropic's open protocol for AI tool integration
+
+  - name: meta
+    description: Posts about this site, writing, or process
+
+  - name: privacy
+    description: Data privacy, self-sovereignty, and personal data control
+
+  - name: recurse
+    description: Recurse Center experiences and community
+
+  - name: schema
+    description: Data schemas, type systems, and validation
+
+  - name: self-hosting
+    description: Running your own services and infrastructure
+
+  - name: web
+    description: Web development, browsers, and the open web

src/pages/blog/[slug].astro

@@ -9,6 +9,9 @@ import MDContent from "@/components/MDContent.astro";
 import Layout from "@/layouts/Layout.astro";
 import { Code } from "@/utils/code";
 
+const tagEntries = await getCollection("tags");
+const tagDescriptions = new Map(tagEntries.map((t) => [t.id, t.data.description]));
+
 export async function getStaticPaths() {
   const posts = await getCollection("blog");
   return posts.map((post) => ({
@@ -52,7 +55,7 @@ const code = post.data.code ? post.data.code.toUpperCase() : Code.fromId(post.id
               <div class="tag-list hidden absolute right-0 top-full pt-1 z-10">
                 <div class="flex flex-wrap gap-2 bg-1 px-2 py-1">
                   {post.data.tags.map((tag) => (
-                    <Tag tag={tag} url="/blog" />
+                    <Tag tag={tag} url="/blog" description={tagDescriptions.get(tag)} />
                   ))}
                 </div>
               </div>

src/pages/blog/index.astro

@@ -7,6 +7,9 @@ import type { LinkListItem } from "@/components/LinkList.astro";
 import Layout from "@/layouts/Layout.astro";
 import { Code } from "@/utils/code";
 
+const tagEntries = await getCollection("tags");
+const tagDescriptions = new Map(tagEntries.map((t) => [t.id, t.data.description]));
+
 export const prerender = false;
 
 // Get selected tag from query params
@@ -64,11 +67,14 @@ const linkListItems: LinkListItem[] = posts.map((post) => {
               url="/blog"
               class="invert"
               id="selected-tag"
+              description={tagDescriptions.get(selectedTag)}
             />
             <Button shortcut="c" label="clear" href="/blog" />
           </>
         ) : (
-          sortedTags.map(({ tag, count }) => <Tag tag={tag} count={count} url="/blog" />)
+          sortedTags.map(({ tag, count }) => (
+            <Tag tag={tag} count={count} url="/blog" description={tagDescriptions.get(tag)} />
+          ))
         )
       }
     </div>