@hutusi/amytis 1.12.0 → 1.14.0

package/src/lib/markdown.ts

@@ -121,6 +121,8 @@ export interface PostData {
   content: string;
   headings: Heading[];
   contentLocales?: Record<string, { content: string; title?: string; excerpt?: string; headings?: Heading[] }>;
+  /** Public-relative base path used for resolving co-located images (e.g. "posts/my-post" or "posts" for root flat files). */
+  imageBaseSlug: string;
 }
 
 export function calculateReadingTime(content: string): string {
@@ -235,6 +237,12 @@ function getSeriesTitle(slug: string): string | undefined {
 function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: string, seriesName?: string): PostData {
   const fileContents = fs.readFileSync(fullPath, 'utf8');
   const { data: rawData, content } = matter(fileContents);
+  // Flat files directly in content/posts/ share the posts root public directory for images.
+  // Folder-based posts and series posts each have their own public subdirectory.
+  const isRootFlatPost = path.basename(fullPath) !== 'index.mdx' &&
+    path.basename(fullPath) !== 'index.md' &&
+    path.dirname(fullPath) === contentDirectory;
+  const imageBaseSlug = isRootFlatPost ? 'posts' : `posts/${slug}`;
 
   const parsed = PostSchema.safeParse(rawData);
   if (!parsed.success) {
@@ -279,7 +287,7 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
   let coverImage = data.coverImage;
   if (coverImage && !coverImage.startsWith('http') && !coverImage.startsWith('/') && !coverImage.startsWith('text:')) {
     const cleanPath = coverImage.replace(/^\.\//, '');
-    coverImage = `/posts/${slug}/${cleanPath}`;
+    coverImage = `/${imageBaseSlug}/${cleanPath}`;
   }
 
   return {
@@ -310,6 +318,7 @@ function parseMarkdownFile(fullPath: string, slug: string, dateFromFileName?: st
     readingTime,
     content: contentWithoutH1,
     headings,
+    imageBaseSlug,
   };
 }
 
@@ -874,19 +883,30 @@ export function getCollectionPosts(collectionSlug: string): PostData[] {
   const data = getSeriesData(collectionSlug);
   if (data?.type !== 'collection' || !data.items) return [];
 
+  const getCollectionKey = (post: PostData) =>
+    post.series ? `${post.series}/${post.slug}` : `posts/${post.slug}`;
+
+  const allPosts = getAllPosts();
+  const postIndex = new Map(allPosts.map((post) => [getCollectionKey(post), post]));
   const seen = new Set<string>();
+
   return data.items
     .flatMap(item => {
       if ('series' in item) {
         const posts = getSeriesPosts(item.series);
         return item.exclude ? posts.filter(p => !item.exclude!.includes(p.slug)) : posts;
       }
-      const post = getPostBySlug(item.post);
+
+      const post = item.post.includes('/')
+        ? postIndex.get(item.post)
+        : getPostBySlug(item.post);
+
       return post ? [post] : [];
     })
     .filter(post => {
-      if (seen.has(post.slug)) return false;
-      seen.add(post.slug);
+      const key = getCollectionKey(post);
+      if (seen.has(key)) return false;
+      seen.add(key);
       return true;
     });
 }
@@ -1176,6 +1196,7 @@ function parseFlowFile(fullPath: string, slug: string): FlowData {
   }
   const data = parsed.data;
 
+  const h1Match = content.match(/^\s*#\s+(.+)/);
   const contentWithoutH1 = content.replace(/^\s*#\s+[^\n]+/, '').trim();
   const date = data.date || slug.replace(/\//g, '-'); // slug is YYYY/MM/DD, convert to YYYY-MM-DD
   const excerpt = generateExcerpt(contentWithoutH1);
@@ -1184,7 +1205,7 @@ function parseFlowFile(fullPath: string, slug: string): FlowData {
   return {
     slug,
     date,
-    title: data.title ?? date, // fall back to date string if no title in frontmatter
+    title: data.title?.trim() || h1Match?.[1]?.trim() || date, // frontmatter(non-empty) → H1 → date
     tags: data.tags,
     draft: data.draft,
     commentable: data.commentable,

package/src/lib/urls.ts

@@ -6,8 +6,8 @@ function normalizeSegment(segment: string): string {
 }
 
 // Top-level route segments reserved by the app — series slugs must not collide with these.
-const RESERVED_ROUTE_SEGMENTS = new Set([
-  'series', 'books', 'flows', 'tags', 'authors', 'archive', 'notes', 'graph', 'page', 'api',
+export const RESERVED_ROUTE_SEGMENTS = new Set([
+  'posts', 'series', 'books', 'flows', 'tags', 'authors', 'archive', 'notes', 'graph', 'search', 'page', 'api',
 ]);
 
 export function getPostsBasePath(): string {
@@ -22,7 +22,7 @@ export function getSeriesCustomPaths(): Record<string, string> {
 }
 
 export function getSeriesAutoPaths(): boolean {
-  return siteConfig.series?.autoPaths ?? false;
+  return siteConfig.series?.autoPaths ?? true;
 }
 
 /**
@@ -41,7 +41,7 @@ export function validateSeriesAutoPaths(seriesSlugs: string[], extraReserved: st
   const reserved = new Set([...RESERVED_ROUTE_SEGMENTS, basePath, ...extraReserved]);
 
   for (const slug of seriesSlugs) {
-    if (slug in customPaths) continue; // Has an explicit override — skip
+    if (Object.hasOwn(customPaths, slug)) continue; // Has an explicit override — skip
     if (reserved.has(slug)) {
       throw new Error(
         `[amytis] Series slug "${slug}" conflicts with the reserved route "/${slug}". ` +
@@ -71,6 +71,11 @@ export function getPostsPageUrl(page: number): string {
   return `/${getPostsBasePath()}/page/${page}`;
 }
 
+/** Returns the series listing URL. */
+export function getSeriesListUrl(): string {
+  return '/series';
+}
+
 /** Returns the books listing URL. */
 export function getBooksListUrl(): string {
   return '/books';

package/tests/e2e/mobile/mobile-compat.spec.ts

@@ -404,4 +404,62 @@ test.describe('Mobile Compatibility', () => {
       expect(await hasNoHorizontalOverflow(page)).toBe(true);
     });
   });
+
+  // ── Post list cover image links ────────────────────────────────────────────
+  test.describe('Post list cover image links', () => {
+    test('cover image in post list is wrapped in a link', async ({ page }) => {
+      await page.goto('/posts');
+      await page.waitForLoadState('load');
+
+      // Find the first cover image inside the post list and check its parent link
+      const imageLink = page.locator('article a:has(img)').first();
+      await expect(imageLink).toHaveAttribute('href', /.+/);
+    });
+
+    test('clicking post list cover image navigates to post page', async ({ page }) => {
+      await page.goto('/posts');
+      await page.waitForLoadState('load');
+
+      const imageLink = page.locator('article a:has(img)').first();
+      const href = await imageLink.getAttribute('href');
+      if (!href) { test.skip(); return; }
+
+      await imageLink.click();
+      await page.waitForLoadState('domcontentloaded');
+      expect(page.url()).toContain(href);
+    });
+
+    test('cover image in series catalog is wrapped in a link', async ({ page }) => {
+      await page.goto('/series');
+      await page.waitForLoadState('load');
+      const seriesLink = page.locator('a[href^="/series/"]').first();
+      const seriesHref = await seriesLink.getAttribute('href');
+      if (!seriesHref) { test.skip(); return; }
+
+      await page.goto(seriesHref);
+      await page.waitForLoadState('load');
+
+      const imageLink = page.locator('article a:has(img)').first();
+      await expect(imageLink).toHaveAttribute('href', /.+/);
+    });
+
+    test('clicking series catalog cover image navigates to post page', async ({ page }) => {
+      await page.goto('/series');
+      await page.waitForLoadState('load');
+      const seriesLink = page.locator('a[href^="/series/"]').first();
+      const seriesHref = await seriesLink.getAttribute('href');
+      if (!seriesHref) { test.skip(); return; }
+
+      await page.goto(seriesHref);
+      await page.waitForLoadState('load');
+
+      const imageLink = page.locator('article a:has(img)').first();
+      const href = await imageLink.getAttribute('href');
+      if (!href) { test.skip(); return; }
+
+      await imageLink.click();
+      await page.waitForLoadState('domcontentloaded');
+      expect(page.url()).toContain(href);
+    });
+  });
 });

package/tests/e2e/navigation.test.ts

@@ -1,4 +1,5 @@
 import { describe, test, expect } from "bun:test";
+import { siteConfig } from "../../site.config";
 
 const BASE_URL = "http://localhost:3000";
 
@@ -54,6 +55,7 @@ describe("E2E: Navigation & Assets", () => {
 
   test("feed.atom should be a valid Atom feed", async () => {
     if (!(await isServerRunning())) return;
+    if (siteConfig.feed.format === "rss") return; // skip if Atom is disabled
 
     const response = await fetch(`${BASE_URL}/feed.atom`);
     expect(response.status).toBe(200);
@@ -62,4 +64,28 @@ describe("E2E: Navigation & Assets", () => {
     expect(text).toContain('xmlns="http://www.w3.org/2005/Atom"');
     expect(text).toContain("<entry>");
   });
+
+  test("type-specific feeds should be accessible", async () => {
+    if (!(await isServerRunning())) return;
+
+    const feedUrls = [
+      "/posts/feed.xml",
+      "/flows/feed.xml",
+      "/all.xml",
+    ];
+
+    if (siteConfig.feed.format === "atom" || siteConfig.feed.format === "both") {
+      feedUrls.push(
+        "/posts/feed.atom",
+        "/flows/feed.atom",
+        "/all.atom"
+      );
+    }
+
+    for (const url of feedUrls) {
+      const response = await fetch(`${BASE_URL}${url}`);
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-type")).toContain("xml");
+    }
+  });
 });

package/tests/integration/collections.test.ts

@@ -44,6 +44,21 @@ describe("Integration: Collections", () => {
     expect(slugs).toContain("understanding-react-hooks");
   });
 
+  test("getCollectionPosts resolves namespaced post entries properly", () => {
+    // The modern-web-dev collection uses the "posts/asynchronous-javascript" syntax.
+    // This test ensures that the namespaced resolution logic successfully found it.
+    const posts = getCollectionPosts("modern-web-dev");
+    const foundPost = posts.find(p => p.slug === "asynchronous-javascript");
+    expect(foundPost).toBeDefined();
+    // Because the namespace was "posts/", its series should be undefined
+    expect(foundPost!.series).toBeUndefined();
+
+    // Also verify series-based namespace
+    const seriesPost = posts.find(p => p.slug === "02-architecture");
+    expect(seriesPost).toBeDefined();
+    expect(seriesPost!.series).toBe("digital-garden");
+  });
+
   test("getCollectionPosts includes posts from referenced series", () => {
     const posts = getCollectionPosts("modern-web-dev");
     const slugs = posts.map((p) => p.slug);
@@ -108,8 +123,8 @@ describe("Integration: Collections", () => {
   test("getAllSeries includes collection with correct post count", () => {
     const all = getAllSeries();
     expect(all).toHaveProperty("modern-web-dev");
-    // modern-web-dev has 2 standalone posts + 2 from nextjs-deep-dive
-    expect(all["modern-web-dev"].length).toBe(4);
+    // modern-web-dev has 2 standalone posts + 4 from nextjs-deep-dive
+    expect(all["modern-web-dev"].length).toBe(6);
   });
 
   test("getAllSeries collection posts are sorted by date descending", () => {

package/tests/integration/feed-utils.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { getFeedItems } from "../../src/lib/feed-utils";
 import { getAllPosts, getAllFlows } from "../../src/lib/markdown";
+import { getPostUrl, getFlowUrl } from "../../src/lib/urls";
 import { siteConfig } from "../../site.config";
 
 describe("Integration: Feed Utils", () => {
@@ -142,4 +143,55 @@ describe("Integration: Feed Utils", () => {
       }
     });
   });
+
+  test("feedType 'posts' returns only post items", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems('posts');
+      const allPosts = getAllPosts();
+      const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+      expect(items.length).toBe(allPosts.length);
+      expect(items.map((item) => item.url).sort()).toEqual(
+        allPosts.map((post) => `${baseUrl}${getPostUrl(post)}`).sort()
+      );
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("feedType 'flows' returns only flow items", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems('flows');
+      const allFlows = getAllFlows();
+      const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+      expect(items.length).toBe(allFlows.length);
+      expect(items.map((item) => item.url).sort()).toEqual(
+        allFlows.map((flow) => `${baseUrl}${getFlowUrl(flow.slug)}`).sort()
+      );
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
+
+  test("feedType 'all' returns both post and flow items", () => {
+    const originalMaxItems = siteConfig.feed.maxItems;
+    try {
+      siteConfig.feed.maxItems = 0;
+      const items = getFeedItems('all');
+      const allPosts = getAllPosts();
+      const allFlows = getAllFlows();
+      const baseUrl = siteConfig.baseUrl.replace(/\/+$/, "");
+      expect(items.map((item) => item.url).sort()).toEqual(
+        [
+          ...allPosts.map((post) => `${baseUrl}${getPostUrl(post)}`),
+          ...allFlows.map((flow) => `${baseUrl}${getFlowUrl(flow.slug)}`),
+        ].sort()
+      );
+    } finally {
+      siteConfig.feed.maxItems = originalMaxItems;
+    }
+  });
 });

package/tests/integration/flow-title.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { getFlowBySlug, getAllFlows } from "../../src/lib/markdown";
+
+describe("Integration: Flow Title Resolution", () => {
+  test("frontmatter title takes priority over H1 and date", () => {
+    // content/flows/2026/03/05.md has `title: 'JSDoc type comments'` in frontmatter
+    const flow = getFlowBySlug("2026/03/05");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("JSDoc type comments");
+  });
+
+  test("H1 heading is extracted as title when no frontmatter title", () => {
+    // content/flows/2026/03/07.md has no frontmatter title but has `# Using Claude Code`
+    const flow = getFlowBySlug("2026/03/07");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("Using Claude Code");
+  });
+
+  test("date is used as fallback when no frontmatter title or H1", () => {
+    // content/flows/2026/02/05.md has no title and no H1
+    const flow = getFlowBySlug("2026/02/05");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("2026-02-05");
+  });
+
+  test("H1 heading is stripped from content body", () => {
+    const flow = getFlowBySlug("2026/03/07");
+    expect(flow).not.toBeNull();
+    // The H1 should be extracted as title but removed from content
+    expect(flow!.content).not.toMatch(/^#\s+Using Claude Code/m);
+    // The body content should still be present
+    expect(flow!.content).toContain("Claude Code");
+  });
+
+  test("every flow has a non-empty title", () => {
+    const flows = getAllFlows();
+    expect(flows.length).toBeGreaterThan(0);
+    flows.forEach((flow) => {
+      expect(flow.title).toBeTruthy();
+      expect(flow.title.trim().length).toBeGreaterThan(0);
+    });
+  });
+
+  test("flow with frontmatter title preserves content H1 independently", () => {
+    // content/flows/2026/03/05.md has frontmatter title — any H1 in content
+    // should still be stripped, but title comes from frontmatter
+    const flow = getFlowBySlug("2026/03/05");
+    expect(flow).not.toBeNull();
+    expect(flow!.title).toBe("JSDoc type comments");
+    // Content should not start with an H1
+    expect(flow!.content).not.toMatch(/^\s*#\s+/);
+  });
+});

package/tests/integration/markdown-features.test.ts

@@ -3,14 +3,14 @@ import { getPostBySlug } from "../../src/lib/markdown";
 
 describe("Integration: Markdown Features", () => {
   test("should correctly load multilingual post", () => {
-    const post = getPostBySlug("multilingual-test");
+    const post = getPostBySlug("multilingual-test-中文长标题");
     expect(post).not.toBeNull();
     expect(post?.title).toContain("多语言测试");
     expect(post?.latex).toBe(true);
   });
 
   test("should generate correct Unicode IDs for TOC", () => {
-    const post = getPostBySlug("multilingual-test");
+    const post = getPostBySlug("multilingual-test-中文长标题");
     expect(post).not.toBeNull();
     
     // Check headings
@@ -43,7 +43,7 @@ describe("Integration: Markdown Features", () => {
   });
 
   test("should correctly identify latex enabled posts", () => {
-    const post = getPostBySlug("multilingual-test");
+    const post = getPostBySlug("multilingual-test-中文长标题");
     expect(post?.latex).toBe(true);
 
     const otherPost = getPostBySlug("hello-world"); // Assuming this doesn't exist or doesn't have latex

package/tests/integration/reading-time-headings.test.ts

@@ -63,9 +63,9 @@ describe("Integration: Reading Time & Headings", () => {
   });
 
   test("multilingual post has headings with correct IDs", () => {
-    const post = getPostBySlug("multilingual-test");
+    const post = getPostBySlug("multilingual-test-中文长标题");
     if (!post) {
-      console.warn("Skipping: multilingual-test post not found");
+      console.warn("Skipping: multilingual-test-中文长标题 post not found");
       return;
     }