@fullstackdatasolutions/articles 0.8.2 → 0.10.0

package/README.md

@@ -74,6 +74,33 @@ export const siteConfig: ArticlesConfig = {
   siteUrl: 'https://yoursite.com',
   siteName: 'Your Site',
   pageSize: 6,
+  defaultAuthor: 'jane-doe',
+  authors: {
+    'jane-doe': {
+      slug: 'jane-doe',
+      name: 'Jane Doe',
+      bio: 'Jane writes about campaign operations and civic technology.',
+      avatar: '/authors/jane-doe.jpg',
+      social: {
+        website: 'https://yoursite.com/about',
+        facebook: 'janedoe',
+        twitter: '@janedoe',
+        x: 'janedoe',
+        linkedin: 'https://www.linkedin.com/in/janedoe',
+        other: {
+          Podcast: 'https://example.com/podcast',
+        },
+      },
+    },
+  },
+  breadcrumbs: {
+    article: [
+      { name: 'Resources', url: '/resources' },
+      'primaryCategory',
+      'folderPath',
+      'articleTitle',
+    ],
+  },
 }
 ```
 
@@ -97,16 +124,18 @@ import {
   ArticleNavigation,
   ArticleSEO,
   ArticleSocialShare,
-  BreadcrumbSchema,
+  Breadcrumb,
   CommentsSection,
   ScrollToTop,
 } from '@fullstackdatasolutions/articles'
 import {
   ArticleContent,
   ArticleTOC,
+  buildArticleBreadcrumbs,
   generateArticleMetadata,
   generateArticleStaticParams,
   getAdjacentArticles,
+  getArticleAuthors,
   getArticleMetadata,
 } from '@fullstackdatasolutions/articles/server'
 import { siteConfig } from '@/config/articles'
@@ -125,26 +154,31 @@ export async function generateMetadata({ params }: ArticlePageProps) {
 export default async function Page({ params }: ArticlePageProps) {
   const { slug: slugSegments } = await params
   const slug = normalizeSlug(slugSegments)
-  const article = await getArticleMetadata(slug)
+  const article = await getArticleMetadata(slug, siteConfig)
   if (!article) notFound()
   const { previous, next } = await getAdjacentArticles(slug)
+  const authors = getArticleAuthors(article, siteConfig)
+  const breadcrumbItems = buildArticleBreadcrumbs(article, siteConfig)
   const siteUrl = siteConfig.siteUrl.replace(/\/$/, '')
   const articleUrl = `${siteUrl}/articles/${slug}`
   return (
     <>
-      <ArticleSEO article={article} articleUrl={articleUrl} siteName={siteConfig.siteName} />
-      <BreadcrumbSchema
-        items={[
-          { name: 'Home', url: siteUrl },
-          { name: 'Articles', url: `${siteUrl}/articles` },
-          { name: article.title, url: articleUrl },
-        ]}
+      <ArticleSEO
+        article={article}
+        articleUrl={articleUrl}
+        siteName={siteConfig.siteName}
+        authors={authors}
+      />
+      <Breadcrumb items={breadcrumbItems} />
+      <ArticleDetailHero
+        article={article}
+        authors={authors}
+        categoryBasePath="/articles/category"
       />
-      <ArticleDetailHero article={article} categoryBasePath="/articles/category" />
       {siteConfig.showToc !== false && article.toc && article.toc.length > 0 && (
         <ArticleTOC toc={article.toc} />
       )}
-      <ArticleContent article={article} />
+      <ArticleContent article={article} config={siteConfig} />
       <ArticleSocialShare title={article.title} url={articleUrl} excerpt={article.excerpt} />
       {siteConfig.comments && <CommentsSection articleSlug={slug} config={siteConfig.comments} />}
       <ArticleNavigation previous={previous} next={next} basePath="/articles" />
@@ -169,10 +203,43 @@ export async function generateMetadata({ params }: CategoryPageProps) {
 }
 export default async function Page({ params }: CategoryPageProps) {
   const { category } = await params
-  const articles = await getArticlesByCategory(category)
+  const articles = await getArticlesByCategory(category, siteConfig)
   if (articles.length === 0) notFound()
   return <CategoryArticlesPage category={category} articles={articles} config={siteConfig} />
 }
+
+// app/articles/authors/[author]/page.tsx
+import { notFound } from 'next/navigation'
+import { AuthorArticlesPage, AuthorDetailHero, Breadcrumb } from '@fullstackdatasolutions/articles'
+import {
+  buildAuthorBreadcrumbs,
+  generateAuthorMetadata,
+  generateAuthorStaticParams,
+  getArticlesByAuthor,
+  getAuthorBySlug,
+} from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+type AuthorPageProps = Readonly<{ params: Promise<{ author: string }> }>
+export function generateStaticParams(): { author: string }[] {
+  return generateAuthorStaticParams(siteConfig)
+}
+export async function generateMetadata({ params }: AuthorPageProps) {
+  const { author } = await params
+  return generateAuthorMetadata(author, siteConfig)
+}
+export default async function Page({ params }: AuthorPageProps) {
+  const { author: authorSlug } = await params
+  const author = getAuthorBySlug(authorSlug, siteConfig)
+  if (!author) notFound()
+  const articles = await getArticlesByAuthor(authorSlug, siteConfig)
+  return (
+    <>
+      <Breadcrumb items={buildAuthorBreadcrumbs(author, siteConfig)} />
+      <AuthorDetailHero author={author} />
+      <AuthorArticlesPage author={author} articles={articles} config={siteConfig} />
+    </>
+  )
+}
 ```
 
 ### 6. Set up markdown handler (Next.js 16+)
@@ -197,7 +264,7 @@ import { rewriteArticleMarkdown } from '@fullstackdatasolutions/articles/middlew
 export async function proxy(request: NextRequest) {
   const mdRewrite = rewriteArticleMarkdown(request)
   if (mdRewrite) return mdRewrite
-  
+
   return NextResponse.next()
 }
 
@@ -246,7 +313,7 @@ Create `public/articles/[slug]/article.md` or `public/articles/[slug]/article.md
 ---
 title: Your Article Title
 excerpt: A one-sentence summary shown in cards and meta descriptions.
-author: Jane Doe
+authors: [jane-doe]
 tags: [campaigns, strategy]
 ---
 
@@ -255,6 +322,34 @@ Article body in Markdown...
 
 Article directories can be nested to any depth below `public/articles`. For example, `public/articles/game-system/article-name/article.mdx` is discovered as the slug `game-system/article-name`, and `public/articles/tov/subdirectory/article-name/article.md` is discovered as `tov/subdirectory/article-name`. Use a catch-all Next.js route such as `app/articles/[...slug]/page.tsx` and join the slug segments before calling the server helpers.
 
+Articles can have zero, one, or many authors:
+
+```markdown
+---
+title: Team Update
+excerpt: A post with no visible author.
+authors: []
+---
+```
+
+```markdown
+---
+title: Joint Post
+excerpt: A post with multiple authors.
+authors:
+  - jane-doe
+  - alex-smith
+---
+```
+
+The legacy `author: Jane Doe` string still works. Resolution order is:
+
+1. `authors: [...]` frontmatter
+2. `author: ...` frontmatter
+3. `defaultAuthor` from `ArticlesConfig`
+
+Use `authors: []` when an article should intentionally show no author, even if `defaultAuthor` is configured.
+
 ---
 
 ## Markdown handler exports
@@ -294,7 +389,7 @@ import { rewriteArticleMarkdown } from '@fullstackdatasolutions/articles/middlew
 export async function proxy(request: NextRequest) {
   const mdRewrite = rewriteArticleMarkdown(request)
   if (mdRewrite) return mdRewrite
-  
+
   return NextResponse.next()
 }
 ```
@@ -340,26 +435,92 @@ Use this if you don't need a custom API base path. For custom paths, use `create
 
 ## `ArticlesConfig` reference
 
-| Field                  | Type                                            | Default   | Description                                                                                                                             |
-| ---------------------- | ----------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `siteUrl`              | `string`                                        | —         | Canonical base URL. Used in metadata and JSON-LD.                                                                                       |
-| `siteName`             | `string`                                        | —         | Site name in title tags and JSON-LD.                                                                                                    |
-| `pageSize`             | `number`                                        | `6`       | Articles per page / per "Load more" click.                                                                                              |
-| `categoriesPageSize`   | `number`                                        | `8`       | Category cards before "Load more categories".                                                                                           |
-| `layout`               | `ArticlesSection[]`                             | see below | Ordered sections to render. Omit a key to hide it.                                                                                      |
-| `theme`                | `ArticlesTheme`                                 | —         | CSS custom-property overrides for colors and fonts.                                                                                     |
-| `categoryDescriptions` | `Record<string, string \| CategoryDescription>` | —         | Short/long text per category slug.                                                                                                      |
-| `hero`                 | `HeroConfig`                                    | —         | Hero section title and description. Omit to use built-in defaults.                                                                      |
-| `comments`             | `CommentsConfig`                                | —         | Comments feature config. Omit to disable entirely.                                                                                      |
-| `showToc`              | `boolean`                                       | `true`    | Show the table of contents on article detail pages. Set to `false` to hide on all articles.                                             |
-| `showBackToArticles`   | `boolean`                                       | `true`    | Show the back-navigation link on article detail pages. Set to `false` to hide `ArticleBackLink`.                                        |
-| `showAuthor`           | `boolean`                                       | `true`    | Show author names in UI and metadata. Set to `false` to omit author display, OpenGraph authors, JSON-LD author fields, and RSS authors. |
-| `description`          | `string`                                        | —         | Short description used as the RSS feed channel description. Falls back to `siteName` if omitted.                                        |
+| Field                  | Type                                                | Default              | Description                                                                                                                                         |
+| ---------------------- | --------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `siteUrl`              | `string`                                            | —                    | Canonical base URL. Used in metadata and JSON-LD.                                                                                                   |
+| `siteName`             | `string`                                            | —                    | Site name in title tags and JSON-LD.                                                                                                                |
+| `pageSize`             | `number`                                            | `6`                  | Articles per page / per "Load more" click.                                                                                                          |
+| `categoriesPageSize`   | `number`                                            | `8`                  | Category cards before "Load more categories".                                                                                                       |
+| `layout`               | `ArticlesSection[]`                                 | see below            | Ordered sections to render. Omit a key to hide it.                                                                                                  |
+| `theme`                | `ArticlesTheme`                                     | —                    | CSS custom-property overrides for colors and fonts.                                                                                                 |
+| `categoryDescriptions` | `Record<string, string \| CategoryDescription>`     | —                    | Short/long text per category slug.                                                                                                                  |
+| `hero`                 | `HeroConfig`                                        | —                    | Hero section title and description. Omit to use built-in defaults.                                                                                  |
+| `comments`             | `CommentsConfig`                                    | —                    | Comments feature config. Omit to disable entirely.                                                                                                  |
+| `showToc`              | `boolean`                                           | `true`               | Show the table of contents on article detail pages. Set to `false` to hide on all articles.                                                         |
+| `showBackToArticles`   | `boolean`                                           | `true`               | Show the back-navigation link on article detail pages. Set to `false` to hide `ArticleBackLink`.                                                    |
+| `showAuthor`           | `boolean`                                           | `true`               | Show author names in UI and metadata. Set to `false` to omit author display, OpenGraph authors, JSON-LD author fields, and RSS authors.             |
+| `showAuthorPage`       | `boolean`                                           | `true`               | Include configured author pages in sitemap output and enable author page helpers. Set to `false` to suppress author page generation.                |
+| `authors`              | `Record<string, AuthorProfile>`                     | `{}`                 | Configured author profiles keyed by slug. Slugs are used by frontmatter, author URLs, and JSON-LD `Person` data.                                    |
+| `defaultAuthor`        | `string`                                            | —                    | Default author slug or name used when article frontmatter omits both `authors` and `author`.                                                        |
+| `breadcrumbs`          | `false \| BreadcrumbsConfig`                        | default trails       | Set to `false` to hide breadcrumbs, or configure article/category/author breadcrumb trails, custom URL items, separator, schema output, and labels. |
+| `linkTargetStrategy`   | `'external-new-tab' \| 'all-new-tab' \| 'same-tab'` | `'external-new-tab'` | Controls article body links. Internal links open in the same window by default; external `http`/`https` links open in a new window.                 |
+| `description`          | `string`                                            | —                    | Short description used as the RSS feed channel description. Falls back to `siteName` if omitted.                                                    |
 
 **Default layout order:** `['hero', 'search', 'featured', 'latest', 'categories']`
 
 To add a newsletter section, pass `layout: ['hero','search','featured','latest','categories','newsletter']` — the library renders `null` for `'newsletter'` so you can append your own component after `<ArticlesPage />`.
 
+### Authors
+
+Author profiles are optional. If an article has no configured author and no plain `author` frontmatter, author UI and author metadata are omitted for that article.
+
+```ts
+authors: {
+  'jane-doe': {
+    slug: 'jane-doe',
+    name: 'Jane Doe',
+    bio: 'Jane writes about campaign operations and civic technology.',
+    avatar: '/authors/jane-doe.jpg',
+    url: 'https://example.com/team/jane-doe',
+    social: {
+      website: 'https://example.com',
+      facebook: 'janedoe',
+      twitter: '@janedoe',
+      x: 'janedoe',
+      linkedin: 'https://www.linkedin.com/in/janedoe',
+      instagram: 'janedoe',
+      youtube: '@janedoe',
+      tiktok: '@janedoe',
+      github: 'janedoe',
+      bluesky: 'janedoe.bsky.social',
+      threads: 'janedoe',
+      mastodon: 'https://mastodon.social/@janedoe',
+      medium: 'janedoe',
+      newsletter: 'https://example.com/newsletter',
+      other: {
+        Podcast: 'https://example.com/podcast',
+      },
+    },
+  },
+}
+```
+
+Only social fields with values are rendered. Handle-style values such as `twitter: '@janedoe'` and `linkedin: 'janedoe'` are normalized to full profile URLs; absolute URLs are left unchanged. `social.other` lets you add custom social or profile links with your own labels.
+
+### Breadcrumbs
+
+Breadcrumbs are visible by default. Disable them with `breadcrumbs: false`, or customize an article trail:
+
+```ts
+breadcrumbs: {
+  separator: '/',
+  showSchema: true,
+  article: [
+    { name: 'Resources', url: '/resources' },
+    'primaryCategory',
+    'folderPath',
+    { name: 'Campaign Library', url: 'https://example.com/library' },
+    'articleTitle',
+  ],
+  category: ['home', { name: 'Resources', url: '/resources' }, 'category'],
+  author: ['home', 'articles', { name: 'Team', url: '/team' }, 'authorName'],
+}
+```
+
+Breadcrumb trails can mix built-in tokens with custom URL items shaped as `{ name: string, url: string }`. Relative custom URLs beginning with `/` are resolved against `siteUrl`; absolute `http` and `https` URLs are left unchanged. The `folderPath` article token expands the article slug folders. For `public/articles/guides/field/example/article.md`, the trail above renders `Resources`, the primary tag, `Guides`, `Field`, `Campaign Library`, and the article title.
+
+Use `breadcrumbs: { show: false }` to disable both visible breadcrumbs and breadcrumb JSON-LD while keeping the rest of the breadcrumb config nearby. Use `showSchema: false` to keep visible breadcrumbs but omit breadcrumb JSON-LD.
+
 ---
 
 ## Theming
@@ -601,56 +762,14 @@ To enable RSS 2.0 feed generation at `/articles/feed.xml`, copy this route file
 
 ```ts
 // app/articles/feed.xml/route.ts
-import { getAllArticles } from '@fullstackdatasolutions/articles/server'
+import { generateRssFeed, getAllArticles } from '@fullstackdatasolutions/articles/server'
 import { siteConfig } from '@/config/articles'
 
 export const dynamic = 'force-static'
 
-function escapeXml(str: string): string {
-  return str
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&apos;')
-}
-
 export async function GET() {
-  const siteUrl = siteConfig.siteUrl.replace(/\/$/, '')
   const articles = await getAllArticles()
-  const showAuthor = siteConfig.showAuthor !== false
-
-  const items = articles
-    .map((article) => {
-      const url = `${siteUrl}/articles/${article.slug}`
-      const pubDate = article.date ? new Date(article.date).toUTCString() : ''
-      return [
-        '    <item>',
-        `      <title><![CDATA[${article.title}]]></title>`,
-        `      <link>${url}</link>`,
-        `      <guid isPermaLink="true">${url}</guid>`,
-        pubDate ? `      <pubDate>${pubDate}</pubDate>` : '',
-        article.excerpt ? `      <description><![CDATA[${article.excerpt}]]></description>` : '',
-        showAuthor && article.author ? `      <author>${escapeXml(article.author)}</author>` : '',
-        '    </item>',
-      ]
-        .filter(Boolean)
-        .join('\n')
-    })
-    .join('\n')
-
-  const description = siteConfig.description ?? `${siteConfig.siteName} articles`
-  const xml = `<?xml version="1.0" encoding="UTF-8" ?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
-  <channel>
-    <title><![CDATA[${siteConfig.siteName}]]></title>
-    <link>${siteUrl}/articles</link>
-    <description><![CDATA[${description}]]></description>
-    <language>en</language>
-    <atom:link href="${siteUrl}/articles/feed.xml" rel="self" type="application/rss+xml" />
-${items}
-  </channel>
-</rss>`
+  const xml = generateRssFeed(articles, siteConfig)
 
   return new Response(xml, {
     headers: {
@@ -662,6 +781,7 @@ ${items}
 ```
 
 - Uses `force-static` for build-time generation
+- Uses `generateRssFeed(articles, siteConfig)` from the package so RSS escaping, authors, descriptions, and feed URLs stay consistent across consuming apps
 - Uses `siteConfig.description` for the channel description field (falls back to `siteName` if omitted)
 - The `<link rel="alternate" type="application/rss+xml">` tag is added automatically to the articles index `<head>` via `generateArticlesIndexMetadata`
 
@@ -731,8 +851,8 @@ import { siteConfig } from '@/config/articles'
 
 export async function generateMetadata({ params }): Promise<Metadata> {
   const slug = (await params).slug.join('/')
-  const base = (await generateArticleMetadata(slug, siteConfig))
-  const article = await getArticleMetadata(slug)
+  const base = await generateArticleMetadata(slug, siteConfig)
+  const article = await getArticleMetadata(slug, siteConfig)
   if (!article) return base
 
   const markdownUrl = getArticleMarkdownUrl(article, siteConfig)
@@ -779,7 +899,7 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
 
 Returns article entries (priority 0.8, changeFrequency 'weekly') and category entries (priority 0.7, changeFrequency 'weekly'). Alternative: pass a plain URL string instead of `siteConfig`: `getArticleSitemapEntries('https://yoursite.com')`.
 
-JSON-LD structured data (`ArticleSchema`, `BreadcrumbSchema`, `CollectionPageSchema`) is rendered automatically inside the library components — no extra wiring required.
+JSON-LD structured data (`ArticleSchema`, `Breadcrumb`, `BreadcrumbSchema`, `CollectionPageSchema`) is rendered automatically inside the library components. Use `Breadcrumb` for visible navigation plus schema, or `BreadcrumbSchema` when you only need visually hidden breadcrumb schema output.
 
 ---
 
@@ -789,7 +909,8 @@ JSON-LD structured data (`ArticleSchema`, `BreadcrumbSchema`, `CollectionPageSch
 | --------------- | ---------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `title`         | `string`                                 | yes      | Article title. If omitted, falls back to the article slug with dashes replaced by spaces.                                                                                                                                                                                                |
 | `excerpt`       | `string`                                 | yes      | One-sentence summary for cards and meta. If omitted, resolves to an empty string.                                                                                                                                                                                                        |
-| `author`        | `string`                                 | no       | Defaults to `'Andrew Blase'`                                                                                                                                                                                                                                                             |
+| `author`        | `string`                                 | no       | Legacy single author slug or display name. Used when `authors` is omitted. Falls back to `defaultAuthor` only when configured.                                                                                                                                                           |
+| `authors`       | `string[]`                               | no       | Preferred multi-author list. Values should match `ArticlesConfig.authors` keys; unknown values still render as fallback author names. Use `authors: []` for an explicitly authorless article.                                                                                            |
 | `tags`          | `string[]`                               | no       | Used as categories. First tag = primary category. ArticleDetailHero displays at most 4 category tags; articles with more than 4 show only the first 4 in the hero.                                                                                                                       |
 | `date`          | `YYYY-MM-DD`                             | no       | Omit to publish immediately. Future dates hide until that date.                                                                                                                                                                                                                          |
 | `lastmod`       | `YYYY-MM-DD`                             | no       | Last modified date used by sitemap metadata when available.                                                                                                                                                                                                                              |
@@ -816,6 +937,7 @@ import {
   ArticleTOC,
   getAllArticles,
   getArticleMetadata,
+  getArticleAuthors,
   getArticleMarkdown,
   getArticleMarkdownResponse,
   getArticleMarkdownUrl,
@@ -823,6 +945,9 @@ import {
   getAiRobotsTxtRules,
   setArticlesErrorHandler,
   getArticlesByCategory,
+  getAuthorBySlug,
+  getAllAuthors,
+  getArticlesByAuthor,
   getAllCategories,
   getAvailableArticleSlugs,
   getAdjacentArticles,
@@ -833,10 +958,16 @@ import {
   extractToc,
   generateArticleStaticParams,
   generateCategoryStaticParams,
+  generateAuthorStaticParams,
   getArticleSitemapEntries,
+  generateRssFeed,
   generateArticlesIndexMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
+  generateAuthorMetadata,
+  buildArticleBreadcrumbs,
+  buildCategoryBreadcrumbs,
+  buildAuthorBreadcrumbs,
 } from '@fullstackdatasolutions/articles/server'
 ```