@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/src/__tests__/markdown.test.ts

@@ -64,7 +64,13 @@ jest.mock('unist-util-visit', () => ({
   },
 }))
 
-import { customRenderer, markdownToHtml, extractToc, getContentSlotBoundaries } from '../markdown'
+import {
+  customRenderer,
+  deriveFaqFromHeadings,
+  markdownToHtml,
+  extractToc,
+  getContentSlotBoundaries,
+} from '../markdown'
 
 // ---------------------------------------------------------------------------
 // customRenderer
@@ -429,3 +435,73 @@ describe('getContentSlotBoundaries', () => {
     expect(boundaries?.paragraphCount).toBe(1)
   })
 })
+
+describe('deriveFaqFromHeadings', () => {
+  it('pairs a question-shaped h2 with the paragraph that follows it', () => {
+    const markdown = [
+      '## What is initiative?',
+      '',
+      'It is the turn order for combat.',
+      'Everyone rolls once.',
+      '',
+      '## How do I roll it?',
+      '',
+      'Roll a d20 and add your modifier.',
+    ].join('\n')
+
+    expect(deriveFaqFromHeadings(markdown)).toEqual([
+      {
+        question: 'What is initiative?',
+        answer: 'It is the turn order for combat. Everyone rolls once.',
+      },
+      { question: 'How do I roll it?', answer: 'Roll a d20 and add your modifier.' },
+    ])
+  })
+
+  it('ignores headings that are not questions, rhetorical questions, and other heading levels', () => {
+    const markdown = [
+      '## Setting the scene',
+      '',
+      'Some prose.',
+      '',
+      '## Sound familiar?',
+      '',
+      'More prose.',
+      '',
+      '### How do I nest?',
+      '',
+      'Nested prose.',
+    ].join('\n')
+
+    expect(deriveFaqFromHeadings(markdown)).toEqual([])
+  })
+
+  it('skips a question heading with no prose under it', () => {
+    const markdown = ['## What is this?', '', '## Why does it matter?', '', 'Because.'].join('\n')
+    expect(deriveFaqFromHeadings(markdown)).toEqual([
+      { question: 'Why does it matter?', answer: 'Because.' },
+    ])
+  })
+
+  it('ignores question headings inside fenced code blocks', () => {
+    const markdown = ['```md', '## What is this?', '', 'Not real prose.', '```'].join('\n')
+    expect(deriveFaqFromHeadings(markdown)).toEqual([])
+  })
+
+  it('requires whitespace after ## and rejects deeper heading levels', () => {
+    expect(deriveFaqFromHeadings(['##What is this?', '', 'Prose.'].join('\n'))).toEqual([])
+    expect(deriveFaqFromHeadings(['### What is this?', '', 'Prose.'].join('\n'))).toEqual([])
+    expect(deriveFaqFromHeadings(['##\tWhat is this?', '', 'Prose.'].join('\n'))).toEqual([
+      { question: 'What is this?', answer: 'Prose.' },
+    ])
+  })
+
+  it('stops collecting at the next heading and strips closing hashes', () => {
+    const markdown = ['## Can I do this? ##', '', 'Yes.', '# New section', '', 'Ignored.'].join(
+      '\n'
+    )
+    expect(deriveFaqFromHeadings(markdown)).toEqual([
+      { question: 'Can I do this?', answer: 'Yes.' },
+    ])
+  })
+})

package/src/__tests__/nextjs.test.ts

@@ -3,10 +3,10 @@
  * Mocks server-articles to isolate the handler logic.
  */
 
-const mockGetArticleMarkdownResponse = jest.fn()
+const mockGetMarkdownTwinResponse = jest.fn()
 
 jest.mock('../server-articles', () => ({
-  getArticleMarkdownResponse: (...args: unknown[]) => mockGetArticleMarkdownResponse(...args),
+  getMarkdownTwinResponse: (...args: unknown[]) => mockGetMarkdownTwinResponse(...args),
 }))
 
 import { createArticleMarkdownHandler } from '../nextjs'
@@ -47,14 +47,16 @@ function makeContext(slugValue: string | string[]): {
   }
 }
 
+const requestHeaders = { get: () => null }
+
 function makeRequest(): NextRequest {
-  return {} as NextRequest
+  return { headers: requestHeaders } as unknown as NextRequest
 }
 
 describe('createArticleMarkdownHandler', () => {
   beforeEach(() => {
     jest.clearAllMocks()
-    mockGetArticleMarkdownResponse.mockResolvedValue(new Response('# Article', { status: 200 }))
+    mockGetMarkdownTwinResponse.mockResolvedValue(new Response('# Article', { status: 200 }))
   })
 
   it('returns an object with a GET handler', () => {
@@ -62,12 +64,14 @@ describe('createArticleMarkdownHandler', () => {
     expect(typeof GET).toBe('function')
   })
 
-  it('calls getArticleMarkdownResponse with joined slug array and config', async () => {
+  it('calls getMarkdownTwinResponse with joined slug array and config', async () => {
     const { GET } = createArticleMarkdownHandler(siteConfig)
     const ctx = makeContext(['category', 'my-article.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('category/my-article', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('category/my-article', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('strips trailing .md from a slug array', async () => {
@@ -75,7 +79,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext(['some-article.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('some-article', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('some-article', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles a plain string slug without .md extension', async () => {
@@ -83,7 +89,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext('plain-slug')
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('plain-slug', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('plain-slug', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles a plain string slug with .md extension - strips it', async () => {
@@ -91,7 +99,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext('plain-slug.md')
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('plain-slug', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('plain-slug', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles undefined slug (missing param) as empty string', async () => {
@@ -101,12 +111,14 @@ describe('createArticleMarkdownHandler', () => {
     }
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 
-  it('returns the response from getArticleMarkdownResponse', async () => {
+  it('returns the response from getMarkdownTwinResponse', async () => {
     const mockResponse = new Response('markdown content', { status: 200 })
-    mockGetArticleMarkdownResponse.mockResolvedValue(mockResponse)
+    mockGetMarkdownTwinResponse.mockResolvedValue(mockResponse)
 
     const { GET } = createArticleMarkdownHandler(siteConfig)
     const ctx = makeContext(['article.md'])
@@ -115,7 +127,7 @@ describe('createArticleMarkdownHandler', () => {
     expect(result).toBe(mockResponse)
   })
 
-  it('passes the config object through to getArticleMarkdownResponse', async () => {
+  it('passes the config object through to getMarkdownTwinResponse', async () => {
     const customConfig: ArticlesConfig = {
       siteUrl: 'https://custom.example.com',
       siteName: 'Custom Site',
@@ -124,7 +136,9 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext(['test.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('test', customConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('test', customConfig, {
+      headers: requestHeaders,
+    })
   })
 
   it('handles deeply nested slug array', async () => {
@@ -132,6 +146,8 @@ describe('createArticleMarkdownHandler', () => {
     const ctx = makeContext(['a', 'b', 'c', 'deep-article.md'])
     await GET(makeRequest(), ctx)
 
-    expect(mockGetArticleMarkdownResponse).toHaveBeenCalledWith('a/b/c/deep-article', siteConfig)
+    expect(mockGetMarkdownTwinResponse).toHaveBeenCalledWith('a/b/c/deep-article', siteConfig, {
+      headers: requestHeaders,
+    })
   })
 })

package/src/__tests__/seoUtils.test.ts

@@ -1,4 +1,5 @@
 import { ArticlesConfig } from '../articlesConfig'
+import type { Article } from '../articleTypes'
 import {
   generateArticleStaticParams,
   generateArticlesIndexMetadata,
@@ -11,6 +12,8 @@ import {
   generateSeriesMetadata,
   getArticleSitemapEntries,
   generateRssFeed,
+  generateLlmsTxt,
+  generateLlmsFullTxt,
   resolveSearchMetadata,
   resolveSocialMetadata,
 } from '../seoUtils'
@@ -102,6 +105,15 @@ jest.mock('../server-articles', () => ({
       return `${cfg.siteUrl.replace(/\/$/, '')}/articles/${article.slug}.md`
     }
   ),
+  categoryToSlug: (category: string) =>
+    category
+      .toLowerCase()
+      .replaceAll(/\s+/g, '-')
+      .replaceAll(/[^a-z0-9-]/g, ''),
+  getArticleMarkdown: jest.fn(async (slug: string) =>
+    slug === 'missing-body' ? null : `Body of ${slug}.`
+  ),
+  buildMarkdownTwinHeader: jest.fn((article: { title: string }) => `HEADER(${article.title})\n\n`),
   getArticlesBySeries: jest.fn(async (seriesSlug: string) => {
     if (seriesSlug === 'new-gm-path') {
       return [
@@ -563,6 +575,71 @@ describe('getArticleSitemapEntries', () => {
     expect(categoryEntry.changeFrequency).toBe('weekly')
   })
 
+  it('derives category lastModified from the newest article in it, not now', async () => {
+    const entries = await getArticleSitemapEntries('https://example.com')
+    const campaigns = entries.find((e) => e.url.endsWith('/articles/category/campaigns'))
+    // getAllArticles mock returns article-one (2025-01-15) and article-two
+    // (2025-01-16), both uncategorized in the mock, so no date is derivable.
+    expect(campaigns).toBeDefined()
+    expect(campaigns!.lastModified).toBeUndefined()
+  })
+
+  it('emits series entries for every distinct seriesSlug', async () => {
+    const { getAllArticles } = jest.requireMock('../server-articles')
+    getAllArticles.mockResolvedValueOnce([
+      {
+        slug: 'one',
+        title: 'One',
+        excerpt: '',
+        author: '',
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '',
+        featuredImage: '',
+        date: '2025-01-15',
+        seriesSlug: 'new-gm',
+      },
+      {
+        slug: 'two',
+        title: 'Two',
+        excerpt: '',
+        author: '',
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '',
+        featuredImage: '',
+        date: '2025-03-01',
+        seriesSlug: 'new-gm',
+      },
+    ])
+
+    const entries = await getArticleSitemapEntries('https://example.com')
+    const series = entries.filter((e) => e.url.includes('/articles/series/'))
+    expect(series).toHaveLength(1)
+    expect(series[0].url).toBe('https://example.com/articles/series/new-gm')
+    expect(series[0].lastModified).toEqual(new Date('2025-03-01'))
+  })
+
+  it('omits paginated entries unless listingPagination is pages', async () => {
+    const entries = await getArticleSitemapEntries({
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+    })
+    expect(entries.some((e) => e.url.includes('/page/'))).toBe(false)
+  })
+
+  it('emits paginated listing entries starting at page 2 in pages mode', async () => {
+    const entries = await getArticleSitemapEntries({
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      listingPagination: 'pages',
+      pageSize: 1,
+    })
+    const indexPages = entries.filter((e) => e.url.startsWith('https://example.com/articles/page/'))
+    // Two articles at pageSize 1 -> pages 1 and 2; page 1 is the listing URL.
+    expect(indexPages.map((e) => e.url)).toEqual(['https://example.com/articles/page/2'])
+  })
+
   it('returns empty array when fetching throws', async () => {
     const { getAllArticles } = jest.requireMock('../server-articles')
     getAllArticles.mockRejectedValueOnce(new Error('filesystem error'))
@@ -931,3 +1008,205 @@ describe('generateSeriesMetadata', () => {
     expect(meta.alternates?.canonical).toBe('https://example.com/articles/series/new-gm-path')
   })
 })
+
+describe('generateRssFeed full content', () => {
+  const baseConfig: ArticlesConfig = {
+    siteUrl: 'https://example.com',
+    siteName: 'Example Site',
+    description: 'Test description',
+  }
+
+  const article = {
+    slug: 'my-article',
+    title: 'My Article',
+    excerpt: 'A short excerpt',
+    date: '2024-01-15',
+    author: 'Jane Doe',
+    category: 'Campaigns',
+    categories: ['Campaigns'],
+    readTime: '3 min read',
+    featuredImage: '',
+    htmlContent: '<p>Full body.</p>',
+  } as Article
+
+  it('declares the content namespace', () => {
+    expect(generateRssFeed([], baseConfig)).toContain(
+      'xmlns:content="http://purl.org/rss/1.0/modules/content/"'
+    )
+  })
+
+  it('omits content:encoded by default', () => {
+    expect(generateRssFeed([article], baseConfig)).not.toContain('<content:encoded>')
+  })
+
+  it('emits content:encoded when fullContent is set', () => {
+    expect(generateRssFeed([article], baseConfig, { fullContent: true })).toContain(
+      '<content:encoded><![CDATA[<p>Full body.</p>]]></content:encoded>'
+    )
+  })
+
+  it('skips content:encoded for articles with no htmlContent', () => {
+    const xml = generateRssFeed([{ ...article, htmlContent: undefined }], baseConfig, {
+      fullContent: true,
+    })
+    expect(xml).not.toContain('<content:encoded>')
+  })
+
+  it('uses the configured language for the channel', () => {
+    expect(generateRssFeed([], baseConfig)).toContain('<language>en</language>')
+    expect(generateRssFeed([], { ...baseConfig, language: 'es' })).toContain(
+      '<language>es</language>'
+    )
+  })
+})
+
+describe('generateLlmsTxt', () => {
+  const baseConfig: ArticlesConfig = {
+    siteUrl: 'https://example.com/',
+    siteName: 'Example Site',
+    description: 'Test description',
+  }
+
+  const article = (overrides: Partial<Article> & Pick<Article, 'slug' | 'title'>): Article =>
+    ({
+      excerpt: `Excerpt for ${overrides.slug}.`,
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '',
+      aiCrawl: true,
+      ...overrides,
+    }) as Article
+
+  it('lists only aiCrawl articles, grouped by category, linking to the .md twin', () => {
+    const output = generateLlmsTxt(
+      [
+        article({ slug: 'one', title: 'One' }),
+        article({ slug: 'two', title: 'Two', category: 'Volunteers', categories: ['Volunteers'] }),
+        article({ slug: 'blocked', title: 'Blocked', aiCrawl: false }),
+      ],
+      baseConfig
+    )
+
+    expect(output).toBe(
+      [
+        '# Example Site',
+        '',
+        '> Test description',
+        '',
+        '## Campaigns',
+        '',
+        '- [One](https://example.com/articles/one.md): Excerpt for one.',
+        '## Volunteers',
+        '',
+        '- [Two](https://example.com/articles/two.md): Excerpt for two.',
+        '## Collections',
+        '',
+        '- [Campaigns](https://example.com/articles/category/campaigns.md)',
+        '- [Volunteers](https://example.com/articles/category/volunteers.md)',
+        '',
+      ].join('\n')
+    )
+    expect(output).not.toContain('Blocked')
+  })
+
+  it('falls back to siteName when description is unset and handles an empty corpus', () => {
+    const output = generateLlmsTxt([], { siteUrl: 'https://example.com', siteName: 'Example Site' })
+    expect(output).toContain('> Example Site articles')
+    expect(output).toContain('_No articles available._')
+  })
+
+  it('groups uncategorized articles under Articles and omits an empty excerpt', () => {
+    const output = generateLlmsTxt(
+      [article({ slug: 'bare', title: 'Bare', category: '', excerpt: '' })],
+      baseConfig
+    )
+    expect(output).toContain('## Articles')
+    expect(output).toContain('- [Bare](https://example.com/articles/bare.md)\n')
+    expect(output).toContain('## Collections')
+    expect(output).toContain('- [Campaigns](https://example.com/articles/category/campaigns.md)')
+  })
+})
+
+describe('generateLlmsFullTxt', () => {
+  const baseConfig: ArticlesConfig = {
+    siteUrl: 'https://example.com',
+    siteName: 'Example Site',
+    description: 'Test description',
+  }
+
+  const article = (slug: string, aiCrawl = true): Article =>
+    ({
+      slug,
+      title: slug.toUpperCase(),
+      excerpt: '',
+      author: '',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '',
+      featuredImage: '',
+      aiCrawl,
+    }) as Article
+
+  it('concatenates header-prefixed bodies for opted-in articles only', async () => {
+    const output = await generateLlmsFullTxt(
+      [article('one'), article('blocked', false)],
+      baseConfig
+    )
+
+    expect(output).toBe(
+      ['# Example Site', '', '> Test description', '', 'HEADER(ONE)\n\nBody of one.'].join('\n')
+    )
+  })
+
+  it('skips articles whose markdown cannot be read', async () => {
+    const output = await generateLlmsFullTxt([article('missing-body')], baseConfig)
+    expect(output).toBe(['# Example Site', '', '> Test description', ''].join('\n'))
+  })
+
+  it('falls back to siteName when description is unset', async () => {
+    const output = await generateLlmsFullTxt([], {
+      siteUrl: 'https://example.com',
+      siteName: 'Example Site',
+    })
+    expect(output).toContain('> Example Site articles')
+  })
+})
+
+describe('titleTemplate', () => {
+  const base: ArticlesConfig = { siteUrl: 'https://example.com', siteName: 'Example Site' }
+
+  it('appends the site name by default', async () => {
+    const meta = await generateArticleMetadata('article-one', base)
+    expect(meta.title).toBe('Article One | Example Site')
+  })
+
+  it('drops the suffix with {title}', async () => {
+    const meta = await generateArticleMetadata('article-one', { ...base, titleTemplate: '{title}' })
+    expect(meta.title).toBe('Article One')
+  })
+
+  it('supports a custom arrangement of both placeholders', async () => {
+    const meta = await generateArticleMetadata('article-one', {
+      ...base,
+      titleTemplate: '{siteName}: {title}',
+    })
+    expect(meta.title).toBe('Example Site: Article One')
+  })
+
+  it('applies to index, category, series, and author titles too', async () => {
+    const config = { ...base, titleTemplate: '{title}' }
+    expect(generateArticlesIndexMetadata(config).title).toBe('Articles')
+    expect((await generateCategoryMetadata('campaigns', config)).title).toBe('Campaigns Articles')
+    expect((await generateSeriesMetadata('new-gm-path', config)).title).toBe('New GM Path Series')
+  })
+
+  it('leaves those titles suffixed under the default template', async () => {
+    expect(generateArticlesIndexMetadata(base).title).toBe('Articles | Example Site')
+    expect((await generateCategoryMetadata('campaigns', base)).title).toBe(
+      'Campaigns Articles | Example Site'
+    )
+  })
+})