@fullstackdatasolutions/articles 0.8.1 → 0.9.0

package/README.md

@@ -125,7 +125,7 @@ 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 siteUrl = siteConfig.siteUrl.replace(/\/$/, '')
@@ -144,7 +144,7 @@ export default async function Page({ params }: ArticlePageProps) {
       {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" />
@@ -175,7 +175,57 @@ export default async function Page({ params }: CategoryPageProps) {
 }
 ```
 
-### 6. Copy the API routes
+### 6. Set up markdown handler (Next.js 16+)
+
+Create an API route to serve article markdown at `/api/articles-markdown/[...slug]`:
+
+```tsx
+// app/api/articles-markdown/[...slug]/route.ts
+import { createArticleMarkdownHandler } from '@fullstackdatasolutions/articles/nextjs'
+import { siteConfig } from '@/config/articles'
+
+export const { GET } = createArticleMarkdownHandler(siteConfig)
+```
+
+Then wire the markdown rewrite into your proxy.ts (Next.js 16+ edge proxy):
+
+```ts
+// proxy.ts
+import { NextResponse, NextRequest } from 'next/server'
+import { rewriteArticleMarkdown } from '@fullstackdatasolutions/articles/middleware'
+
+export async function proxy(request: NextRequest) {
+  const mdRewrite = rewriteArticleMarkdown(request)
+  if (mdRewrite) return mdRewrite
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+}
+```
+
+This pattern rewrites requests from `/articles/slug.md` to `/api/articles-markdown/slug` where the handler serves the markdown. See the AI markdown twins section below for details on how to expose markdown and configure AI crawling rules.
+
+For **Next.js 14/15**, use the middleware.ts pattern below instead.
+
+### 6b. Set up middleware (Next.js 14/15 only)
+
+If using Next.js 14 or 15 and cannot use a proxy, create middleware.ts to rewrite markdown requests:
+
+```ts
+// middleware.ts
+import { NextRequest } from 'next/server'
+import { middleware, config } from '@fullstackdatasolutions/articles/middleware'
+
+export { config }
+export default middleware
+```
+
+This pattern does NOT work in Next.js 16 (use the proxy.ts pattern instead). You still need the handler route above to actually serve the markdown.
+
+### 6c. Copy the comments API routes
 
 These cannot live inside the package — Next.js file-based routing requires them in your app. Copy these files from the reference implementation:
 
@@ -207,23 +257,105 @@ Article directories can be nested to any depth below `public/articles`. For exam
 
 ---
 
+## Markdown handler exports
+
+### `./nextjs` — Article markdown handler factory
+
+Import from `@fullstackdatasolutions/articles/nextjs`. Node.js runtime only (use in API routes, not Edge middleware).
+
+#### `createArticleMarkdownHandler(config)`
+
+Factory function that returns a `{ GET }` handler for serving article markdown.
+
+```ts
+import { createArticleMarkdownHandler } from '@fullstackdatasolutions/articles/nextjs'
+import { siteConfig } from '@/config/articles'
+
+export const { GET } = createArticleMarkdownHandler(siteConfig)
+```
+
+- **config** - `ArticlesConfig` instance (required). Must include `siteUrl` and `siteName` at minimum.
+- **returns** - Object with `GET` async function matching Next.js Route Handler signature.
+- The handler extracts slug from `params['slug']` and strips `.md` extension if present.
+- Uses `getArticleMarkdownResponse` from the server utilities to fetch and return markdown.
+- Only returns markdown for articles with `aiCrawl: true` in frontmatter (returns 404 otherwise).
+
+### `./middleware` — Article markdown rewrite helpers
+
+Import from `@fullstackdatasolutions/articles/middleware`. Edge runtime safe (no Node.js built-ins).
+
+#### `rewriteArticleMarkdown(request, apiBase?)`
+
+Rewrites `/articles/*.md` requests to your markdown handler route.
+
+```ts
+import { rewriteArticleMarkdown } from '@fullstackdatasolutions/articles/middleware'
+
+export async function proxy(request: NextRequest) {
+  const mdRewrite = rewriteArticleMarkdown(request)
+  if (mdRewrite) return mdRewrite
+
+  return NextResponse.next()
+}
+```
+
+- **request** - `NextRequest` object (required).
+- **apiBase** - Base path to your markdown handler. Default: `'/api/articles-markdown'`
+- **returns** - `NextResponse` if request matches `/articles/...md`, `undefined` otherwise.
+- Intended use: call in proxy.ts (Next.js 16+) or middleware.ts. If result is truthy, return it; otherwise continue processing.
+- Example: request to `/articles/my-post.md` rewrites to `/api/articles-markdown/my-post`.
+
+#### `createArticleMarkdownMiddleware(apiBase?)`
+
+Factory for building custom middleware/proxy with a custom API base path.
+
+```ts
+import { createArticleMarkdownMiddleware } from '@fullstackdatasolutions/articles/middleware'
+
+const { middleware, config } = createArticleMarkdownMiddleware('/api/my-custom-path')
+
+export { config }
+export default middleware
+```
+
+- **apiBase** - Base path to your markdown handler. Default: `'/api/articles-markdown'`
+- **returns** - Object with `{ middleware, config }` ready to export from middleware.ts.
+- `config.matcher` automatically targets `/articles/:path*.md`.
+
+#### `middleware` (default export)
+
+Pre-built middleware using the default API base (`'/api/articles-markdown'`).
+
+```ts
+// middleware.ts
+import { middleware, config } from '@fullstackdatasolutions/articles/middleware'
+
+export { config }
+export default middleware
+```
+
+Use this if you don't need a custom API base path. For custom paths, use `createArticleMarkdownMiddleware()` instead.
+
+---
+
 ## `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. |
+| `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']`
 
@@ -470,56 +602,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: {
@@ -531,6 +621,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`
 
@@ -548,24 +639,82 @@ aiCrawl: true
 Markdown body...
 ```
 
-Runtime route example for Next App Router:
+To expose markdown at public URLs like `/articles/my-post.md`, use the markdown handler factories above:
+
+- **Next.js 16+** — Use `createArticleMarkdownHandler()` + `rewriteArticleMarkdown()` in proxy.ts (see Step 6 above).
+- **Next.js 14/15** — Use `createArticleMarkdownHandler()` + middleware.ts with `middleware` export from the package (see Step 6b above).
+
+For static generation, call `getArticleMarkdown(slug)` during your build and write the returned content beside your generated HTML; it returns `null` unless `aiCrawl: true`.
+
+**robots.txt - block AI crawlers from non-aiCrawl articles**
+
+Wire `getAiRobotsTxtRules()` into your robots.txt route. It returns disallow rules for known AI crawler agents (GPTBot, Claude-Web, etc.) targeting any article that does not have `aiCrawl: true`. Without this step, AI crawlers can still reach all articles regardless of the frontmatter flag.
 
 ```ts
-// app/articles-md/[...slug]/route.ts
-import { getArticleMarkdownResponse } from '@fullstackdatasolutions/articles/server'
-import { siteConfig } from '@/config/articles'
+// app/robots.txt/route.ts
+import { NextResponse } from 'next/server'
+import { getAiRobotsTxtRules } from '@fullstackdatasolutions/articles/server'
 
-type RouteProps = Readonly<{ params: Promise<{ slug: string[] }> }>
+export async function GET() {
+  const siteUrl = 'https://yoursite.com'
+  const aiRules = await getAiRobotsTxtRules()
 
-export async function GET(_request: Request, { params }: RouteProps) {
-  const { slug } = await params
-  return getArticleMarkdownResponse(slug.join('/'), siteConfig)
+  const robotsTxt = `User-agent: *
+Allow: /
+
+Sitemap: ${siteUrl}/sitemap.xml${aiRules ? `\n\n${aiRules}` : ''}`
+
+  return new NextResponse(robotsTxt, {
+    headers: {
+      'Content-Type': 'text/plain',
+      'Cache-Control': 'public, max-age=3600, s-maxage=3600',
+    },
+  })
+}
+```
+
+`getAiRobotsTxtRules()` returns a string of `User-agent` / `Disallow` blocks, one per known AI crawler, or `null` if every article is opted in. The template literal appends it only when non-null so no blank lines appear when it is unused.
+
+**article page metadata - emit alternate link and noai directive**
+
+`generateArticleMetadata` handles the `text/markdown` alternate link automatically when `aiCrawl: true`. If you override `generateMetadata` and build the metadata object yourself, cast the return value as `Metadata` before spreading so TypeScript accepts it:
+
+```ts
+// app/articles/[...slug]/page.tsx
+import type { Metadata } from 'next'
+import {
+  generateArticleMetadata,
+  getArticleMetadata,
+  getArticleMarkdownUrl,
+} from '@fullstackdatasolutions/articles/server'
+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, siteConfig)
+  if (!article) return base
+
+  const markdownUrl = getArticleMarkdownUrl(article, siteConfig)
+  if (markdownUrl) {
+    return {
+      ...base,
+      alternates: {
+        ...(base.alternates as Record<string, unknown>),
+        types: { 'text/markdown': markdownUrl },
+      },
+    }
+  }
+  return {
+    ...base,
+    robots: 'index, follow, noai, noimageai',
+  }
 }
 ```
 
-If you want public URLs like `/articles/my-post.md`, add a rewrite from `/articles/:path*.md` to `/articles-md/:path*` in the consuming app. For static generation, call `getArticleMarkdown(slug)` during your build and write the returned content beside your generated HTML; it returns `null` unless `aiCrawl: true`.
+Do **not** use `headers()` from `next/headers` to set response headers in a Server Component page - it is read-only in the App Router (reads request headers). Use `generateMetadata` instead.
 
-Use `getArticleAiHeaders(article, siteConfig)` in an HTML article route if you want response headers in addition to Next metadata. Opted-in articles receive a markdown `Link` header. Blocked/default articles receive `X-Robots-Tag: noai, noimageai`. `getAiRobotsTxtRules()` returns optional robots.txt blocks for known AI crawler user agents and articles that are not opted in.
+Use `getArticleAiHeaders(article, siteConfig)` only in a Route Handler (not a page), where you control the `Response` object directly. Opted-in articles receive a markdown `Link` header; all others receive `X-Robots-Tag: noai, noimageai`.
 
 ### Sitemaps
 
@@ -645,6 +794,7 @@ import {
   generateArticleStaticParams,
   generateCategoryStaticParams,
   getArticleSitemapEntries,
+  generateRssFeed,
   generateArticlesIndexMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
@@ -739,6 +889,7 @@ For sitemaps and metadata: `import { getArticleSitemapEntries, generateArticlesI
 - `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`).
+- `aiCrawl: true` in article frontmatter opts that article into AI indexing. Wire up three things: (1) `getAiRobotsTxtRules()` in `app/robots.txt/route.ts` appended to the robots.txt string; (2) a `app/articles/[slug].md/route.ts` Route Handler calling `getArticleMarkdownResponse`; (3) `generateMetadata` in the article page casting the base metadata as `Metadata` and spreading it before adding `alternates.types` or `robots`. Do NOT use `next/headers` `headers()` to set response headers in a page - it is read-only.
 - Full library docs: `node_modules/@fullstackdatasolutions/articles/README.md`
 ```
 
@@ -757,6 +908,16 @@ GitHub Actions runs typecheck → test → build → `npm publish --access publi
 
 ---
 
+## Examples
+
+See this package in use at:
+
+- [voxpopulus.us/articles](https://voxpopulus.us/articles/)
+- [loopvolt.io/articles](https://loopvolt.io/articles)
+- [theroleplayersguild.com/articles](https://theroleplayersguild.com/articles)
+
+---
+
 ## Upgrading
 
 Follow semver. Breaking changes (major) include a migration note in the changelog.