@fullstackdatasolutions/articles 0.4.3 → 0.5.1

package/README.md

@@ -72,23 +72,76 @@ export default function Page() {
 }
 
 // app/articles/[slug]/page.tsx
-import { ArticlePage, generateArticleStaticParams, generateArticleMetadata } from '@fullstackdatasolutions/articles/server'
+import { notFound } from 'next/navigation'
+import {
+  ArticleDetailHero,
+  ArticleNavigation,
+  ArticleSEO,
+  ArticleSocialShare,
+  BreadcrumbSchema,
+  CommentsSection,
+  ScrollToTop,
+} from '@fullstackdatasolutions/articles'
+import {
+  ArticleContent,
+  ArticleTOC,
+  generateArticleMetadata,
+  getAdjacentArticles,
+  getArticleMetadata,
+} from '@fullstackdatasolutions/articles/server'
 import { siteConfig } from '@/config/articles'
-export const generateStaticParams = () => generateArticleStaticParams()
-export const generateMetadata = ({ params }: { params: { slug: string } }) =>
-  generateArticleMetadata(params.slug, siteConfig)
-export default function Page({ params }: { params: { slug: string } }) {
-  return <ArticlePage slug={params.slug} config={siteConfig} />
+export { generateArticleStaticParams as generateStaticParams } from '@fullstackdatasolutions/articles/server'
+type ArticlePageProps = Readonly<{ params: Promise<{ slug: string }> }>
+export async function generateMetadata({ params }: ArticlePageProps) {
+  const { slug } = await params
+  return generateArticleMetadata(slug, siteConfig)
+}
+export default async function Page({ params }: ArticlePageProps) {
+  const { slug } = await params
+  const article = await getArticleMetadata(slug)
+  if (!article) notFound()
+  const { previous, next } = await getAdjacentArticles(slug)
+  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 },
+        ]}
+      />
+      <ArticleDetailHero article={article} categoryBasePath="/articles/category" />
+      {siteConfig.showToc !== false && article.toc && article.toc.length > 0 && (
+        <ArticleTOC toc={article.toc} />
+      )}
+      <ArticleContent article={article} />
+      <ArticleSocialShare title={article.title} url={articleUrl} excerpt={article.excerpt} />
+      {siteConfig.comments && <CommentsSection articleSlug={slug} config={siteConfig.comments} />}
+      <ArticleNavigation previous={previous} next={next} basePath="/articles" />
+      <ScrollToTop />
+    </>
+  )
 }
 
 // app/articles/category/[category]/page.tsx
-import { CategoryArticlesPage, generateCategoryStaticParams, generateCategoryMetadata } from '@fullstackdatasolutions/articles/server'
+import { notFound } from 'next/navigation'
+import { CategoryArticlesPage } from '@fullstackdatasolutions/articles'
+import { generateCategoryMetadata, getArticlesByCategory } from '@fullstackdatasolutions/articles/server'
 import { siteConfig } from '@/config/articles'
-export const generateStaticParams = () => generateCategoryStaticParams()
-export const generateMetadata = ({ params }: { params: { category: string } }) =>
-  generateCategoryMetadata(params.category, siteConfig)
-export default function Page({ params }: { params: { category: string } }) {
-  return <CategoryArticlesPage category={params.category} config={siteConfig} />
+export { generateCategoryStaticParams as generateStaticParams } from '@fullstackdatasolutions/articles/server'
+type CategoryPageProps = Readonly<{ params: Promise<{ category: string }> }>
+export async function generateMetadata({ params }: CategoryPageProps) {
+  const { category } = await params
+  return generateCategoryMetadata(category, siteConfig)
+}
+export default async function Page({ params }: CategoryPageProps) {
+  const { category } = await params
+  const articles = await getArticlesByCategory(category)
+  if (articles.length === 0) notFound()
+  return <CategoryArticlesPage category={category} articles={articles} config={siteConfig} />
 }
 ```
 
@@ -98,6 +151,7 @@ These cannot live inside the package — Next.js file-based routing requires the
 
 ```
 app/api/articles/route.ts
+app/api/articles/comments-store.ts
 app/api/articles/[slug]/comments/route.ts
 app/api/articles/[slug]/comments/[commentId]/route.ts
 ```
@@ -134,6 +188,8 @@ Article body in Markdown...
 | `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. |
+| `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']`
 
@@ -248,6 +304,44 @@ const { previous, next } = await getAdjacentArticles(slug)
 
 ---
 
+## ArticleTOC
+
+`ArticleTOC` renders the article's table of contents as an inline nav block above article content. Server component (no `'use client'`). Returns `null` when the `toc` array is empty, so it is safe to render unconditionally.
+
+```tsx
+import { ArticleTOC } from '@fullstackdatasolutions/articles/server'
+
+<ArticleTOC toc={article.toc} />
+```
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `toc` | `TocItem[]` | yes | Array of table of contents items from the article |
+| `className` | `string` | no | Optional CSS class to add to the nav wrapper |
+
+- Indentation: h2=0rem, h3=1rem, h4=2rem (based on `item.depth - 2`)
+- Returns `null` when `toc` is empty
+- Gate used in article detail pages: `siteConfig.showToc !== false && article.toc && article.toc.length > 0`
+
+---
+
+## ScrollToTop
+
+`ScrollToTop` is a fixed-position floating button in the bottom-right corner that appears when the user scrolls past 300px, and smooth-scrolls back to the top on click. Client component (`'use client'`). No props required - fully self-contained, safe to place anywhere in your layout.
+
+```tsx
+import { ScrollToTop } from '@fullstackdatasolutions/articles'
+
+<ScrollToTop />
+```
+
+- No props
+- Appears only after 300px of vertical scroll
+- Smooth scroll animation
+- Fixed position, bottom-right corner
+
+---
+
 ## Comments setup
 
 ### 1. Enable in config
@@ -274,7 +368,8 @@ app/api/articles/[slug]/comments/[commentId]/route.ts  ← DELETE (soft)
 ### 3. Requirements
 
 - **NextAuth** session — users must be signed in to post. Unauthenticated visitors see a sign-in prompt.
-- **PostgreSQL** — comments are stored via Prisma. Run the migration from the reference app's `backend/` directory.
+- **File storage** — the reference implementation stores comments in `public/articles/{slug}/comments.json` via `app/api/articles/comments-store.ts`. Make sure the app can write to that path in the environment where comments are enabled.
+- The reference API supports one reply level only: top-level comments can have replies, but replies cannot have nested replies.
 
 ---
 
@@ -289,8 +384,9 @@ import { generateArticlesIndexMetadata } from '@fullstackdatasolutions/articles/
 import { siteConfig } from '@/config/articles'
 export const metadata: Metadata = generateArticlesIndexMetadata(siteConfig)
 // Produces: title, description, full OpenGraph (type: 'website'), Twitter Card,
-// canonical URL (/articles), and robots directives.
+// canonical URL (/articles), robots directives, and RSS feed alternate link.
 // Description falls back to config.hero?.description when set.
+// Automatically emits <link rel="alternate" type="application/rss+xml"> pointing to /articles/feed.xml
 ```
 
 ### Article and category metadata
@@ -308,6 +404,75 @@ export const generateMetadata = ({ params }) =>
   generateCategoryMetadata(params.category, siteConfig)
 ```
 
+### RSS feed
+
+To enable RSS 2.0 feed generation at `/articles/feed.xml`, copy this route file into your consuming app:
+
+```ts
+// app/articles/feed.xml/route.ts
+import { 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 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>` : '',
+        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>`
+
+  return new Response(xml, {
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',
+      'Cache-Control': 'public, max-age=3600',
+    },
+  })
+}
+```
+
+- Uses `force-static` for build-time generation
+- 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`
+
 ### Sitemaps
 
 Use `getArticleSitemapEntries` to generate article and category sitemap entries. Pass your `ArticlesConfig` object (preferred) or a plain URL string.
@@ -339,12 +504,21 @@ JSON-LD structured data (`ArticleSchema`, `BreadcrumbSchema`, `CollectionPageSch
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `title` | `string` | yes | Article title |
-| `excerpt` | `string` | yes | One-sentence summary for cards and meta |
+| `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'` |
 | `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. |
-| `featuredImage` | `string` | no | Filename relative to the article directory. Auto-detected if omitted. |
+| `lastmod` | `YYYY-MM-DD` | no | Last modified date used by sitemap metadata when available. |
+| `featuredImage` | `string` | no | Filename or nested path relative to the article directory, or an absolute `http(s)` URL. Auto-detected from the first image in the article directory if omitted. Falls back to `/placeholder-logo.png`. Relative paths are sanitized and resolved to `/articles/{slug}/{featuredImage}`. |
+| `draft` | `boolean` | no | Set to `true` to hide the article in production. Drafts remain visible outside production. |
+| `faq` | `{ question: string; answer: string }[]` | no | FAQ items used by the article structured data. Invalid entries are ignored. |
+| `howTo` | `{ name: string; text: string }[]` | no | How-to steps used by the article structured data. Invalid entries are ignored. |
+| `canonicalUrl` | `string` | no | Canonical URL override for article metadata. |
+| `articleType` | `string` | no | Optional article type value included in article metadata/structured data. |
+| `series` | `string` | no | Optional series label for grouping related articles. |
+
+Articles can be authored as either `article.md` or `article.mdx` inside `public/articles/{slug}/`. Markdown files are converted to HTML; MDX files are returned as `mdxSource` for the consuming app to render. Reading time and the table of contents are generated from the article body automatically.
 
 ---
 
@@ -354,6 +528,8 @@ Import from `@fullstackdatasolutions/articles/server` — these use `fs`/`path`
 
 ```ts
 import {
+  ArticleContent,
+  ArticleTOC,
   getAllArticles,
   getArticleMetadata,
   getArticlesByCategory,
@@ -362,6 +538,11 @@ import {
   getAdjacentArticles,
   searchArticles,
   categoryToSlug,
+  sanitizeImagePath,
+  markdownToHtml,
+  extractToc,
+  generateArticleStaticParams,
+  generateCategoryStaticParams,
   getArticleSitemapEntries,
   generateArticlesIndexMetadata,
   generateArticleMetadata,
@@ -408,9 +589,11 @@ Paste this block into your app's `AGENTS.md` so AI assistants know how the libra
 This app uses `@fullstackdatasolutions/articles` for the articles section.
 
 ### Key files
-- `config/articles.ts` — all library behaviour (layout, theme, page size, comments) is controlled here
+- `config/articles.ts` — all library behaviour (layout, theme, page size, comments, TOC, RSS) is controlled here
 - `app/api/articles/` — thin API route wrappers; do not add business logic here
-- `public/articles/[slug]/article.md` — one directory per article
+- `app/api/articles/comments-store.ts` — reference file-backed comment persistence helper used by the comment API routes
+- `app/articles/feed.xml/route.ts` — RSS 2.0 feed (copy from reference implementation)
+- `public/articles/[slug]/article.md` or `article.mdx` — one directory per article
 
 ### CSS (Tailwind v4)
 The package ships its source TypeScript files so Tailwind can scan them.
@@ -418,6 +601,10 @@ The package ships its source TypeScript files so Tailwind can scan them.
   @source "./node_modules/@fullstackdatasolutions/articles/src";
 If this line is missing, most component classes will not render correctly. Note: `ArticleCategoryGrid` images, `CategoryArticlesPage` hero, and `ArticleDetailHero` image use inline styles for critical layout so they render correctly without this line. All other styling still requires it.
 
+### Components
+- `ArticleTOC` — server component imported from `@fullstackdatasolutions/articles/server`; renders `article.toc[]` as a nav block. Controlled by `siteConfig.showToc` (defaults `true`). Returns `null` when empty.
+- `ScrollToTop` — client component, no props. Fixed-position button appears after 300px scroll.
+
 ### Server utilities
 For sitemaps and metadata: `import { getArticleSitemapEntries, generateArticlesIndexMetadata, generateArticleMetadata, generateCategoryMetadata } from '@fullstackdatasolutions/articles/server'`. See README for usage examples.
 
@@ -426,6 +613,8 @@ For sitemaps and metadata: `import { getArticleSitemapEntries, generateArticlesI
 - When adding a new article: create `public/articles/[slug]/article.md` with title, excerpt, author, tags.
 - API routes are copied from the library — update the package version and re-copy if the library API changes.
 - `hero.title` and `hero.description` in `ArticlesConfig` control the hero heading — pass them to customize per app.
+- `showToc?: boolean` (default `true`) controls TOC visibility on all article detail pages.
+- `description?: string` sets the RSS feed channel description (falls back to `siteName`).
 - Full library docs: `node_modules/@fullstackdatasolutions/articles/README.md`
 ```