@fullstackdatasolutions/articles 0.4.2 → 0.5.0

package/src/__tests__/seoUtils.test.ts

@@ -1,6 +1,7 @@
 import { ArticlesConfig } from '../articlesConfig'
 import {
   generateArticleStaticParams,
+  generateArticlesIndexMetadata,
   generateCategoryStaticParams,
   generateArticleMetadata,
   generateCategoryMetadata,
@@ -98,6 +99,54 @@ describe('generateArticleStaticParams', () => {
   })
 })
 
+describe('generateArticlesIndexMetadata', () => {
+  it('returns canonical URL pointing to /articles', () => {
+    const meta = generateArticlesIndexMetadata(config)
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles')
+  })
+
+  it('strips trailing slash from siteUrl before building canonical', () => {
+    const meta = generateArticlesIndexMetadata({ ...config, siteUrl: 'https://example.com/' })
+    expect(meta.alternates?.canonical).toBe('https://example.com/articles')
+  })
+
+  it('works with a subdirectory siteUrl', () => {
+    const meta = generateArticlesIndexMetadata({ ...config, siteUrl: 'https://example.com/app' })
+    expect(meta.alternates?.canonical).toBe('https://example.com/app/articles')
+  })
+
+  it('includes title, description, openGraph, twitter, and robots', () => {
+    const meta = generateArticlesIndexMetadata(config)
+    expect(meta.title).toBeDefined()
+    expect(meta.description).toBeDefined()
+    expect(meta.openGraph).toBeDefined()
+    expect((meta.openGraph as { type?: string })?.type).toBe('website')
+    expect(meta.twitter).toBeDefined()
+    expect(meta.robots).toBeDefined()
+  })
+
+  it('uses config.hero.description when provided', () => {
+    const cfg: ArticlesConfig = {
+      ...config,
+      hero: { description: 'Custom hero description.' },
+    }
+    const meta = generateArticlesIndexMetadata(cfg)
+    expect(meta.description).toBe('Custom hero description.')
+  })
+
+  it('includes RSS feed URL in alternates.types', () => {
+    const meta = generateArticlesIndexMetadata(config)
+    const types = (meta.alternates as { types?: Record<string, string> })?.types
+    expect(types?.['application/rss+xml']).toBe('https://example.com/articles/feed.xml')
+  })
+
+  it('strips trailing slash from siteUrl before building RSS feed URL', () => {
+    const meta = generateArticlesIndexMetadata({ ...config, siteUrl: 'https://example.com/' })
+    const types = (meta.alternates as { types?: Record<string, string> })?.types
+    expect(types?.['application/rss+xml']).toBe('https://example.com/articles/feed.xml')
+  })
+})
+
 describe('generateCategoryStaticParams', () => {
   it('returns category slug params', async () => {
     const result = await generateCategoryStaticParams()
@@ -143,6 +192,173 @@ describe('generateArticleMetadata', () => {
     })
     expect(meta.alternates?.canonical).toBe('https://example.com/articles/article-one')
   })
+
+  it('uses canonicalUrl override from article when set', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      canonicalUrl: 'https://custom.example.com/my-article',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.alternates?.canonical).toBe('https://custom.example.com/my-article')
+  })
+
+  it('includes modifiedTime in openGraph when lastmod is set', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      lastmod: '2025-06-15',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect((meta.openGraph as { modifiedTime?: string }).modifiedTime).toBe(
+      new Date('2025-06-15').toISOString()
+    )
+  })
+
+  it('includes article:modified_time in other when lastmod is set', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      lastmod: '2025-06-15',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect((meta.other as Record<string, string>)['article:modified_time']).toBe(
+      new Date('2025-06-15').toISOString()
+    )
+  })
+
+  it('resolves absolute featuredImage URL without modification', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: 'https://cdn.example.com/image.jpg',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect((meta.openGraph as { images?: Array<{ url: string }> }).images?.[0].url).toBe(
+      'https://cdn.example.com/image.jpg'
+    )
+  })
+
+  it('uses fallback description when excerpt is null', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: null,
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      tags: ['campaigns'],
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.description).toBe('Read Article One on Example Site.')
+  })
+
+  it('uses placeholder image when featuredImage is falsy', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '',
+      tags: ['campaigns'],
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect((meta.openGraph as { images?: Array<{ url: string }> }).images?.[0].url).toBe(
+      'https://example.com/placeholder-logo.png'
+    )
+  })
+
+  it('populates keywords from article tags', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.keywords).toBe('campaigns, strategy')
+  })
+
+  it('includes article:author, article:published_time, article:section, and article:tag in other', async () => {
+    const meta = await generateArticleMetadata('article-one', config)
+    const other = meta.other as Record<string, string>
+    expect(other['article:author']).toBe('Jane Doe')
+    expect(other['article:published_time']).toBe(new Date('2025-01-15').toISOString())
+    expect(other['article:section']).toBe('Campaigns')
+    expect(other['article:tag']).toBe('campaigns,strategy')
+  })
+
+  it('omits publishedTime and article:published_time when date is undefined', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+      tags: ['campaigns'],
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect((meta.openGraph as { publishedTime?: string }).publishedTime).toBeUndefined()
+    expect(
+      (meta.other as Record<string, string | undefined>)['article:published_time']
+    ).toBeUndefined()
+  })
+
+  it('sets keywords to empty string and article:tag to empty string when tags is undefined', async () => {
+    const { getArticleMetadata: mockGetArticleMetadata } = jest.requireMock('../server-articles')
+    mockGetArticleMetadata.mockImplementationOnce(async () => ({
+      slug: 'article-one',
+      title: 'Article One',
+      excerpt: 'Excerpt.',
+      date: '2025-01-15',
+      author: 'Jane Doe',
+      category: 'Campaigns',
+      categories: ['Campaigns'],
+      readTime: '3 min read',
+      featuredImage: '/articles/article-one/image.jpg',
+    }))
+    const meta = await generateArticleMetadata('article-one', config)
+    expect(meta.keywords).toBe('')
+    expect((meta.other as Record<string, string>)['article:tag']).toBe('')
+  })
 })
 
 describe('generateCategoryMetadata', () => {
@@ -177,6 +393,17 @@ describe('generateCategoryMetadata', () => {
     const meta = await generateCategoryMetadata('nonexistent', config)
     expect(meta.title).toBe('Category Not Found')
   })
+
+  it('uses string categoryDescriptions value directly', async () => {
+    const cfg: ArticlesConfig = {
+      ...config,
+      categoryDescriptions: {
+        campaigns: 'Plain string description.',
+      },
+    }
+    const meta = await generateCategoryMetadata('campaigns', cfg)
+    expect(meta.description).toBe('Plain string description.')
+  })
 })
 
 describe('getArticleSitemapEntries', () => {
@@ -249,4 +476,61 @@ describe('getArticleSitemapEntries', () => {
     const configResult = await getArticleSitemapEntries(config)
     expect(JSON.stringify(stringResult)).toBe(JSON.stringify(configResult))
   })
+
+  it('uses lastmod over date for article lastModified when both are set', async () => {
+    const { getAllArticles } = jest.requireMock('../server-articles')
+    getAllArticles.mockImplementationOnce(async () => [
+      {
+        slug: 'article-one',
+        date: '2025-01-15',
+        lastmod: '2025-06-01',
+        title: '',
+        excerpt: '',
+        author: '',
+        category: '',
+        categories: [],
+        readTime: '',
+        featuredImage: '',
+      },
+    ])
+    const entries = await getArticleSitemapEntries('https://example.com')
+    expect(entries[0].lastModified).toEqual(new Date('2025-06-01'))
+  })
+
+  it('sets lastModified to undefined when article has no date or lastmod', async () => {
+    const { getAllArticles } = jest.requireMock('../server-articles')
+    getAllArticles.mockImplementationOnce(async () => [
+      {
+        slug: 'article-one',
+        title: '',
+        excerpt: '',
+        author: '',
+        category: '',
+        categories: [],
+        readTime: '',
+        featuredImage: '',
+      },
+    ])
+    const entries = await getArticleSitemapEntries('https://example.com')
+    expect(entries[0].lastModified).toBeUndefined()
+  })
+
+  it('uses date for lastModified when article has date but no lastmod', async () => {
+    const { getAllArticles } = jest.requireMock('../server-articles')
+    getAllArticles.mockImplementationOnce(async () => [
+      {
+        slug: 'article-one',
+        date: '2025-03-10',
+        title: '',
+        excerpt: '',
+        author: '',
+        category: '',
+        categories: [],
+        readTime: '',
+        featuredImage: '',
+      },
+    ])
+    const entries = await getArticleSitemapEntries('https://example.com')
+    expect(entries[0].lastModified).toEqual(new Date('2025-03-10'))
+  })
 })

package/src/__tests__/server-articles.test.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs'
+import { getArticleMetadata } from '../server-articles'
+
+jest.mock('react', () => ({ cache: (fn: Function) => fn }))
+jest.mock('node:fs')
+jest.mock('../markdown', () => ({
+  markdownToHtml: jest.fn(async () => '<p>content</p>'),
+  extractToc: jest.fn(async () => []),
+}))
+jest.mock('reading-time', () => () => ({ text: '2 min read' }))
+
+const mockedFs = fs as jest.Mocked<typeof fs>
+
+function setupArticleMock(frontmatter: string, body = 'Article body content.'): void {
+  mockedFs.existsSync.mockReturnValue(true)
+  mockedFs.readFileSync.mockReturnValue(
+    `---\ntitle: Test Article\nexcerpt: A test.\nauthor: Test Author\n${frontmatter}---\n\n${body}`
+  )
+  ;(mockedFs.readdirSync as jest.Mock).mockReturnValue([])
+}
+
+describe('getArticleMetadata - frontmatter parsing', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('parses faq from frontmatter', async () => {
+    setupArticleMock(
+      'faq:\n  - question: "What is this?"\n    answer: "A test."\n  - question: "Why?"\n    answer: "Because."\n'
+    )
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.faq).toHaveLength(2)
+    expect(article!.faq![0]).toEqual({ question: 'What is this?', answer: 'A test.' })
+  })
+
+  it('parses howTo from frontmatter', async () => {
+    setupArticleMock(
+      'howTo:\n  - name: "Step 1"\n    text: "Do this."\n  - name: "Step 2"\n    text: "Then that."\n'
+    )
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.howTo).toHaveLength(2)
+    expect(article!.howTo![0]).toEqual({ name: 'Step 1', text: 'Do this.' })
+  })
+
+  it('parses lastmod from frontmatter', async () => {
+    setupArticleMock('lastmod: 2025-06-15\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.lastmod).toBe('2025-06-15')
+  })
+
+  it('parses canonicalUrl from frontmatter', async () => {
+    setupArticleMock('canonicalUrl: "https://canonical.example.com/article"\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.canonicalUrl).toBe('https://canonical.example.com/article')
+  })
+
+  it('parses articleType from frontmatter', async () => {
+    setupArticleMock('articleType: "TechArticle"\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.articleType).toBe('TechArticle')
+  })
+
+  it('parses series from frontmatter', async () => {
+    setupArticleMock('series: "My Series"\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.series).toBe('My Series')
+  })
+
+  it('filters out malformed faq items', async () => {
+    setupArticleMock(
+      'faq:\n  - question: "What is this?"\n    answer: "A test."\n  - question: "Missing answer"\n'
+    )
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.faq).toHaveLength(1)
+    expect(article!.faq![0].question).toBe('What is this?')
+  })
+
+  it('returns undefined for faq when not present', async () => {
+    setupArticleMock('')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.faq).toBeUndefined()
+  })
+
+  it('returns undefined for howTo when not present', async () => {
+    setupArticleMock('')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.howTo).toBeUndefined()
+  })
+})

package/src/articleTypes.ts

@@ -1,8 +1,25 @@
+export interface TocItem {
+  id: string
+  depth: number
+  text: string
+}
+
+export interface FaqItem {
+  question: string
+  answer: string
+}
+
+export interface HowToStep {
+  name: string
+  text: string
+}
+
 export interface Article {
   slug: string
   title: string
   excerpt: string
   date?: string
+  lastmod?: string
   author: string
   category: string
   categories: string[]
@@ -11,6 +28,15 @@ export interface Article {
   tags?: string[]
   content?: string
   htmlContent?: string
+  mdxSource?: string
+  contentType?: 'md' | 'mdx'
+  draft?: boolean
+  toc?: TocItem[]
+  faq?: FaqItem[]
+  howTo?: HowToStep[]
+  canonicalUrl?: string
+  articleType?: string
+  series?: string
 }
 
 export interface CategoryInfo {

package/src/articlesConfig.ts

@@ -94,6 +94,10 @@ export interface ArticlesConfig {
   comments?: CommentsConfig
   /** Hero section title and description. Omit to use the built-in defaults. */
   hero?: HeroConfig
+  /** Short description used in the RSS feed channel. Falls back to siteName if omitted. */
+  description?: string
+  /** Set to false to hide the table of contents on article detail pages. Default: true. */
+  showToc?: boolean
 }
 
 export const DEFAULT_PAGE_SIZE = 6

package/src/index.ts

@@ -11,10 +11,18 @@ export { FeaturedArticle } from './FeaturedArticle'
 export { LatestArticles } from './LatestArticles'
 export { LatestArticlesSection } from './LatestArticlesSection'
 export { CategoryArticlesPage } from './CategoryArticlesPage'
-export { ArticleSchema, BreadcrumbSchema, CollectionPageSchema } from './ArticleSchemas'
+export {
+  ArticleSchema,
+  ArticleSEO,
+  BreadcrumbSchema,
+  CollectionPageSchema,
+  FAQPageSchema,
+} from './ArticleSchemas'
 
 export { ArticleSocialShare } from './ArticleSocialShare'
 export { ArticleNavigation } from './ArticleNavigation'
+export { ArticleTOC } from './ArticleTOC'
+export { ScrollToTop } from './ScrollToTop'
 
 // Comments
 export { CommentsSection } from './CommentsSection'
@@ -35,5 +43,5 @@ export type {
   CommentsConfig,
 } from './articlesConfig'
 export { DEFAULT_LAYOUT, DEFAULT_PAGE_SIZE, DEFAULT_CATEGORIES_PAGE_SIZE } from './articlesConfig'
-export type { Article, CategoryInfo } from './articleTypes'
+export type { Article, CategoryInfo, FaqItem, HowToStep, TocItem } from './articleTypes'
 export type { ArticleComment, ArticleCommentWithReplies } from './commentTypes'