@fullstackdatasolutions/articles 0.9.0 → 0.11.0

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

@@ -5,6 +5,7 @@ import {
   getAdjacentArticles,
   getAiRobotsTxtRules,
   getAllArticles,
+  getArticleAuthors,
   getAllCategories,
   getArticleAiHeaders,
   getArticleMarkdown,
@@ -12,6 +13,8 @@ import {
   getArticleMarkdownUrl,
   getArticleMetadata,
   getArticlesByCategory,
+  getArticlesByAuthor,
+  getAuthorBySlug,
   getAvailableArticleSlugs,
   sanitizeImagePath,
   searchArticles,
@@ -86,8 +89,9 @@ function mockDirectory(name: string): fs.Dirent {
 
 function setupArticleMock(frontmatter: string, body = 'Article body content.'): void {
   mockedFs.existsSync.mockReturnValue(true)
+  const authorLine = /^authors?:/m.test(frontmatter) ? '' : 'author: Test Author\n'
   mockedFs.readFileSync.mockReturnValue(
-    `---\ntitle: Test Article\nexcerpt: A test.\nauthor: Test Author\n${frontmatter}---\n\n${body}`
+    `---\ntitle: Test Article\nexcerpt: A test.\n${authorLine}${frontmatter}---\n\n${body}`
   )
   ;(mockedFs.readdirSync as jest.Mock).mockReturnValue([])
 }
@@ -131,7 +135,8 @@ function setupArticleTreeMock(articles: readonly MockArticle[]): void {
   mockedFs.readFileSync.mockImplementation((target) => {
     const article = articleFilePaths.get(target.toString())
     if (!article) throw new Error(`Unexpected file read: ${target.toString()}`)
-    return `---\ntitle: ${article.slug}\nexcerpt: Excerpt for ${article.slug}\nauthor: Test Author\n${article.frontmatter}---\n\n${article.body ?? 'Article body content.'}`
+    const authorLine = /^authors?:/m.test(article.frontmatter) ? '' : 'author: Test Author\n'
+    return `---\ntitle: ${article.slug}\nexcerpt: Excerpt for ${article.slug}\n${authorLine}${article.frontmatter}---\n\n${article.body ?? 'Article body content.'}`
   })
   ;(mockedFs.readdirSync as jest.Mock).mockImplementation((target: fs.PathLike) => {
     const targetPath = target.toString()
@@ -235,6 +240,158 @@ describe('getArticleMetadata - frontmatter parsing', () => {
       expect(article!.aiCrawl).toBe(expected)
     })
   })
+
+  it('resolves a configured author slug to the display name', async () => {
+    setupArticleMock('author: andrew-blase\n')
+    const article = await getArticleMetadata('test-slug', {
+      siteUrl: 'https://example.com',
+      siteName: 'Example',
+      authors: {
+        'andrew-blase': {
+          name: 'Andrew Blase',
+          slug: 'andrew-blase',
+          bio: 'Writer.',
+        },
+      },
+    })
+    expect(article).not.toBeNull()
+    expect(article!.author).toBe('Andrew Blase')
+  })
+
+  it('parses multi-author frontmatter', async () => {
+    setupArticleMock('authors:\n  - andrew-blase\n  - jane-doe\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.authors).toEqual(['andrew-blase', 'jane-doe'])
+  })
+
+  it('preserves explicit zero-author frontmatter', async () => {
+    setupArticleMock('authors: []\n')
+    const article = await getArticleMetadata('test-slug')
+    expect(article).not.toBeNull()
+    expect(article!.author).toBe('')
+    expect(article!.authors).toEqual([])
+  })
+})
+
+describe('author utilities', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  const config = {
+    siteUrl: 'https://example.com',
+    siteName: 'Example',
+    defaultAuthor: 'andrew-blase',
+    authors: {
+      'andrew-blase': {
+        name: 'Andrew Blase',
+        slug: 'andrew-blase',
+        bio: 'Writer.',
+      },
+      'jane-doe': {
+        name: 'Jane Doe',
+        slug: 'jane-doe',
+        bio: 'Guest writer.',
+      },
+    },
+  }
+
+  it('gets an author by slug with an auto-generated profile URL', () => {
+    expect(getAuthorBySlug('andrew-blase', config)).toEqual({
+      name: 'Andrew Blase',
+      slug: 'andrew-blase',
+      bio: 'Writer.',
+      url: 'https://example.com/articles/authors/andrew-blase',
+    })
+  })
+
+  it('resolves article authors from multi-author frontmatter first', () => {
+    const authors = getArticleAuthors(
+      {
+        slug: 'test',
+        title: 'Test',
+        excerpt: 'Test.',
+        author: 'Andrew Blase',
+        authors: ['jane-doe', 'andrew-blase'],
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '2 min read',
+        featuredImage: '/image.jpg',
+      },
+      config
+    )
+
+    expect(authors.map((author) => author.slug)).toEqual(['jane-doe', 'andrew-blase'])
+  })
+
+  it('returns no article authors when authors is explicitly empty', () => {
+    const authors = getArticleAuthors(
+      {
+        slug: 'test',
+        title: 'Test',
+        excerpt: 'Test.',
+        author: '',
+        authors: [],
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '2 min read',
+        featuredImage: '/image.jpg',
+      },
+      config
+    )
+
+    expect(authors).toEqual([])
+  })
+
+  it('does not duplicate the author when frontmatter author matches the default author', () => {
+    const authors = getArticleAuthors(
+      {
+        slug: 'test',
+        title: 'Test',
+        excerpt: 'Test.',
+        author: 'andrew-blase',
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '2 min read',
+        featuredImage: '/image.jpg',
+      },
+      config
+    )
+
+    expect(authors.map((author) => author.slug)).toEqual(['andrew-blase'])
+  })
+
+  it('does not duplicate the author when article.author is already resolved to the display name', () => {
+    // getArticleMetadata resolves article.author to the author's display name (e.g. "Andrew Blase")
+    // while config.defaultAuthor stays a slug (e.g. "andrew-blase") - these must dedupe to one author.
+    const authors = getArticleAuthors(
+      {
+        slug: 'test',
+        title: 'Test',
+        excerpt: 'Test.',
+        author: 'Andrew Blase',
+        category: 'Campaigns',
+        categories: ['Campaigns'],
+        readTime: '2 min read',
+        featuredImage: '/image.jpg',
+      },
+      config
+    )
+
+    expect(authors.map((author) => author.slug)).toEqual(['andrew-blase'])
+  })
+
+  it('filters articles by configured author', async () => {
+    setupArticleTreeMock([
+      { slug: 'andrew-post', frontmatter: 'date: 2025-01-01\nauthor: andrew-blase\n' },
+      { slug: 'jane-post', frontmatter: 'date: 2025-01-02\nauthor: jane-doe\n' },
+    ])
+
+    await expect(getArticlesByAuthor('jane-doe', config)).resolves.toEqual([
+      expect.objectContaining({ slug: 'jane-post' }),
+    ])
+  })
 })
 
 describe('getAvailableArticleSlugs', () => {

package/src/articleTypes.ts

@@ -21,6 +21,7 @@ export interface Article {
   date?: string
   lastmod?: string
   author: string
+  authors?: string[]
   category: string
   categories: string[]
   readTime: string
@@ -46,3 +47,35 @@ export interface CategoryInfo {
   count: number
   featuredImage: string
 }
+
+export interface AuthorSocial {
+  website?: string
+  facebook?: string
+  twitter?: string
+  x?: string
+  linkedin?: string
+  instagram?: string
+  youtube?: string
+  tiktok?: string
+  github?: string
+  bluesky?: string
+  threads?: string
+  mastodon?: string
+  medium?: string
+  newsletter?: string
+  other?: Record<string, string>
+}
+
+export interface AuthorProfile {
+  name: string
+  slug: string
+  bio: string
+  avatar?: string
+  url?: string
+  social?: AuthorSocial
+}
+
+export interface BreadcrumbItem {
+  name: string
+  url?: string
+}

package/src/articlesConfig.ts

@@ -1,3 +1,6 @@
+import type { ComponentType } from 'react'
+import type { AuthorProfile } from './articleTypes'
+
 /** Keys for each renderable section of the articles listing page. */
 export type ArticlesSection =
   | 'hero'
@@ -70,6 +73,52 @@ export interface HeroConfig {
 /** Controls how article body links set target/rel attributes. */
 export type LinkTargetStrategy = 'external-new-tab' | 'all-new-tab' | 'same-tab'
 
+/** React components that article MDX bodies can reference by JSX tag name. */
+export type MdxComponents = Record<string, ComponentType<never>>
+
+export type ArticleBreadcrumbToken =
+  | 'home'
+  | 'articles'
+  | 'primaryCategory'
+  | 'folderPath'
+  | 'articleTitle'
+export type CategoryBreadcrumbToken = 'home' | 'articles' | 'category'
+export type AuthorBreadcrumbToken = 'home' | 'articles' | 'authors' | 'authorName'
+
+export interface CustomBreadcrumbItem {
+  /** Label displayed in the breadcrumb trail. */
+  name: string
+  /** Custom URL. Relative paths are resolved against `siteUrl` by server builders. */
+  url: string
+}
+
+export type ArticleBreadcrumbEntry = ArticleBreadcrumbToken | CustomBreadcrumbItem
+export type CategoryBreadcrumbEntry = CategoryBreadcrumbToken | CustomBreadcrumbItem
+export type AuthorBreadcrumbEntry = AuthorBreadcrumbToken | CustomBreadcrumbItem
+
+export interface BreadcrumbLabels {
+  home?: string
+  articles?: string
+  authors?: string
+}
+
+export interface BreadcrumbsConfig {
+  /** Set to false to hide visible breadcrumbs and breadcrumb JSON-LD generated by the helper builders. */
+  show?: boolean
+  /** Separator used by the visible Breadcrumb component. Default: '>'. */
+  separator?: string
+  /** Set to false to render visible breadcrumbs without JSON-LD. Default: true. */
+  showSchema?: boolean
+  /** Article breadcrumb trail. Example: ['primaryCategory', { name: 'Guides', url: '/guides' }, 'articleTitle']. */
+  article?: ArticleBreadcrumbEntry[]
+  /** Category breadcrumb trail. Default: ['home', 'articles', 'category']. */
+  category?: CategoryBreadcrumbEntry[]
+  /** Author breadcrumb trail. Default: ['home', 'articles', 'authors', 'authorName']. */
+  author?: AuthorBreadcrumbEntry[]
+  /** Optional label overrides for built-in breadcrumb items. */
+  labels?: BreadcrumbLabels
+}
+
 /** Top-level configuration object. Pass one instance to every library component. */
 export interface ArticlesConfig {
   /** Canonical base URL of the site, used in metadata and JSON-LD. Example: `'https://yoursite.com'` */
@@ -105,8 +154,18 @@ export interface ArticlesConfig {
   showBackToArticles?: boolean
   /** Set to false to hide author names from UI and metadata. Default: true. */
   showAuthor?: boolean
+  /** Author profiles keyed by slug. Omit to keep plain string author display. */
+  authors?: Record<string, AuthorProfile>
+  /** Author slug used when article frontmatter omits author fields. */
+  defaultAuthor?: string
+  /** Set to false to disable copied author page routes in consuming apps. Default: true. */
+  showAuthorPage?: boolean
+  /** Set to false to disable breadcrumbs, or pass a config object to customize breadcrumb trails. */
+  breadcrumbs?: false | BreadcrumbsConfig
   /** Article body link target behavior. Default: `'external-new-tab'`. */
   linkTargetStrategy?: LinkTargetStrategy
+  /** Extra components exposed to article MDX bodies by JSX tag name. */
+  mdxComponents?: MdxComponents
 }
 
 export const DEFAULT_PAGE_SIZE = 6
@@ -119,3 +178,12 @@ export const DEFAULT_LAYOUT: ArticlesSection[] = [
   'latest',
   'categories',
 ]
+
+export function breadcrumbsAreEnabled(config: ArticlesConfig): boolean {
+  return config.breadcrumbs !== false && config.breadcrumbs?.show !== false
+}
+
+export function getBreadcrumbsConfig(config: ArticlesConfig): BreadcrumbsConfig {
+  if (config.breadcrumbs === false) return {}
+  return config.breadcrumbs ?? {}
+}

package/src/authorUtils.ts

@@ -0,0 +1,95 @@
+import type { ArticlesConfig } from './articlesConfig'
+import type { AuthorProfile, AuthorSocial } from './articleTypes'
+
+export function getAuthorUrl(author: AuthorProfile): string {
+  return author.url ?? `/articles/authors/${author.slug}`
+}
+
+export function getAuthorAvatar(
+  author: AuthorProfile,
+  config?: ArticlesConfig
+): string | undefined {
+  if (!author.avatar) return undefined
+  if (author.avatar.startsWith('http://') || author.avatar.startsWith('https://')) {
+    return author.avatar
+  }
+  const path = `/articles/authors/${author.slug}/${author.avatar.replace(/^\/+/, '')}`
+  if (!config) return path
+  return `${config.siteUrl.replace(/\/$/, '')}${path}`
+}
+
+export function getAuthorSameAs(author: AuthorProfile): string[] {
+  return getAuthorSocialLinks(author).map((link) => link.href)
+}
+
+export interface AuthorSocialLink {
+  label: string
+  href: string
+}
+
+function normalizeHandle(value: string): string {
+  return value.replace(/^@/, '')
+}
+
+function normalizeUrl(value: string, baseUrl?: string): string {
+  if (value.startsWith('http://') || value.startsWith('https://')) return value
+  if (!baseUrl) return value
+  return `${baseUrl}${normalizeHandle(value)}`
+}
+
+function getConfiguredSocialLinks(social: AuthorSocial): AuthorSocialLink[] {
+  return [
+    { label: 'Website', href: social.website ?? '' },
+    {
+      label: 'Facebook',
+      href: social.facebook ? normalizeUrl(social.facebook, 'https://www.facebook.com/') : '',
+    },
+    {
+      label: 'Twitter',
+      href: social.twitter ? normalizeUrl(social.twitter, 'https://twitter.com/') : '',
+    },
+    { label: 'X', href: social.x ? normalizeUrl(social.x, 'https://x.com/') : '' },
+    {
+      label: 'LinkedIn',
+      href: social.linkedin ? normalizeUrl(social.linkedin, 'https://www.linkedin.com/in/') : '',
+    },
+    {
+      label: 'Instagram',
+      href: social.instagram ? normalizeUrl(social.instagram, 'https://www.instagram.com/') : '',
+    },
+    {
+      label: 'YouTube',
+      href: social.youtube ? normalizeUrl(social.youtube, 'https://www.youtube.com/') : '',
+    },
+    {
+      label: 'TikTok',
+      href: social.tiktok ? normalizeUrl(social.tiktok, 'https://www.tiktok.com/@') : '',
+    },
+    {
+      label: 'GitHub',
+      href: social.github ? normalizeUrl(social.github, 'https://github.com/') : '',
+    },
+    {
+      label: 'Bluesky',
+      href: social.bluesky ? normalizeUrl(social.bluesky, 'https://bsky.app/profile/') : '',
+    },
+    {
+      label: 'Threads',
+      href: social.threads ? normalizeUrl(social.threads, 'https://www.threads.net/@') : '',
+    },
+    { label: 'Mastodon', href: social.mastodon ? normalizeUrl(social.mastodon) : '' },
+    {
+      label: 'Medium',
+      href: social.medium ? normalizeUrl(social.medium, 'https://medium.com/@') : '',
+    },
+    { label: 'Newsletter', href: social.newsletter ?? '' },
+  ]
+}
+
+export function getAuthorSocialLinks(author: AuthorProfile): AuthorSocialLink[] {
+  const social = author.social
+  if (!social) return []
+  const configuredLinks = getConfiguredSocialLinks(social)
+  const otherLinks = Object.entries(social.other ?? {}).map(([label, href]) => ({ label, href }))
+  return [...configuredLinks, ...otherLinks].filter((link) => link.href.trim().length > 0)
+}

package/src/index.ts

@@ -11,13 +11,11 @@ export { FeaturedArticle } from './FeaturedArticle'
 export { LatestArticles } from './LatestArticles'
 export { LatestArticlesSection } from './LatestArticlesSection'
 export { CategoryArticlesPage } from './CategoryArticlesPage'
-export {
-  ArticleSchema,
-  ArticleSEO,
-  BreadcrumbSchema,
-  CollectionPageSchema,
-  FAQPageSchema,
-} from './ArticleSchemas'
+export { AuthorArticlesPage } from './AuthorArticlesPage'
+export { AuthorCard, AuthorSocialLinks } from './AuthorCard'
+export { AuthorDetailHero } from './AuthorDetailHero'
+export { Breadcrumb, BreadcrumbSchema } from './Breadcrumb'
+export { ArticleSchema, ArticleSEO, CollectionPageSchema, FAQPageSchema } from './ArticleSchemas'
 
 export { ArticleSocialShare } from './ArticleSocialShare'
 export { ArticleNavigation } from './ArticleNavigation'
@@ -43,7 +41,32 @@ export type {
   CategoryDescription,
   CommentsConfig,
   LinkTargetStrategy,
+  MdxComponents,
+  BreadcrumbsConfig,
+  BreadcrumbLabels,
+  ArticleBreadcrumbToken,
+  CategoryBreadcrumbToken,
+  AuthorBreadcrumbToken,
+  ArticleBreadcrumbEntry,
+  CategoryBreadcrumbEntry,
+  AuthorBreadcrumbEntry,
+  CustomBreadcrumbItem,
+} from './articlesConfig'
+export {
+  DEFAULT_LAYOUT,
+  DEFAULT_PAGE_SIZE,
+  DEFAULT_CATEGORIES_PAGE_SIZE,
+  breadcrumbsAreEnabled,
+  getBreadcrumbsConfig,
 } from './articlesConfig'
-export { DEFAULT_LAYOUT, DEFAULT_PAGE_SIZE, DEFAULT_CATEGORIES_PAGE_SIZE } from './articlesConfig'
-export type { Article, CategoryInfo, FaqItem, HowToStep, TocItem } from './articleTypes'
+export type {
+  Article,
+  AuthorProfile,
+  AuthorSocial,
+  BreadcrumbItem,
+  CategoryInfo,
+  FaqItem,
+  HowToStep,
+  TocItem,
+} from './articleTypes'
 export type { ArticleComment, ArticleCommentWithReplies } from './commentTypes'

package/src/renderMdx.tsx

@@ -22,7 +22,9 @@ type MdxContent = ComponentType<{
 function makeImgComponent(basePath: string) {
   return function MdxImage({ src, alt, ...props }: ImgHTMLAttributes<HTMLImageElement>) {
     const resolvedSrc =
-      src && !src.startsWith('http') && !src.startsWith('/') ? `${basePath}/${src}` : src
+      typeof src === 'string' && !src.startsWith('http') && !src.startsWith('/')
+        ? `${basePath}/${src}`
+        : src
     return React.createElement('img', { src: resolvedSrc, alt, ...props })
   }
 }
@@ -43,6 +45,10 @@ export async function renderMdxSource(source: string, basePath?: string, config?
   })
 
   const Content = mdxModule.default as MdxContent
-  const components = basePath ? { img: makeImgComponent(basePath) } : undefined
+  const internalComponents = basePath ? { img: makeImgComponent(basePath) } : undefined
+  const components =
+    internalComponents || config?.mdxComponents
+      ? { ...internalComponents, ...config?.mdxComponents }
+      : undefined
   return <Content components={components as Record<string, ComponentType<unknown>>} />
 }