@fullstackdatasolutions/articles 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,243 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.11.0] - 2026-07-30
+
+### Added
+
+- Added `mdxComponents` to `ArticlesConfig`, allowing consuming apps to register React components for explicit use inside article MDX bodies. Registered components are merged with the package's built-in MDX image override.
+
+## [0.10.0] - 2026-07-23
+
+### Added
+
+- Added configured author profiles with social links, avatar support, default authors, and optional generated author pages.
+- Added zero-author and multi-author article support via `authors: []` and `authors: [author-slug]` frontmatter while preserving the legacy `author` fallback.
+- Added author social profile fields for website, Facebook, Twitter, X, LinkedIn, Instagram, YouTube, TikTok, GitHub, Bluesky, Threads, Mastodon, Medium, newsletter, and custom `other` links. Empty social fields are omitted from rendered author UI.
+- Added author server utilities: `getAuthorBySlug`, `getArticleAuthors`, `getAllAuthors`, `getArticlesByAuthor`, `generateAuthorStaticParams`, and `generateAuthorMetadata`.
+- Added `AuthorCard`, `AuthorDetailHero`, `AuthorArticlesPage`, and visible `Breadcrumb` components.
+- Added optional breadcrumb builders for article, category, and author pages with configurable trails, custom URL entries at any position, folder-path expansion, label overrides, separators, and JSON-LD control.
+
+### Changed
+
+- Article JSON-LD now emits full `Person` objects for configured authors.
+- Article, category, search, feed, and sitemap helpers can resolve configured author display names when passed `ArticlesConfig`.
+- The reference app now exposes `/articles/authors/[author]` pages, shows configured author bylines, and uses visible breadcrumbs on article and category routes.
+
+## [0.9.0] - 2026-07-06
+
+### Added
+
+- Added `linkTargetStrategy` to `ArticlesConfig` with three article body link behaviors: `external-new-tab` (default), `all-new-tab`, and `same-tab`.
+- Added `generateRssFeed(articles, config)` to the server exports so consuming apps can delegate RSS XML generation to the package.
+
+### Changed
+
+- Article body links now default to opening internal links in the same window and external `http`/`https` links in a new window with `rel="noopener noreferrer"`.
+- `getArticleMetadata(slug, config?)`, `ArticleContent`, and MDX rendering now accept article config so Markdown and MDX links share the same target behavior.
+- The README article route examples now pass `siteConfig` into article metadata/content rendering, and the RSS route example uses `generateRssFeed`.
+
+## [0.8.2] - 2026-05-27
+
+### Added
+
+- Added test coverage for `aiCrawl` wiring: robots.txt AI rules integration, markdown route handler (`GET /articles/[slug].md`), and `generateMetadata` aiCrawl behavior in the article detail page.
+
+### Documentation
+
+- README: added concrete wiring examples for `aiCrawl` integration in consuming apps - `getAiRobotsTxtRules` usage in `robots.txt` route, `generateMetadata` alternates pattern for markdown alternate links, and `robots` string for `noai`/`noimageai` directives.
+- README: added explicit warning that `headers()` from `next/headers` is read-only in Next.js App Router pages and cannot be used to set response headers - `getArticleAiHeaders` must only be called from Route Handlers.
+
+### Fixed
+
+- Removed dead code in article detail page that referenced `headers()` and `getArticleAiHeaders` in a Server Component context, causing TypeScript errors.
+
+## [0.8.1] - 2026-06-01
+
+## [0.8.0] - 2026-05-26
+
+### Added
+
+- Added `aiCrawl` article frontmatter support. Only articles with `aiCrawl: true` expose markdown twins, markdown alternate metadata, and markdown route helper responses.
+- Added AI crawl server helpers: `getArticleMarkdown`, `getArticleMarkdownResponse`, `getArticleMarkdownUrl`, `getArticleAiHeaders`, and `getAiRobotsTxtRules`.
+- Added `showAuthor` to `ArticlesConfig` to hide author names from UI, generated metadata, JSON-LD, RSS examples, and optional author search matching.
+- Added `setArticlesErrorHandler` so installed apps can route article package errors to their own logging or observability system.
+
+### Dependencies
+
+- `remark-github-blockquote-alert` updated from `^1.3.1` to `^2.1.0`
+
+## [0.7.2] - 2026-05-22
+
+### Added
+
+- Added npm `funding` metadata pointing to the Buy Me a Coffee support page.
+- Added a dependency-free `postinstall` message that thanks users for installing the package and links to the support page.
+
+## [0.7.1] - 2026-05-21
+
+### Fixed
+
+- Internal anchor links (href starting with `#`) no longer open in a new tab. The `customRenderer` rehype plugin now checks for internal anchors before applying `target="_blank"` and `rel="noopener noreferrer"`.
+- Article discovery now continues walking inside directories that are also articles, so nested articles at any depth are included in `getAllArticles()`, sitemap entries, RSS feeds, and static params.
+- README route examples now use the catch-all `app/articles/[...slug]/page.tsx` pattern required for slash-separated nested article slugs.
+
+### Added
+
+- `ArticleBackLink` component - renders a back-navigation link on article detail pages. Returns `null` when `config.showBackToArticles === false`. Accepts `config`, optional `href` (default `/articles`), optional `label` (default `Back to Articles`), and optional `className` props.
+- Test coverage added across `markdown.ts`, `ArticleBackLink.tsx`, `articlesConfig.ts`, and `server-articles.ts`, including coverage for nested article discovery.
+
+## [0.7.0] - 2026-05-20
+
+### Added
+
+- MDX articles now apply the same explicit Tailwind utility classes as Markdown articles. The shared `customRenderer` rehype plugin is passed to `evaluate()` so heading, paragraph, list, blockquote, code, table, and image elements are styled identically across both content types.
+- MDX image resolution: relative `src` values in MDX articles are resolved to `/articles/{slug}/{filename}` at render time via an injected `img` component. Absolute URLs and paths starting with `/` are left unchanged.
+- MDX rendering now includes `remarkGfm`, `remarkGithubBlockquoteAlert`, `rehypeSlug`, `rehypeAutolinkHeadings`, and `rehypePrism` - matching the full Markdown pipeline.
+
+### Changed
+
+- `customRenderer` in `markdown.ts` is now exported so it can be shared between the Markdown and MDX pipelines.
+- `ArticleContent` passes `/articles/{article.slug}` as `basePath` to `renderMdxSource`, enabling correct image URL resolution for both flat and nested article slugs.
+- `renderMdxSource` accepts an optional `basePath` parameter. When provided, a custom `img` component is injected into the MDX component tree to resolve relative image paths.
+
+## [0.6.0] - 2026-05-21
+
+### Changed
+
+- `getAvailableArticleSlugs()` now discovers article directories recursively under `public/articles`, so nested articles such as `public/articles/game-system/article-name/article.mdx` produce the slug `game-system/article-name`.
+
+## [0.5.1] - 2026-05-20
+
+### Added
+
+- `ArticleTOC` is now exported from `@fullstackdatasolutions/articles/server`, so server route examples can import the server component without pulling from the client entry point.
+
+### Changed
+
+- README route examples now use the actual article detail wiring with `getArticleMetadata`, `ArticleContent`, `ArticleDetailHero`, `ArticleSEO`, social sharing, comments, navigation, and scroll-to-top instead of referencing a nonexistent `ArticlePage` export.
+- README category route examples now import `CategoryArticlesPage` from the main package entry and fetch category articles with `getArticlesByCategory`.
+- README frontmatter reference now documents `lastmod`, `draft`, `faq`, `howTo`, `canonicalUrl`, `articleType`, `series`, MDX support, image resolution, generated reading time, and generated table of contents.
+- README server utility examples now include all exported helpers, including static param generators, markdown helpers, `sanitizeImagePath`, `ArticleContent`, and `ArticleTOC`.
+
+### Fixed
+
+- README comments setup now includes the required `app/api/articles/comments-store.ts` helper and correctly documents file-backed `comments.json` storage instead of PostgreSQL/Prisma storage.
+- README `ArticleTOC` guidance now imports from `@fullstackdatasolutions/articles/server`, matching the server-only usage guidance.
+
+## [0.5.0] - 2026-05-19
+
+### Added
+
+- `ArticleTOC` component - server component (no `'use client'`) that renders `article.toc[]` as an inline nav block above article content. Indentation: h2=0rem, h3=1rem, h4=2rem (based on `item.depth - 2`). Returns `null` when toc is empty. Controlled by `siteConfig.showToc` (gate: `showToc !== false && article.toc?.length > 0`). Exported from index.ts.
+- `ScrollToTop` component - client component (`'use client'`) that renders a fixed-position floating button (bottom-right corner) appearing when user scrolls past 300px. Smooth-scrolls back to top on click. No props. Exported from index.ts.
+- `showToc?: boolean` field on `ArticlesConfig` - optional, defaults to `true` when omitted. Set to `false` to hide the table of contents on all article detail pages.
+- `description?: string` field on `ArticlesConfig` - optional. Short description used as the RSS feed channel description. Falls back to `siteName` if omitted.
+- RSS feed route reference implementation - copy `app/articles/feed.xml/route.ts` from the reference app into consuming apps to enable an RSS 2.0 feed at `/articles/feed.xml`. Uses `force-static` for build-time generation. Uses `getAllArticles` from `@fullstackdatasolutions/articles/server`. Uses `siteConfig.description` for channel description field.
+
+### Changed
+
+- `generateArticlesIndexMetadata` now includes `alternates.types['application/rss+xml']` pointing to `${siteUrl}/articles/feed.xml`, automatically adding `<link rel="alternate" type="application/rss+xml">` to the articles index page head.
+
+## [0.4.3] - 2026-05-18
+
+### Added
+
+- `generateArticlesIndexMetadata(config: ArticlesConfig): Metadata` - generates full Next.js metadata for the articles index page (`/articles`). Returns title, description, OpenGraph (`type: 'website'`), Twitter Card, canonical URL, and robots directives. Description falls back to `config.hero?.description` when set. Export from `@fullstackdatasolutions/articles/server`.
+
+## [0.4.2] - 2026-05-18
+
+### Changed
+
+- `getArticleSitemapEntries` now accepts `string | ArticlesConfig`. Pass your `ArticlesConfig` directly instead of extracting `config.siteUrl` manually. Passing a plain URL string still works (backwards compatible).
+
+## [0.4.1] - 2026-05-18
+
+### Fixed
+
+- `CategoryArticlesPage` hero section now uses inline styles for critical layout (`position`, `height`, `overflow`, `z-index`, overlay background). Previously relied on Tailwind classes (`relative h-72 md:h-96`, `absolute inset-0`, `bg-black/60`, `relative z-10`) which have no effect on consuming apps that do not configure Tailwind to scan the package source. Follows the same fix applied to `ArticleCategoryGrid` images in v0.2.1.
+- `ArticleDetailHero` now defaults `categoryBasePath` to `'/articles/category'`, so category tags render as links out of the box. Pass `categoryBasePath=""` to suppress links. Previously omitting the prop produced plain `<span>` elements with no navigation.
+- `ArticleDetailHero` `<Image>` now includes `style={{ objectFit: 'cover' }}` in addition to `className="object-cover"`, ensuring the image fills the hero container correctly on consuming apps where Tailwind may not process the package source.
+
+## [0.4.0] - 2026-05-18
+
+### Added
+
+- `ArticleSocialShare` component: social sharing buttons for LinkedIn, Facebook, Twitter, Reddit, WhatsApp, Telegram, Email, and Copy Link. Optional `shareMessage` prop renders a footer paragraph below the buttons. Exported from the main package entry point.
+- `ArticleNavigation` component: previous/next article navigation links. Accepts `previous`, `next` (each `{ slug, title } | null`), and `basePath` props. Returns `null` when both are absent. Titles longer than 60 characters are truncated. Exported from the main package entry point.
+
+### Changed
+
+- `ArticleDetailHero` now accepts an optional `showDate?: boolean` prop (default `false`). The article date is hidden by default; pass `showDate={true}` to render it.
+
+## [0.3.0] - 2026-05-14
+
+### Added
+
+- `ArticleDetailHero` component: displays the article's featured image behind the title, categories, and metadata in the article detail page hero. Exported from the main package entry point. Accepts `article` and optional `categoryBasePath` props.
+
+### Changed
+
+- ArticleDetailHero now displays at most 4 category tags in the article hero. Articles with more than 4 categories show only the first 4.
+
+### Dependencies
+
+- `lucide-react` upgraded from `^0.454.0` to `^1.16.0`
+- `rehype-highlight` upgraded from `^7.0.1` to `^7.0.2`
+- `rehype-prism-plus` upgraded from `^2.0.0` to `^2.0.2`
+- `remark-gfm` upgraded from `^4.0.0` to `^4.0.1`
+- `unist-util-visit` upgraded from `^5.0.0` to `^5.1.0`
+
+## [0.2.2] - 2026-05-14
+
+### Changed
+
+- Category grid now uses the same responsive layout as Latest Articles: 1 column on mobile, 2 columns at md, 3 columns at lg. Removed conflicting inline `gridTemplateColumns` style that was overriding Tailwind responsive classes.
+
+## [0.2.1] - 2026-05-14
+
+### Added
+
+- `keywords` field added to `package.json` for npm discoverability
+- Blog link to [fullstackdatasolutions.com](https://fullstackdatasolutions.com) added to README
+
+### Fixed
+
+- Category grid now renders single column on mobile (was 2 columns). Changed `grid-cols-2` to `grid-cols-1`; desktop 4-column layout is unchanged.
+- Category images now render correctly on all consuming apps regardless of whether `@source` is configured in the app's Tailwind CSS. The image container's `position: relative` and `height` are now set via inline styles instead of Tailwind classes (`relative h-52`), which were only generated when the consuming app scanned the package source.
+
+No migration needed - both fixes are internal and backwards-compatible.
+
+## [0.2.0] - 2026-05-13
+
+### Added
+
+- `HeroConfig` interface with optional `title` and `description` fields
+- `hero` field on `ArticlesConfig` (type `HeroConfig`, fully optional)
+- `ArticlesHero` now accepts `title` and `description` props; built-in strings remain as defaults
+
+### Changed
+
+- `renderSection` internal function signature extended with a `config` parameter to forward hero config
+- `frontend/config/articles.ts` (reference app) now explicitly sets `hero.title` and `hero.description` matching the previous hardcoded values
+
+### Migration
+
+No breaking changes. Existing `ArticlesConfig` objects without a `hero` field continue to render the original "Vox Populus Insights" heading and description unchanged.
+
+To customize the hero for your app, add:
+
+```ts
+hero: {
+  title: 'Your App Title',
+  description: 'Your custom description.',
+}
+```
+
+## [0.1.0] - initial release
+
+- Initial public release with articles listing, article detail, category pages, comments system, SEO utilities, and theming support.

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'
@@ -128,19 +157,24 @@ export default async function Page({ params }: ArticlePageProps) {
   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} />
       )}
@@ -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+)
@@ -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
@@ -340,27 +435,119 @@ 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. |
-| `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.                                        |
+| 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.                 |
+| `mdxComponents`        | `Record<string, ComponentType<never>>`              | -                    | Components exposed to article `.mdx` bodies by tag name. Merged with the built-in MDX image override.                                               |
+| `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 />`.
 
+### Custom MDX components
+
+Pass React components through `mdxComponents` to make them available to article `.mdx` files. The component key is the JSX tag authors write in the article.
+
+```tsx
+// config/articles.ts
+import type { ArticlesConfig } from '@fullstackdatasolutions/articles'
+import { LeadMagnetCTA } from '@/components/LeadMagnetCTA'
+
+export const siteConfig: ArticlesConfig = {
+  siteUrl: 'https://yoursite.com',
+  siteName: 'Your Site',
+  mdxComponents: {
+    LeadMagnetCTA,
+  },
+}
+```
+
+```mdx
+Article intro paragraph.
+
+<LeadMagnetCTA system="DND" segment="new-players" />
+```
+
+Imports inside individual `.mdx` article files are not supported. Define components in the consuming app and register them through `mdxComponents`.
+
+### 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
@@ -739,7 +926,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.
 
 ---
 
@@ -749,7 +936,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.                                                                                                                                                                                                                              |
@@ -776,6 +964,7 @@ import {
   ArticleTOC,
   getAllArticles,
   getArticleMetadata,
+  getArticleAuthors,
   getArticleMarkdown,
   getArticleMarkdownResponse,
   getArticleMarkdownUrl,
@@ -783,6 +972,9 @@ import {
   getAiRobotsTxtRules,
   setArticlesErrorHandler,
   getArticlesByCategory,
+  getAuthorBySlug,
+  getAllAuthors,
+  getArticlesByAuthor,
   getAllCategories,
   getAvailableArticleSlugs,
   getAdjacentArticles,
@@ -793,11 +985,16 @@ import {
   extractToc,
   generateArticleStaticParams,
   generateCategoryStaticParams,
+  generateAuthorStaticParams,
   getArticleSitemapEntries,
   generateRssFeed,
   generateArticlesIndexMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
+  generateAuthorMetadata,
+  buildArticleBreadcrumbs,
+  buildCategoryBreadcrumbs,
+  buildAuthorBreadcrumbs,
 } from '@fullstackdatasolutions/articles/server'
 ```