@hutusi/amytis 1.9.0 → 1.11.0

package/src/lib/feed-utils.ts

@@ -0,0 +1,68 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeStringify from 'rehype-stringify';
+import { getAllPosts, getAllFlows } from './markdown';
+import { siteConfig } from '../../site.config';
+import { getPostUrl, getFlowUrl } from './urls';
+
+export interface FeedItem {
+  title: string;
+  url: string;
+  date: Date;
+  excerpt: string;
+  /** Rendered HTML content for use in content:encoded / Atom <content> */
+  content: string;
+  tags: string[];
+  authors?: string[];
+}
+
+function markdownToHtml(markdown: string): string {
+  const result = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeRaw)
+    .use(rehypeStringify)
+    .processSync(markdown);
+  return String(result);
+}
+
+/**
+ * Returns feed items for RSS/Atom generation.
+ * Includes all published posts (converted to HTML) and optionally flow notes
+ * when `siteConfig.feed.includeFlows` is enabled. Results are sorted by date
+ * descending and capped at `siteConfig.feed.maxItems` (0 = unlimited).
+ */
+export function getFeedItems(): FeedItem[] {
+  const { maxItems, includeFlows } = siteConfig.feed;
+  const baseUrl = siteConfig.baseUrl.replace(/\/+$/, '');
+
+  const postItems: FeedItem[] = getAllPosts().map((post) => ({
+    title: post.title,
+    url: `${baseUrl}${getPostUrl(post)}`,
+    date: new Date(post.date),
+    excerpt: post.excerpt,
+    content: markdownToHtml(post.content),
+    tags: post.tags || [],
+    authors: post.authors,
+  }));
+
+  let items: FeedItem[] = postItems;
+
+  if (includeFlows) {
+    const flowItems: FeedItem[] = getAllFlows().map((flow) => ({
+      title: flow.title,
+      url: `${baseUrl}${getFlowUrl(flow.slug)}`,
+      date: new Date(flow.date),
+      excerpt: flow.excerpt,
+      content: markdownToHtml(flow.content),
+      tags: flow.tags || [],
+    }));
+    items = [...postItems, ...flowItems].sort((a, b) => b.date.getTime() - a.date.getTime());
+  }
+
+  return maxItems > 0 ? items.slice(0, maxItems) : items;
+}

package/src/lib/format-utils.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from 'bun:test';
+import { padNumber } from './format-utils';
+
+describe('padNumber', () => {
+  test('pads single digit to width 2 by default', () => {
+    expect(padNumber(1)).toBe('01');
+    expect(padNumber(9)).toBe('09');
+  });
+
+  test('does not pad numbers already at default width', () => {
+    expect(padNumber(10)).toBe('10');
+    expect(padNumber(99)).toBe('99');
+  });
+
+  test('does not truncate numbers wider than the default width', () => {
+    expect(padNumber(100)).toBe('100');
+  });
+
+  test('pads zero', () => {
+    expect(padNumber(0)).toBe('00');
+  });
+
+  test('respects custom width', () => {
+    expect(padNumber(5, 3)).toBe('005');
+    expect(padNumber(42, 4)).toBe('0042');
+  });
+});

package/src/lib/format-utils.ts

@@ -0,0 +1,3 @@
+export function padNumber(n: number, width = 2): string {
+  return String(n).padStart(width, '0');
+}

package/src/lib/image-utils.ts

@@ -0,0 +1,12 @@
+/**
+ * Prepend a CDN base URL to a local image path.
+ * External URLs (http/https) and special values (text:, data:) are returned as-is.
+ */
+export function getCdnImageUrl(src: string, cdnBaseUrl: string): string {
+  if (!cdnBaseUrl || !src) return src;
+  if (src.startsWith('http') || src.startsWith('//')) return src;
+  if (src.startsWith('text:') || src.startsWith('data:')) return src;
+  const base = cdnBaseUrl.replace(/\/$/, '');
+  const path = src.startsWith('/') ? src : `/${src}`;
+  return `${base}${path}`;
+}

package/src/lib/json-ld.ts

@@ -0,0 +1,236 @@
+// ── Schema shape types ────────────────────────────────────────────────────────
+
+interface SchemaOrganization {
+  '@type': 'Organization';
+  name: string;
+  url: string;
+}
+
+interface SchemaPerson {
+  '@type': 'Person';
+  name: string;
+}
+
+interface SchemaImageObject {
+  '@type': 'ImageObject';
+  url: string;
+}
+
+interface SchemaBlogPosting {
+  '@type': 'BlogPosting';
+  headline: string;
+  description: string | undefined;
+  url: string;
+  datePublished: string;
+  dateModified: string;
+  author: SchemaPerson[];
+  publisher: SchemaOrganization;
+  image: SchemaImageObject;
+  keywords: string | undefined;
+  mainEntityOfPage: { '@type': 'WebPage'; '@id': string };
+}
+
+interface SchemaBook {
+  '@type': 'Book';
+  name: string;
+  description: string | undefined;
+  url: string;
+  datePublished: string;
+  author: SchemaPerson[];
+  publisher: SchemaOrganization;
+  image: SchemaImageObject | undefined;
+}
+
+interface SchemaArticle {
+  '@type': 'Article';
+  headline: string;
+  description: string | undefined;
+  url: string;
+  datePublished: string;
+  author: SchemaPerson[];
+  publisher: SchemaOrganization;
+  isPartOf: { '@type': 'Book'; '@id': string; name: string };
+}
+
+interface SchemaWebSite {
+  '@type': 'WebSite';
+  name: string;
+  url: string;
+  description?: string;
+}
+
+type SchemaNode = SchemaBlogPosting | SchemaBook | SchemaArticle | SchemaWebSite;
+
+interface SchemaGraph {
+  '@context': 'https://schema.org';
+  '@graph': SchemaNode[];
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function buildPublisher(siteTitle: string, siteUrl: string): SchemaOrganization {
+  return { '@type': 'Organization', name: siteTitle, url: siteUrl };
+}
+
+function buildAuthors(names: string[]): SchemaPerson[] {
+  return names.map(name => ({ '@type': 'Person', name }));
+}
+
+/**
+ * Resolve an absolute image URL for structured data.
+ * Accepts external URLs (http/https) and site-relative paths (/books/..., /posts/...).
+ * Rejects relative paths (./images/...) and text placeholders (text:...).
+ */
+export function resolveImageUrl(
+  coverImage: string | undefined,
+  defaultOgImage: string,
+  siteUrl: string,
+): string {
+  const toAbsolute = (url: string) =>
+    url.startsWith('http') ? url : `${siteUrl}${url.startsWith('/') ? url : `/${url}`}`;
+
+  if (coverImage && !coverImage.startsWith('text:') && !coverImage.startsWith('./')) {
+    return toAbsolute(coverImage);
+  }
+  return toAbsolute(defaultOgImage);
+}
+
+/**
+ * Serialize a JSON-LD graph to a string safe for injection into a <script> tag.
+ * JSON.stringify does not escape '<', so a value containing '</script>' could
+ * break the script block. Replacing '<' with '\u003c' prevents this.
+ */
+export function serializeJsonLd(schema: SchemaGraph): string {
+  return JSON.stringify(schema).replace(/</g, '\\u003c');
+}
+
+function wrapGraph(nodes: SchemaNode[]): SchemaGraph {
+  return { '@context': 'https://schema.org', '@graph': nodes };
+}
+
+export interface WebsiteJsonLdParams {
+  siteTitle: string;
+  siteUrl: string;
+  description?: string;
+}
+
+// ── Public param types ────────────────────────────────────────────────────────
+
+export interface PostJsonLdParams {
+  post: {
+    title: string;
+    excerpt: string;
+    date: string;
+    authors: string[];
+    tags: string[];
+    coverImage?: string;
+  };
+  postUrl: string;
+  siteTitle: string;
+  siteUrl: string;
+  defaultOgImage: string;
+}
+
+export interface BookJsonLdParams {
+  book: {
+    title: string;
+    excerpt?: string;
+    date: string;
+    authors: string[];
+    coverImage?: string;
+  };
+  bookUrl: string;
+  siteTitle: string;
+  siteUrl: string;
+  defaultOgImage: string;
+}
+
+export interface BookChapterJsonLdParams {
+  chapter: {
+    title: string;
+    excerpt?: string;
+  };
+  book: {
+    title: string;
+    date: string;
+    authors: string[];
+  };
+  chapterUrl: string;
+  bookUrl: string;
+  siteTitle: string;
+  siteUrl: string;
+}
+
+// ── Builders ──────────────────────────────────────────────────────────────────
+
+export function buildWebsiteJsonLd(params: WebsiteJsonLdParams): SchemaGraph {
+  const { siteTitle, siteUrl, description } = params;
+  const base = siteUrl.replace(/\/+$/, '');
+
+  const node: SchemaWebSite = {
+    '@type': 'WebSite',
+    name: siteTitle,
+    url: base,
+    description: description || undefined,
+  };
+
+  return wrapGraph([node]);
+}
+
+export function buildPostJsonLd(params: PostJsonLdParams): SchemaGraph {
+  const { post, postUrl, siteTitle, siteUrl, defaultOgImage } = params;
+  const base = siteUrl.replace(/\/+$/, '');
+
+  const node: SchemaBlogPosting = {
+    '@type': 'BlogPosting',
+    headline: post.title,
+    description: post.excerpt || undefined,
+    url: postUrl,
+    datePublished: post.date,
+    dateModified: post.date,
+    author: buildAuthors(post.authors),
+    publisher: buildPublisher(siteTitle, base),
+    image: { '@type': 'ImageObject', url: resolveImageUrl(post.coverImage, defaultOgImage, base) },
+    keywords: post.tags.length > 0 ? post.tags.join(', ') : undefined,
+    mainEntityOfPage: { '@type': 'WebPage', '@id': postUrl },
+  };
+
+  return wrapGraph([node]);
+}
+
+export function buildBookJsonLd(params: BookJsonLdParams): SchemaGraph {
+  const { book, bookUrl, siteTitle, siteUrl, defaultOgImage } = params;
+  const base = siteUrl.replace(/\/+$/, '');
+  const imageUrl = resolveImageUrl(book.coverImage, defaultOgImage, base);
+
+  const node: SchemaBook = {
+    '@type': 'Book',
+    name: book.title,
+    description: book.excerpt || undefined,
+    url: bookUrl,
+    datePublished: book.date,
+    author: buildAuthors(book.authors),
+    publisher: buildPublisher(siteTitle, base),
+    image: imageUrl ? { '@type': 'ImageObject', url: imageUrl } : undefined,
+  };
+
+  return wrapGraph([node]);
+}
+
+export function buildBookChapterJsonLd(params: BookChapterJsonLdParams): SchemaGraph {
+  const { chapter, book, chapterUrl, bookUrl, siteTitle, siteUrl } = params;
+  const base = siteUrl.replace(/\/+$/, '');
+
+  const node: SchemaArticle = {
+    '@type': 'Article',
+    headline: chapter.title,
+    description: chapter.excerpt || undefined,
+    url: chapterUrl,
+    datePublished: book.date,
+    author: buildAuthors(book.authors),
+    publisher: buildPublisher(siteTitle, base),
+    isPartOf: { '@type': 'Book', '@id': bookUrl, name: book.title },
+  };
+
+  return wrapGraph([node]);
+}

package/src/lib/markdown.ts

@@ -4,6 +4,7 @@ import matter from 'gray-matter';
 import { siteConfig } from '../../site.config';
 import GithubSlugger from 'github-slugger';
 import { z } from 'zod';
+import { getPostUrl } from './urls';
 
 const contentDirectory = path.join(process.cwd(), 'content', 'posts');
 const pagesDirectory = path.join(process.cwd(), 'content');
@@ -20,6 +21,7 @@ const ExternalLinkSchema = z.object({
 const PostSchema = z.object({
   title: z.string(),
   date: z.union([z.string(), z.date()]).transform(val => new Date(val).toISOString().split('T')[0]).optional(),
+  subtitle: z.string().optional(),
   excerpt: z.string().optional(),
   category: z.string().optional().default('Uncategorized'),
   tags: z.array(z.string()).optional().default([]),
@@ -31,6 +33,7 @@ const PostSchema = z.object({
   sort: z.enum(['date-desc', 'date-asc', 'manual']).optional().default('date-desc'),
   posts: z.array(z.string()).optional(),
   featured: z.boolean().optional().default(false),
+  pinned: z.boolean().optional().default(false),
   draft: z.boolean().optional().default(false),
   latex: z.boolean().optional().default(false),
   toc: z.boolean().optional().default(true),
@@ -51,6 +54,7 @@ export interface ExternalLink {
 export interface PostData {
   slug: string;
   title: string;
+  subtitle?: string;
   date: string;
   excerpt: string;
   category: string;
@@ -58,10 +62,12 @@ export interface PostData {
   authors: string[];
   layout?: string;
   series?: string;
+  seriesTitle?: string;
   coverImage?: string;
   sort?: 'date-desc' | 'date-asc' | 'manual';
   posts?: string[];
   featured?: boolean;
+  pinned?: boolean;
   draft?: boolean;
   latex?: boolean;
   toc?: boolean;
@@ -149,6 +155,38 @@ export function getSeriesAuthors(seriesSlug: string): string[] | null {
   return null;
 }
 
+/**
+ * Resolve display authors for a series: explicit series authors first,
+ * then top contributors aggregated from the series' posts.
+ */
+export function resolveSeriesAuthors(slug: string, posts: PostData[]): string[] {
+  const explicit = getSeriesAuthors(slug);
+  if (explicit) return explicit;
+  if (posts.length === 0) return [];
+  const counts = new Map<string, number>();
+  for (const post of posts) {
+    for (const author of post.authors) {
+      counts.set(author, (counts.get(author) || 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([name]) => name);
+}
+
+function getSeriesTitle(slug: string): string | undefined {
+  if (!fs.existsSync(seriesDirectory)) return undefined;
+  const indexPathMdx = path.join(seriesDirectory, slug, 'index.mdx');
+  const indexPathMd = path.join(seriesDirectory, slug, 'index.md');
+  let fullPath = '';
+  if (fs.existsSync(indexPathMdx)) fullPath = indexPathMdx;
+  else if (fs.existsSync(indexPathMd)) fullPath = indexPathMd;
+  else return undefined;
+  const { data } = matter(fs.readFileSync(fullPath, 'utf8'));
+  if (data.draft === true) return undefined;
+  return typeof data.title === 'string' ? data.title : undefined;
+}
+
 function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: string, seriesName?: string): PostData {
   const fileContents = fs.readFileSync(fullPath, 'utf8');
   const { data: rawData, content } = matter(fileContents);
@@ -162,6 +200,7 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
 
   const contentWithoutH1 = content.replace(/^\s*#\s+[^\n]+/, '').trim();
 
+  const effectiveSeriesSlug = data.series || seriesName;
   let authors: string[] = [];
   if (data.authors && Array.isArray(data.authors)) {
     authors = data.authors;
@@ -169,15 +208,17 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
     authors = [data.author];
   } else {
     // Inherit from series if this post belongs to one
-    const seriesSlug = data.series || seriesName;
-    if (seriesSlug) {
-      const seriesAuthors = getSeriesAuthors(seriesSlug);
+    if (effectiveSeriesSlug) {
+      const seriesAuthors = getSeriesAuthors(effectiveSeriesSlug);
       if (seriesAuthors) {
         authors = seriesAuthors;
       }
     }
     if (authors.length === 0) {
-      authors = ['Amytis'];
+      const defaultAuthors = siteConfig.posts?.authors?.default;
+      if (defaultAuthors && defaultAuthors.length > 0) {
+        authors = defaultAuthors;
+      }
     }
   }
 
@@ -199,17 +240,20 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
   return {
     slug,
     title: data.title,
+    subtitle: data.subtitle,
     date,
     excerpt,
     category: data.category,
     tags: data.tags,
     authors,
     layout: data.layout,
-    series: data.series || seriesName,
+    series: effectiveSeriesSlug,
+    seriesTitle: effectiveSeriesSlug ? getSeriesTitle(effectiveSeriesSlug) : undefined,
     coverImage,
     sort: data.sort,
     posts: data.posts,
     featured: data.featured,
+    pinned: data.pinned,
     draft: data.draft,
     latex: data.latex,
     toc: data.toc,
@@ -350,6 +394,17 @@ export function getAllPosts(): PostData[] {
     .sort((a, b) => (a.date < b.date ? 1 : -1));
 }
 
+/**
+ * Returns posts for the main listing pages, honouring posts.excludeFromListing.
+ * Use this instead of getAllPosts() on any listing/pagination page.
+ * Individual post routes and series pages still use getAllPosts() directly.
+ */
+export function getListingPosts(): PostData[] {
+  const excluded = new Set(siteConfig.posts?.excludeFromListing ?? []);
+  if (excluded.size === 0) return getAllPosts();
+  return getAllPosts().filter(p => !p.series || !excluded.has(p.series));
+}
+
 function findPostFile(name: string, targetSlug: string): PostData | null {
   // Check standard posts
   let fullPath = path.join(contentDirectory, `${name}.mdx`);
@@ -1304,7 +1359,7 @@ export function buildSlugRegistry(): Map<string, SlugRegistryEntry> {
   const map = new Map<string, SlugRegistryEntry>();
 
   getAllPosts().forEach(p =>
-    map.set(p.slug, { url: `/posts/${p.slug}`, type: 'post', title: p.title })
+    map.set(p.slug, { url: getPostUrl(p), type: 'post', title: p.title })
   );
 
   getAllFlows().forEach(f =>
@@ -1395,7 +1450,7 @@ function buildBacklinkIndex(): Map<string, BacklinkSource[]> {
     }
   };
 
-  getAllPosts().forEach(p => addBacklinks(p.content, p.slug, p.title, 'post', `/posts/${p.slug}`));
+  getAllPosts().forEach(p => addBacklinks(p.content, p.slug, p.title, 'post', getPostUrl(p)));
   getAllNotes().forEach(n => addBacklinks(n.content, n.slug, n.title, 'note', `/notes/${n.slug}`));
   getAllFlows().forEach(f => addBacklinks(f.content, f.slug, f.title, 'flow', `/flows/${f.slug}`));
 

package/src/lib/rehype-image-metadata.test.ts

@@ -0,0 +1,124 @@
+import { describe, test, expect } from 'bun:test';
+import rehypeImageMetadata from './rehype-image-metadata';
+import type { Root, Element } from 'hast';
+
+/** Build a minimal HAST tree containing a single <img> node. */
+function makeTree(src: string): Root {
+  return {
+    type: 'root',
+    children: [
+      {
+        type: 'element',
+        tagName: 'img',
+        properties: { src },
+        children: [],
+      } satisfies Element,
+    ],
+  };
+}
+
+function imgSrc(tree: Root): unknown {
+  return (tree.children[0] as Element).properties.src;
+}
+
+describe('rehype-image-metadata', () => {
+  describe('relative paths (./)', () => {
+    test('resolves to posts public path when slug is posts/{slug}', () => {
+      const tree = makeTree('./images/photo.png');
+      rehypeImageMetadata({ slug: 'posts/my-post' })(tree);
+      expect(imgSrc(tree)).toBe('/posts/my-post/images/photo.png');
+    });
+
+    test('resolves to books public path when slug is books/{slug}', () => {
+      const tree = makeTree('./images/cover.jpg');
+      rehypeImageMetadata({ slug: 'books/my-book' })(tree);
+      expect(imgSrc(tree)).toBe('/books/my-book/images/cover.jpg');
+    });
+
+    test('resolves to flows public path when slug is flows/{year}/{month}/{day}', () => {
+      const tree = makeTree('./images/snap.jpg');
+      rehypeImageMetadata({ slug: 'flows/2026/01/15' })(tree);
+      expect(imgSrc(tree)).toBe('/flows/2026/01/15/images/snap.jpg');
+    });
+
+    test('resolves to notes public path when slug is notes/{slug}', () => {
+      const tree = makeTree('./images/diagram.svg');
+      rehypeImageMetadata({ slug: 'notes/my-note' })(tree);
+      expect(imgSrc(tree)).toBe('/notes/my-note/images/diagram.svg');
+    });
+
+    test('does not modify src when no slug is provided', () => {
+      const tree = makeTree('./images/photo.png');
+      rehypeImageMetadata({})(tree);
+      expect(imgSrc(tree)).toBe('./images/photo.png');
+    });
+
+    test('handles nested relative paths correctly', () => {
+      const tree = makeTree('./assets/sub/image.webp');
+      rehypeImageMetadata({ slug: 'posts/my-post' })(tree);
+      expect(imgSrc(tree)).toBe('/posts/my-post/assets/sub/image.webp');
+    });
+  });
+
+  describe('absolute paths (/)', () => {
+    test('keeps absolute paths as-is', () => {
+      const tree = makeTree('/static/logo.png');
+      rehypeImageMetadata({ slug: 'posts/my-post' })(tree);
+      expect(imgSrc(tree)).toBe('/static/logo.png');
+    });
+
+    test('resolves absolute path without slug', () => {
+      const tree = makeTree('/images/banner.png');
+      rehypeImageMetadata({})(tree);
+      expect(imgSrc(tree)).toBe('/images/banner.png');
+    });
+  });
+
+  describe('external URLs', () => {
+    test('does not touch http:// URLs', () => {
+      const tree = makeTree('https://example.com/image.png');
+      rehypeImageMetadata({ slug: 'posts/my-post' })(tree);
+      expect(imgSrc(tree)).toBe('https://example.com/image.png');
+    });
+
+    test('does not touch // protocol-relative URLs', () => {
+      const tree = makeTree('//cdn.example.com/image.png');
+      rehypeImageMetadata({ slug: 'posts/my-post' })(tree);
+      expect(imgSrc(tree)).toBe('//cdn.example.com/image.png');
+    });
+  });
+
+  describe('bare relative paths (no prefix)', () => {
+    test('resolves bare relative paths against slug', () => {
+      const tree = makeTree('images/photo.png');
+      rehypeImageMetadata({ slug: 'posts/my-post' })(tree);
+      expect(imgSrc(tree)).toBe('/posts/my-post/images/photo.png');
+    });
+
+    test('keeps bare relative paths when no slug is provided', () => {
+      const tree = makeTree('images/photo.png');
+      rehypeImageMetadata({})(tree);
+      expect(imgSrc(tree)).toBe('images/photo.png');
+    });
+  });
+
+  describe('CDN prefix', () => {
+    test('prepends CDN base URL to resolved relative path', () => {
+      const tree = makeTree('./images/photo.png');
+      rehypeImageMetadata({ slug: 'posts/my-post', cdnBaseUrl: 'https://cdn.example.com' })(tree);
+      expect(imgSrc(tree)).toBe('https://cdn.example.com/posts/my-post/images/photo.png');
+    });
+
+    test('prepends CDN base URL to absolute path', () => {
+      const tree = makeTree('/static/logo.png');
+      rehypeImageMetadata({ cdnBaseUrl: 'https://cdn.example.com' })(tree);
+      expect(imgSrc(tree)).toBe('https://cdn.example.com/static/logo.png');
+    });
+
+    test('does not prepend CDN to external URLs', () => {
+      const tree = makeTree('https://external.com/img.png');
+      rehypeImageMetadata({ cdnBaseUrl: 'https://cdn.example.com' })(tree);
+      expect(imgSrc(tree)).toBe('https://external.com/img.png');
+    });
+  });
+});