@fullstackdatasolutions/articles 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,237 @@
+# 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.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.