@fullstackdatasolutions/articles 0.9.0 → 0.11.0

package/src/seoUtils.ts

@@ -2,13 +2,25 @@ import type { Metadata, MetadataRoute } from 'next'
 import {
   getArticleMetadata,
   getAllArticles,
+  getAllAuthors,
   getAllCategories,
+  getArticleAuthors,
   getArticlesByCategory,
+  getAuthorBySlug,
   getArticleMarkdownUrl,
   getAvailableArticleSlugs,
+  categoryToSlug,
 } from './server-articles'
-import { ArticlesConfig } from './articlesConfig'
-import type { Article } from './articleTypes'
+import {
+  breadcrumbsAreEnabled,
+  getBreadcrumbsConfig,
+  type ArticlesConfig,
+  type ArticleBreadcrumbEntry,
+  type AuthorBreadcrumbEntry,
+  type CategoryBreadcrumbEntry,
+  type CustomBreadcrumbItem,
+} from './articlesConfig'
+import type { Article, AuthorProfile, BreadcrumbItem } from './articleTypes'
 
 function escapeXml(str: string): string {
   return str
@@ -72,6 +84,11 @@ export async function generateCategoryStaticParams(): Promise<{ category: string
   return categories.map((cat) => ({ category: cat.slug }))
 }
 
+export function generateAuthorStaticParams(config: ArticlesConfig): { author: string }[] {
+  if (config.showAuthorPage === false) return []
+  return getAllAuthors(config).map((author) => ({ author: author.slug }))
+}
+
 function resolveImageUrl(featuredImage: string, siteUrl: string): string {
   const base = siteUrl.replace(/\/$/, '')
   if (featuredImage.startsWith('http://') || featuredImage.startsWith('https://')) {
@@ -84,7 +101,7 @@ export async function generateArticleMetadata(
   slug: string,
   config: ArticlesConfig
 ): Promise<Metadata> {
-  const article = await getArticleMetadata(slug)
+  const article = await getArticleMetadata(slug, config)
 
   if (!article) {
     return {
@@ -102,6 +119,7 @@ export async function generateArticleMetadata(
   const description = article.excerpt ?? `Read ${article.title} on ${config.siteName}.`
   const showAuthor = config.showAuthor !== false
   const markdownUrl = getArticleMarkdownUrl(article, config)
+  const authorNames = getArticleAuthors(article, config).map((author) => author.name)
 
   return {
     title: `${article.title} | ${config.siteName}`,
@@ -117,7 +135,7 @@ export async function generateArticleMetadata(
       type: 'article',
       ...(article.date && { publishedTime: article.date }),
       ...(article.lastmod && { modifiedTime: new Date(article.lastmod).toISOString() }),
-      ...(showAuthor && { authors: [article.author] }),
+      ...(showAuthor && authorNames.length > 0 && { authors: authorNames }),
       tags: article.tags ?? [],
     },
     twitter: {
@@ -146,7 +164,7 @@ export async function generateArticleMetadata(
       },
     },
     other: {
-      ...(showAuthor && { 'article:author': article.author }),
+      ...(showAuthor && authorNames.length > 0 && { 'article:author': authorNames.join(', ') }),
       ...(article.date && {
         'article:published_time': new Date(article.date).toISOString(),
       }),
@@ -252,6 +270,195 @@ export async function generateCategoryMetadata(
   }
 }
 
+export async function generateAuthorMetadata(
+  authorSlug: string,
+  config: ArticlesConfig
+): Promise<Metadata> {
+  const author = getAuthorBySlug(authorSlug, config)
+
+  if (!author || config.showAuthorPage === false) return { title: 'Author Not Found' }
+
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const authorUrl = author.url ?? `${siteUrl}/articles/authors/${author.slug}`
+  const title = `${author.name} Articles | ${config.siteName}`
+
+  return {
+    title,
+    description: author.bio,
+    openGraph: {
+      title,
+      description: author.bio,
+      url: authorUrl,
+      siteName: config.siteName,
+      type: 'profile',
+      locale: 'en_US',
+      ...(author.avatar && { images: [{ url: resolveAuthorAvatar(author, config) }] }),
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description: author.bio,
+      ...(author.avatar && { images: [resolveAuthorAvatar(author, config)] }),
+    },
+    alternates: {
+      canonical: authorUrl,
+    },
+    robots: {
+      index: true,
+      follow: true,
+    },
+  }
+}
+
+function formatCategoryName(category: string): string {
+  return category
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+export function buildArticleBreadcrumbs(
+  article: Pick<Article, 'slug' | 'title' | 'category'>,
+  config: ArticlesConfig
+): BreadcrumbItem[] {
+  if (!breadcrumbsAreEnabled(config)) return []
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const breadcrumbConfig = getBreadcrumbsConfig(config)
+  const labels = breadcrumbConfig.labels ?? {}
+  const categorySlug = categoryToSlug(article.category)
+  const trail = breadcrumbConfig.article ?? ['home', 'articles', 'primaryCategory', 'articleTitle']
+  const folderSegments = article.slug.split('/').filter(Boolean).slice(0, -1)
+  return trail.flatMap((token): BreadcrumbItem[] =>
+    buildArticleBreadcrumbToken(token, {
+      article,
+      siteUrl,
+      categorySlug,
+      folderSegments,
+      labels,
+    })
+  )
+}
+
+export function buildCategoryBreadcrumbs(
+  category: string,
+  config: ArticlesConfig,
+  categoryName = formatCategoryName(category)
+): BreadcrumbItem[] {
+  if (!breadcrumbsAreEnabled(config)) return []
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const breadcrumbConfig = getBreadcrumbsConfig(config)
+  const labels = breadcrumbConfig.labels ?? {}
+  const trail = breadcrumbConfig.category ?? ['home', 'articles', 'category']
+  return trail.flatMap((entry): BreadcrumbItem[] =>
+    buildCategoryBreadcrumbEntry(entry, { categoryName, siteUrl, labels })
+  )
+}
+
+export function buildAuthorBreadcrumbs(
+  author: AuthorProfile,
+  config: ArticlesConfig
+): BreadcrumbItem[] {
+  if (!breadcrumbsAreEnabled(config)) return []
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const breadcrumbConfig = getBreadcrumbsConfig(config)
+  const labels = breadcrumbConfig.labels ?? {}
+  const trail = breadcrumbConfig.author ?? ['home', 'articles', 'authors', 'authorName']
+  return trail.flatMap((entry): BreadcrumbItem[] =>
+    buildAuthorBreadcrumbEntry(entry, { author, siteUrl, labels })
+  )
+}
+
+type BreadcrumbLabels = NonNullable<ReturnType<typeof getBreadcrumbsConfig>['labels']>
+
+function isCustomBreadcrumbItem(entry: unknown): entry is CustomBreadcrumbItem {
+  return typeof entry === 'object' && entry !== null && 'name' in entry && 'url' in entry
+}
+
+function resolveCustomBreadcrumbItem(item: CustomBreadcrumbItem, siteUrl: string): BreadcrumbItem {
+  if (item.url.startsWith('/')) return { name: item.name, url: `${siteUrl}${item.url}` }
+  return { name: item.name, url: item.url }
+}
+
+function buildArticleBreadcrumbToken(
+  entry: ArticleBreadcrumbEntry,
+  context: Readonly<{
+    article: Pick<Article, 'slug' | 'title' | 'category'>
+    siteUrl: string
+    categorySlug: string
+    folderSegments: string[]
+    labels: BreadcrumbLabels
+  }>
+): BreadcrumbItem[] {
+  if (isCustomBreadcrumbItem(entry)) {
+    return [resolveCustomBreadcrumbItem(entry, context.siteUrl)]
+  }
+  if (entry === 'home') return [{ name: context.labels.home ?? 'Home', url: context.siteUrl }]
+  if (entry === 'articles') {
+    return [{ name: context.labels.articles ?? 'Articles', url: `${context.siteUrl}/articles` }]
+  }
+  if (entry === 'primaryCategory') {
+    return [
+      {
+        name: context.article.category,
+        url: `${context.siteUrl}/articles/category/${context.categorySlug}`,
+      },
+    ]
+  }
+  if (entry === 'folderPath') {
+    return context.folderSegments.map((segment, index) => ({
+      name: formatCategoryName(segment),
+      url: `${context.siteUrl}/articles/${context.folderSegments.slice(0, index + 1).join('/')}`,
+    }))
+  }
+  return [{ name: context.article.title }]
+}
+
+function buildCategoryBreadcrumbEntry(
+  entry: CategoryBreadcrumbEntry,
+  context: Readonly<{ categoryName: string; siteUrl: string; labels: BreadcrumbLabels }>
+): BreadcrumbItem[] {
+  if (isCustomBreadcrumbItem(entry)) {
+    return [resolveCustomBreadcrumbItem(entry, context.siteUrl)]
+  }
+  if (entry === 'home') return [{ name: context.labels.home ?? 'Home', url: context.siteUrl }]
+  if (entry === 'articles') {
+    return [{ name: context.labels.articles ?? 'Articles', url: `${context.siteUrl}/articles` }]
+  }
+  return [{ name: context.categoryName }]
+}
+
+function buildAuthorBreadcrumbEntry(
+  entry: AuthorBreadcrumbEntry,
+  context: Readonly<{ author: AuthorProfile; siteUrl: string; labels: BreadcrumbLabels }>
+): BreadcrumbItem[] {
+  if (isCustomBreadcrumbItem(entry)) {
+    return [resolveCustomBreadcrumbItem(entry, context.siteUrl)]
+  }
+  if (entry === 'home') return [{ name: context.labels.home ?? 'Home', url: context.siteUrl }]
+  if (entry === 'articles') {
+    return [{ name: context.labels.articles ?? 'Articles', url: `${context.siteUrl}/articles` }]
+  }
+  if (entry === 'authors') {
+    return [
+      {
+        name: context.labels.authors ?? 'Authors',
+        url: `${context.siteUrl}/articles/authors`,
+      },
+    ]
+  }
+  return [{ name: context.author.name }]
+}
+
+export function resolveAuthorAvatar(author: AuthorProfile, config: ArticlesConfig): string {
+  if (!author.avatar) return ''
+  if (author.avatar.startsWith('http://') || author.avatar.startsWith('https://')) {
+    return author.avatar
+  }
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  return `${siteUrl}/articles/authors/${author.slug}/${author.avatar.replace(/^\/+/, '')}`
+}
+
 export async function getArticleSitemapEntries(
   baseUrlOrConfig: string | ArticlesConfig
 ): Promise<MetadataRoute.Sitemap> {
@@ -260,7 +467,10 @@ export async function getArticleSitemapEntries(
   ).replace(/\/$/, '')
 
   try {
-    const [articles, categories] = await Promise.all([getAllArticles(), getAllCategories()])
+    const [articles, categories] = await Promise.all([
+      getAllArticles(typeof baseUrlOrConfig === 'string' ? undefined : baseUrlOrConfig),
+      getAllCategories(),
+    ])
 
     const articleEntries: MetadataRoute.Sitemap = articles.map((article) => {
       const dateStr = article.lastmod ?? article.date
@@ -280,7 +490,16 @@ export async function getArticleSitemapEntries(
       priority: 0.7,
     }))
 
-    return [...articleEntries, ...categoryEntries]
+    const authorEntries: MetadataRoute.Sitemap =
+      typeof baseUrlOrConfig === 'string' || baseUrlOrConfig.showAuthorPage === false
+        ? []
+        : getAllAuthors(baseUrlOrConfig).map((author) => ({
+            url: `${baseUrl}/articles/authors/${author.slug}`,
+            changeFrequency: 'monthly' as const,
+            priority: 0.6,
+          }))
+
+    return [...articleEntries, ...categoryEntries, ...authorEntries]
   } catch {
     return []
   }

package/src/server-articles.ts

@@ -4,7 +4,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import readingTime from 'reading-time'
 import { markdownToHtml, extractToc } from './markdown'
-import type { Article, CategoryInfo, FaqItem, HowToStep } from './articleTypes'
+import type { Article, AuthorProfile, CategoryInfo, FaqItem, HowToStep } from './articleTypes'
 import type { ArticlesConfig } from './articlesConfig'
 import { reportArticlesError } from './errorReporting'
 
@@ -153,7 +153,81 @@ function parseHowToSteps(raw: unknown): HowToStep[] | undefined {
   return steps.length ? steps : undefined
 }
 
-async function getArticleSummary(slug: string): Promise<Article | null> {
+function parseAuthors(raw: unknown): string[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  const authors = raw.filter(
+    (author): author is string => typeof author === 'string' && author.trim().length > 0
+  )
+  return authors
+}
+
+export function getAuthorBySlug(slug: string, config: ArticlesConfig): AuthorProfile | null {
+  const profile = config.authors?.[slug]
+  if (!profile) return null
+  return {
+    ...profile,
+    url: profile.url ?? `${config.siteUrl.replace(/\/$/, '')}/articles/authors/${profile.slug}`,
+  }
+}
+
+function getConfiguredAuthorByName(name: string, config: ArticlesConfig): AuthorProfile | null {
+  const normalizedName = name.trim().toLowerCase()
+  const profile = Object.values(config.authors ?? {}).find(
+    (author) => author.name.toLowerCase() === normalizedName
+  )
+  return profile ? getAuthorBySlug(profile.slug, config) : null
+}
+
+function resolveArticleAuthorName(
+  rawAuthor: unknown,
+  rawAuthors: unknown,
+  config?: ArticlesConfig
+): string {
+  const authorArray = parseAuthors(rawAuthors)
+  const firstAuthor = authorArray?.[0]
+  const rawAuthorValue = typeof rawAuthor === 'string' && rawAuthor.trim() ? rawAuthor : undefined
+  const author = firstAuthor ?? rawAuthorValue
+  const resolved = author ?? config?.defaultAuthor
+  if (!resolved) return ''
+  if (!config) return resolved
+  return (
+    getAuthorBySlug(resolved, config)?.name ??
+    getConfiguredAuthorByName(resolved, config)?.name ??
+    resolved
+  )
+}
+
+export function getArticleAuthors(article: Article, config: ArticlesConfig): AuthorProfile[] {
+  const fallbackAuthors = Array.from(
+    new Set(
+      [article.author, config.defaultAuthor].filter(
+        (author): author is string => typeof author === 'string' && author.trim().length > 0
+      )
+    )
+  )
+  const authorValues = article.authors ?? fallbackAuthors
+  if (authorValues.length === 0) return []
+  const resolvedAuthors = authorValues
+    .map((author) => getAuthorBySlug(author, config) ?? getConfiguredAuthorByName(author, config))
+    .filter((author): author is AuthorProfile => author !== null)
+    .filter((author, index, all) => all.findIndex((a) => a.slug === author.slug) === index)
+
+  if (resolvedAuthors.length > 0) return resolvedAuthors
+
+  return authorValues.map((fallbackName) => ({
+    name: fallbackName,
+    slug: categoryToSlug(fallbackName),
+    bio: '',
+  }))
+}
+
+export function getAllAuthors(config: ArticlesConfig): AuthorProfile[] {
+  return Object.keys(config.authors ?? {})
+    .map((slug) => getAuthorBySlug(slug, config))
+    .filter((author): author is AuthorProfile => author !== null)
+}
+
+async function getArticleSummary(slug: string, config?: ArticlesConfig): Promise<Article | null> {
   try {
     const found = findArticleFile(slug)
     if (!found) return null
@@ -171,7 +245,8 @@ async function getArticleSummary(slug: string): Promise<Article | null> {
       excerpt: data.excerpt || '',
       date: parseDateField(data.date),
       lastmod: parseDateField(data.lastmod),
-      author: data.author || 'Andrew Blase',
+      author: resolveArticleAuthorName(data.author, data.authors, config),
+      authors: parseAuthors(data.authors),
       category: categories[0],
       categories,
       readTime,
@@ -200,7 +275,7 @@ async function getArticleSummary(slug: string): Promise<Article | null> {
 export const getArticleMetadata = cache(
   async (slug: string, config?: ArticlesConfig): Promise<Article | null> => {
     try {
-      const summary = await getArticleSummary(slug)
+      const summary = await getArticleSummary(slug, config)
       if (!summary) return null
       const found = findArticleFile(slug)
       if (!found) return null
@@ -227,9 +302,9 @@ export const getArticleMetadata = cache(
   }
 )
 
-export const getAllArticles = cache(async (): Promise<Article[]> => {
+export const getAllArticles = cache(async (config?: ArticlesConfig): Promise<Article[]> => {
   const slugs = getAvailableArticleSlugs()
-  const articles = await Promise.all(slugs.map((slug) => getArticleSummary(slug)))
+  const articles = await Promise.all(slugs.map((slug) => getArticleSummary(slug, config)))
   const currentDate = new Date().toISOString().split('T')[0]
   return articles
     .filter((article): article is Article => article !== null)
@@ -339,8 +414,8 @@ export async function getAiRobotsTxtRules(): Promise<string> {
 }
 
 export async function searchArticles(query: string, config?: ArticlesConfig): Promise<Article[]> {
-  if (!query?.trim()) return getAllArticles()
-  const articles = await getAllArticles()
+  if (!query?.trim()) return getAllArticles(config)
+  const articles = await getAllArticles(config)
   const searchTerm = query.toLowerCase().trim()
   const includeAuthor = config?.showAuthor !== false
   return articles.filter((article) => {
@@ -383,11 +458,24 @@ export async function getAllCategories(): Promise<CategoryInfo[]> {
     .sort((a, b) => b.count - a.count)
 }
 
-export async function getArticlesByCategory(categorySlug: string): Promise<Article[]> {
-  const articles = await getAllArticles()
+export async function getArticlesByCategory(
+  categorySlug: string,
+  config?: ArticlesConfig
+): Promise<Article[]> {
+  const articles = await getAllArticles(config)
   return articles.filter((article) =>
     article.categories.some((cat) => categoryToSlug(cat) === categorySlug)
   )
 }
 
+export async function getArticlesByAuthor(
+  authorSlug: string,
+  config: ArticlesConfig
+): Promise<Article[]> {
+  const articles = await getAllArticles(config)
+  return articles.filter((article) =>
+    getArticleAuthors(article, config).some((author) => author.slug === authorSlug)
+  )
+}
+
 export { sanitizeImagePath }

package/src/server.ts

@@ -7,10 +7,14 @@ export {
   getArticleMarkdownResponse,
   getArticleMarkdownUrl,
   getArticleMetadata,
+  getArticleAuthors,
   getAvailableArticleSlugs,
   getAdjacentArticles,
+  getAllAuthors,
   searchArticles,
+  getAuthorBySlug,
   getAllCategories,
+  getArticlesByAuthor,
   getArticlesByCategory,
   categoryToSlug,
   sanitizeImagePath,
@@ -20,18 +24,32 @@ export {
   generateRssFeed,
   generateArticleStaticParams,
   generateCategoryStaticParams,
+  generateAuthorStaticParams,
   generateArticlesIndexMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
+  generateAuthorMetadata,
+  buildArticleBreadcrumbs,
+  buildCategoryBreadcrumbs,
+  buildAuthorBreadcrumbs,
+  resolveAuthorAvatar,
   getArticleSitemapEntries,
 } from './seoUtils'
 
 export { markdownToHtml, extractToc } from './markdown'
 export { setArticlesErrorHandler } from './errorReporting'
+export { getBreadcrumbsConfig } from './articlesConfig'
 export { ArticleContent } from './ArticleContent'
 export { ArticleTOC } from './ArticleTOC'
 
-export type { Article, CategoryInfo, TocItem } from './articleTypes'
+export type {
+  Article,
+  AuthorProfile,
+  AuthorSocial,
+  BreadcrumbItem,
+  CategoryInfo,
+  TocItem,
+} from './articleTypes'
 export type { ArticlesConfig, LinkTargetStrategy } from './articlesConfig'
 export type {
   ArticlesErrorCode,