@karaoke-cms/module-tags 0.11.2

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@karaoke-cms/module-tags",
+  "type": "module",
+  "version": "0.11.2",
+  "description": "Tags module for karaoke-cms — cross-collection tag index with per-tag RSS feeds",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pages/index": "./src/pages/index.astro",
+    "./pages/tag": "./src/pages/tag.astro",
+    "./pages/tag-rss": "./src/pages/tag-rss.ts"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "astro",
+    "cms",
+    "tags",
+    "rss",
+    "karaoke-cms"
+  ],
+  "dependencies": {
+    "@astrojs/rss": "^4.0.17"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0",
+    "@karaoke-cms/contracts": "^0.11.2",
+    "@karaoke-cms/astro": "^0.11.2"
+  },
+  "devDependencies": {
+    "astro": "^6.0.8",
+    "vitest": "^4.1.1",
+    "@karaoke-cms/contracts": "0.11.2",
+    "@karaoke-cms/astro": "0.11.2"
+  },
+  "scripts": {
+    "test": "vitest run test/module-tags.test.js"
+  }
+}

package/src/css-contract.ts

@@ -0,0 +1,12 @@
+import type { CssContract } from '@karaoke-cms/contracts';
+
+export const cssContract: CssContract = {
+  'tag-listing-header':  { description: 'Wrapper for the /tags page title + subtitle',             required: true  },
+  'tag-list':            { description: 'Ordered/unordered list of tag links on the index page',   required: true  },
+  'tag-count':           { description: 'Post count badge next to each tag name',                  required: false },
+  'tag-page-header':     { description: 'Wrapper for the /tags/[tag] page title + back link',      required: true  },
+  'tag-post-list':       { description: 'List of posts matching the current tag',                  required: true  },
+  'tag-post-date':       { description: 'Publication date on each tagged post item',               required: false },
+  'tag-post-collection': { description: 'Collection badge (Blog / Docs) on each post item',        required: false },
+  'tag-empty-state':     { description: 'Shown when a tag has no matching public entries',         required: false },
+};

package/src/index.ts

@@ -0,0 +1,50 @@
+import type { ModuleInstance } from '@karaoke-cms/contracts';
+import { cssContract } from './css-contract.js';
+
+export interface TagsConfig {
+  /** Mount path for the tags section. Default: '/tags'. */
+  mount?: string;
+  /** When false, tags routes are not injected. Default: true. */
+  enabled?: boolean;
+}
+
+/**
+ * Tags module — cross-collection tag index with per-tag RSS feeds.
+ *
+ * Aggregates tags from the blog collection and all active docs sections automatically.
+ * No explicit `sources` config required — mirrors current theme-default behavior.
+ *
+ * @example
+ * // karaoke.config.ts
+ * import { tags } from '@karaoke-cms/module-tags';
+ * modules: [blog(), docs(), tags()]
+ *
+ * // Custom mount:
+ * modules: [blog(), docs(), tags({ mount: '/topics' })]
+ */
+export function tags(config: TagsConfig = {}): ModuleInstance {
+  const rawMount = config.mount ?? '/tags';
+  if (!rawMount || rawMount === '/') {
+    throw new Error(
+      '[module-tags] mount cannot be "/" or empty. Pass a non-root path like "/tags".',
+    );
+  }
+  const mount = rawMount.replace(/\/$/, '');
+
+  return {
+    _type: 'module-instance',
+    id: 'tags',
+    mount,
+    enabled: config.enabled ?? true,
+    routes: [
+      { pattern: mount,                    entrypoint: '@karaoke-cms/module-tags/pages/index' },
+      { pattern: `${mount}/[tag]`,         entrypoint: '@karaoke-cms/module-tags/pages/tag' },
+      { pattern: `${mount}/[tag]/rss.xml`, entrypoint: '@karaoke-cms/module-tags/pages/tag-rss' },
+    ],
+    menuEntries: [{ id: 'tags', name: 'Tags', path: mount, section: 'main', weight: 30 }],
+    cssContract,
+    hasDefaultCss: false,
+    defaultCssPath: undefined,
+    scaffoldPages: undefined,
+  };
+}

package/src/pages/index.astro

@@ -0,0 +1,46 @@
+---
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+import { tagsMount } from 'virtual:karaoke-cms/tags-config';
+import { docsSections } from 'virtual:karaoke-cms/docs-sections';
+import { slugifyTag } from '../utils.js';
+
+// Auto-discover: always blog + all active docs sections
+const settled = await Promise.allSettled([
+  getCollection('blog', ({ data }) => data.publish === true),
+  ...docsSections.map(s => getCollection(s.collection as any, ({ data }) => data.publish === true)),
+]);
+const allEntries = settled.flatMap(r => r.status === 'fulfilled' ? r.value : []);
+
+// Count occurrences of each tag across all collections
+const counts = new Map<string, number>();
+for (const entry of allEntries) {
+  for (const tag of entry.data.tags ?? []) {
+    counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  }
+}
+
+const tags = [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+---
+
+<DefaultPage title={`Tags — ${siteTitle}`}>
+  <div class="listing-header">
+    <h1>Tags</h1>
+  </div>
+  {tags.length > 0 ? (
+    <ul class="tag-list">
+      {tags.map(([tag, count]) => (
+        <li>
+          <a href={`${tagsMount}/${slugifyTag(tag)}`}>{tag}</a>
+          <span class="tag-count">{count}</span>
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <div class="empty-state">
+      <p>No tags yet.</p>
+      <p>Tags are added to posts via the <code>tags</code> frontmatter field or by AI enrichment.</p>
+    </div>
+  )}
+</DefaultPage>

package/src/pages/tag-rss.ts

@@ -0,0 +1,77 @@
+/**
+ * Per-tag RSS feed endpoint.
+ *
+ * Route: /tags/[tag]/rss.xml  (or whatever mount was configured)
+ *
+ * NOTE: This uses injectRoute({ pattern: '${mount}/[tag]/rss.xml' }).
+ * The [tag] segment is populated by getStaticPaths in SSG mode.
+ * The tag param is a URL-safe slug (from slugifyTag); the original tag string
+ * is passed via props.originalTag for display and filtering.
+ */
+import rss from '@astrojs/rss';
+import { getCollection } from 'astro:content';
+import { siteTitle, siteDescription, blogMount } from 'virtual:karaoke-cms/config';
+import { docsSections } from 'virtual:karaoke-cms/docs-sections';
+import { slugifyTag, slugToTag } from '../utils.js';
+import type { APIRoute, GetStaticPaths } from 'astro';
+
+async function getAllEntries() {
+  const settled = await Promise.allSettled([
+    getCollection('blog', (e) => e.data.publish === true),
+    ...docsSections.map(s => getCollection(s.collection as any, (e) => e.data.publish === true)),
+  ]);
+  return settled.flatMap(r => r.status === 'fulfilled' ? r.value : []);
+}
+
+const mountByCollection: Record<string, string> = {
+  blog: blogMount,
+  ...Object.fromEntries(docsSections.map((s) => [s.collection, s.mount])),
+};
+
+function entryHref(entry: { collection: string; id: string }) {
+  const mount = mountByCollection[entry.collection];
+  return mount ? `${mount}/${entry.id}` : `/${entry.collection}/${entry.id}`;
+}
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const all = await getAllEntries();
+  const tags = new Set(all.flatMap(e => e.data.tags ?? []));
+  return [...tags].map(tag => ({
+    params: { tag: slugifyTag(tag) },
+    props: { originalTag: tag },
+  }));
+};
+
+export const GET: APIRoute = async ({ params, props, site }) => {
+  // RSS feeds require absolute URLs. site comes from Astro.site (set in astro.config.mjs).
+  if (!site) {
+    return new Response(
+      '<?xml version="1.0" encoding="UTF-8"?>' +
+      '<!-- RSS feeds require `site` to be configured in astro.config.mjs -->',
+      { status: 200, headers: { 'Content-Type': 'application/xml' } },
+    );
+  }
+
+  const all = await getAllEntries();
+
+  // Prefer originalTag passed from getStaticPaths; fall back to reverse slug lookup
+  const allTagStrings = [...new Set(all.flatMap(e => e.data.tags ?? []))];
+  const tag = (props as { originalTag?: string }).originalTag ?? slugToTag(params.tag!, allTagStrings);
+  if (!tag) return new Response('Not found', { status: 404 });
+
+  const tagged = all
+    .filter(e => e.data.tags?.includes(tag))
+    .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0));
+
+  return rss({
+    title: `#${tag} — ${siteTitle}`,
+    description: `${siteDescription ? siteDescription + ' · ' : ''}Posts tagged #${tag}`,
+    site,
+    items: tagged.map(e => ({
+      title: e.data.title,
+      pubDate: e.data.date,
+      description: e.data.description,
+      link: entryHref(e),
+    })),
+  });
+};

package/src/pages/tag.astro

@@ -0,0 +1,70 @@
+---
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle, blogMount } from 'virtual:karaoke-cms/config';
+import { tagsMount } from 'virtual:karaoke-cms/tags-config';
+import { docsSections } from 'virtual:karaoke-cms/docs-sections';
+import { slugifyTag, slugToTag } from '../utils.js';
+
+export async function getStaticPaths() {
+  const settled = await Promise.allSettled([
+    getCollection('blog', ({ data }) => data.publish === true),
+    ...docsSections.map(s => getCollection(s.collection as any, ({ data }) => data.publish === true)),
+  ]);
+  const allEntries = settled.flatMap(r => r.status === 'fulfilled' ? r.value : []);
+
+  const tags = new Set<string>();
+  for (const entry of allEntries) {
+    for (const tag of entry.data.tags ?? []) tags.add(tag);
+  }
+
+  return [...tags].map(tag => ({
+    params: { tag: slugifyTag(tag) },
+    props: {
+      originalTag: tag,
+      entries: allEntries
+        .filter(e => e.data.tags?.includes(tag))
+        .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0)),
+    },
+  }));
+}
+
+const { tag } = Astro.params;
+const { originalTag, entries } = Astro.props;
+
+// Map collection name → mount path for correct href generation
+const mountByCollection: Record<string, string> = {
+  blog: blogMount,
+  ...Object.fromEntries(docsSections.map(s => [s.collection, s.mount])),
+};
+
+function href(entry: { collection: string; id: string }) {
+  const mount = mountByCollection[entry.collection];
+  return mount ? `${mount}/${entry.id}` : `/${entry.collection}/${entry.id}`;
+}
+---
+
+<DefaultPage title={`#${originalTag} — ${siteTitle}`}>
+  <link rel="alternate" type="application/rss+xml" title={`#${originalTag} RSS Feed`} href={`${tagsMount}/${tag}/rss.xml`} slot="head" />
+  <div class="listing-header">
+    <h1>#{originalTag}</h1>
+    <p><a href={tagsMount}>← All tags</a></p>
+  </div>
+  {entries.length > 0 ? (
+    <ul class="post-list">
+      {entries.map(entry => (
+        <li>
+          {entry.data.date && (
+            <span class="post-date">{entry.data.date.toISOString().slice(0, 10)}</span>
+          )}
+          <a href={href(entry)}>{entry.data.title}</a>
+          <span class="post-collection">{entry.collection}</span>
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <div class="empty-state">
+      <p>No published posts tagged <strong>#{originalTag}</strong>.</p>
+    </div>
+  )}
+</DefaultPage>

package/src/utils.ts

@@ -0,0 +1,28 @@
+/**
+ * Convert a raw tag string to a URL-safe slug.
+ * Used in all three module pages and the RSS endpoint for consistent URL generation.
+ *
+ * Examples:
+ *   "C++"    → "c-plus-plus"
+ *   "AI/ML"  → "ai-ml"
+ *   "Node.js"→ "node-js"
+ *   "web dev"→ "web-dev"
+ */
+export function slugifyTag(tag: string): string {
+  return tag
+    .toLowerCase()
+    .replace(/\+\+/g, '-plus-plus')
+    .replace(/\+/g, '-plus-')
+    .replace(/[^\w\s-]/g, '-')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Reverse lookup: given a slug and a set of known original tag strings,
+ * return the original tag that maps to this slug.
+ */
+export function slugToTag(slug: string, knownTags: string[]): string | undefined {
+  return knownTags.find(t => slugifyTag(t) === slug);
+}