@fullstackdatasolutions/articles 0.8.1 → 0.9.0

package/src/markdown.ts

@@ -11,8 +11,67 @@ import remarkRehype from 'remark-rehype'
 import { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
 import type { TocItem } from './articleTypes'
+import type { ArticlesConfig, LinkTargetStrategy } from './articlesConfig'
 import { reportArticlesError } from './errorReporting'
 
+type LinkTargetOptions = Readonly<{
+  strategy?: LinkTargetStrategy
+  siteUrl?: string
+}>
+
+const DEFAULT_LINK_TARGET_STRATEGY: LinkTargetStrategy = 'external-new-tab'
+
+function isNonBrowserNavigationLink(href: string): boolean {
+  return (
+    /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href) &&
+    !href.startsWith('http://') &&
+    !href.startsWith('https://')
+  )
+}
+
+function getOrigin(url: string | undefined): string | null {
+  if (!url) return null
+  try {
+    return new URL(url).origin
+  } catch {
+    return null
+  }
+}
+
+function isExternalHttpLink(href: string, siteUrl?: string): boolean {
+  if (!href.startsWith('http://') && !href.startsWith('https://')) return false
+  const siteOrigin = getOrigin(siteUrl)
+  if (!siteOrigin) return true
+  return getOrigin(href) !== siteOrigin
+}
+
+function shouldOpenInNewTab(href: string, options: LinkTargetOptions = {}): boolean {
+  if (!href || href.startsWith('#') || isNonBrowserNavigationLink(href)) return false
+
+  const strategy = options.strategy ?? DEFAULT_LINK_TARGET_STRATEGY
+  if (strategy === 'same-tab') return false
+  if (strategy === 'all-new-tab') return true
+  return isExternalHttpLink(href, options.siteUrl)
+}
+
+function applyLinkTarget(props: Record<string, unknown>, options?: LinkTargetOptions): void {
+  const href = typeof props.href === 'string' ? props.href : ''
+  if (shouldOpenInNewTab(href, options)) {
+    props.target = '_blank'
+    props.rel = 'noopener noreferrer'
+    return
+  }
+  delete props.target
+  delete props.rel
+}
+
+function getLinkTargetOptions(config?: ArticlesConfig): LinkTargetOptions {
+  return {
+    strategy: config?.linkTargetStrategy,
+    siteUrl: config?.siteUrl,
+  }
+}
+
 // Import the sanitizeImagePath function
 function sanitizeImagePath(rawPath: string, articleSlug: string): string | null {
   if (!rawPath || typeof rawPath !== 'string') {
@@ -169,7 +228,7 @@ function processFootnotesSection(node: Element): void {
   if (node.properties) node.properties.className = undefined
 }
 
-export const customRenderer: Plugin<[], Root> = () => {
+export const customRenderer: Plugin<[LinkTargetOptions?], Root> = (linkTargetOptions = {}) => {
   return (tree: Root) => {
     // First pass: Apply general styles
     visit(tree, 'element', (node: Element) => {
@@ -194,11 +253,7 @@ export const customRenderer: Plugin<[], Root> = () => {
             break
           case 'a': {
             props.className = 'text-primary hover:underline transition-colors duration-200'
-            const href = typeof props.href === 'string' ? props.href : ''
-            if (!href.startsWith('#')) {
-              props.target = '_blank'
-              props.rel = 'noopener noreferrer'
-            }
+            applyLinkTarget(props, linkTargetOptions)
             break
           }
           case 'ul':
@@ -278,7 +333,11 @@ const rehypeProcessImages: Plugin<[{ articleSlug?: string }], Root> = (options =
   }
 }
 
-export async function markdownToHtml(markdown: string, articleSlug?: string) {
+export async function markdownToHtml(
+  markdown: string,
+  articleSlug?: string,
+  config?: ArticlesConfig
+) {
   try {
     // Start building the remark processor
     let processor = remark()
@@ -286,7 +345,7 @@ export async function markdownToHtml(markdown: string, articleSlug?: string) {
       .use(remarkGfm)
       .use(remarkGithubBlockquoteAlert)
       .use(remarkRehype)
-      .use(customRenderer)
+      .use(customRenderer, getLinkTargetOptions(config))
       .use(rehypeSlug)
       // @ts-ignore
       .use(rehypePrism)

package/src/nextjs-middleware.ts

@@ -0,0 +1,48 @@
+// Next.js proxy/middleware helper — Edge runtime safe (no Node.js built-ins)
+// Import from '@fullstackdatasolutions/articles/middleware'
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+const DEFAULT_API_BASE = '/api/articles-markdown'
+
+/**
+ * Rewrite /articles/*.md requests to the markdown API route.
+ * Returns a NextResponse rewrite if the request matches, undefined otherwise.
+ *
+ * Usage in proxy.ts (Next.js 16+):
+ *   import { rewriteArticleMarkdown } from '@fullstackdatasolutions/articles/middleware'
+ *   export async function proxy(request: NextRequest) {
+ *     return rewriteArticleMarkdown(request) ?? NextResponse.next()
+ *   }
+ */
+export function rewriteArticleMarkdown(
+  request: NextRequest,
+  apiBase = DEFAULT_API_BASE
+): NextResponse | undefined {
+  const { pathname } = request.nextUrl
+  if (pathname.startsWith('/articles/') && pathname.endsWith('.md')) {
+    const slug = pathname.slice('/articles/'.length)
+    return NextResponse.rewrite(new URL(`${apiBase}/${slug}`, request.url))
+  }
+  return undefined
+}
+
+// Legacy middleware.ts usage (Next.js 14/15)
+function buildMiddleware(apiBase: string) {
+  return function middleware(request: NextRequest) {
+    return rewriteArticleMarkdown(request, apiBase)
+  }
+}
+
+export const middleware = buildMiddleware(DEFAULT_API_BASE)
+
+export const config = {
+  matcher: '/articles/:path*.md',
+}
+
+export function createArticleMarkdownMiddleware(apiBase = DEFAULT_API_BASE) {
+  return {
+    middleware: buildMiddleware(apiBase),
+    config: { matcher: '/articles/:path*.md' },
+  }
+}

package/src/nextjs.ts

@@ -0,0 +1,27 @@
+// Next.js API route handler factory — Node.js runtime only
+// Import from '@fullstackdatasolutions/articles/nextjs'
+import type { NextRequest } from 'next/server'
+import { getArticleMarkdownResponse } from './server-articles'
+import type { ArticlesConfig } from './articlesConfig'
+
+/**
+ * Returns a Next.js App Router GET handler for serving article markdown.
+ *
+ * Usage in app/api/articles-markdown/[...slug]/route.ts:
+ *   import { createArticleMarkdownHandler } from '@fullstackdatasolutions/articles/nextjs'
+ *   import { siteConfig } from '@/config/articles'
+ *   export const { GET } = createArticleMarkdownHandler(siteConfig)
+ */
+export function createArticleMarkdownHandler(config: ArticlesConfig) {
+  async function GET(
+    _request: NextRequest,
+    context: { params: Promise<Record<string, string | string[]>> }
+  ) {
+    const params = await context.params
+    const slugParts = params['slug']
+    const slug = Array.isArray(slugParts) ? slugParts.join('/') : (slugParts ?? '')
+    const cleanSlug = slug.endsWith('.md') ? slug.slice(0, -3) : slug
+    return getArticleMarkdownResponse(cleanSlug, config)
+  }
+  return { GET }
+}

package/src/renderMdx.tsx

@@ -13,6 +13,7 @@ import rehypeSlug from 'rehype-slug'
 import remarkGfm from 'remark-gfm'
 import remarkGithubBlockquoteAlert from 'remark-github-blockquote-alert'
 import { customRenderer } from './markdown'
+import type { ArticlesConfig } from './articlesConfig'
 
 type MdxContent = ComponentType<{
   components?: Record<string, ComponentType<unknown>>
@@ -26,7 +27,7 @@ function makeImgComponent(basePath: string) {
   }
 }
 
-export async function renderMdxSource(source: string, basePath?: string) {
+export async function renderMdxSource(source: string, basePath?: string, config?: ArticlesConfig) {
   const isDevelopment = process.env.NODE_ENV === 'development'
 
   const mdxModule = await evaluate(source, {
@@ -34,7 +35,7 @@ export async function renderMdxSource(source: string, basePath?: string) {
     development: isDevelopment,
     remarkPlugins: [remarkGfm, remarkGithubBlockquoteAlert],
     rehypePlugins: [
-      customRenderer,
+      [customRenderer, { strategy: config?.linkTargetStrategy, siteUrl: config?.siteUrl }],
       rehypeSlug,
       // @ts-ignore
       rehypePrism,

package/src/seoUtils.ts

@@ -8,6 +8,60 @@ import {
   getAvailableArticleSlugs,
 } from './server-articles'
 import { ArticlesConfig } from './articlesConfig'
+import type { Article } from './articleTypes'
+
+function escapeXml(str: string): string {
+  return str
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+}
+
+export function generateRssFeed(articles: Article[], config: ArticlesConfig): string {
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const showAuthor = config.showAuthor !== false
+
+  const items = articles
+    .map((article) => {
+      const url = `${siteUrl}/articles/${article.slug}`
+      const pubDate = article.date ? new Date(article.date).toUTCString() : ''
+      const imageUrl = article.featuredImage ? resolveImageUrl(article.featuredImage, siteUrl) : ''
+
+      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>` : '',
+        article.category ? `      <category><![CDATA[${article.category}]]></category>` : '',
+        imageUrl
+          ? `      <media:content url="${imageUrl}" medium="image" width="1200" height="630"/>`
+          : '',
+        '    </item>',
+      ]
+        .filter(Boolean)
+        .join('\n')
+    })
+    .join('\n')
+
+  const description = config.description ?? `${config.siteName} articles`
+
+  return `<?xml version="1.0" encoding="UTF-8" ?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">
+  <channel>
+    <title><![CDATA[${config.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>`
+}
 
 export function generateArticleStaticParams(): { slug: string }[] {
   return getAvailableArticleSlugs().map((slug) => ({ slug }))

package/src/server-articles.ts

@@ -197,33 +197,35 @@ async function getArticleSummary(slug: string): Promise<Article | null> {
   }
 }
 
-export const getArticleMetadata = cache(async (slug: string): Promise<Article | null> => {
-  try {
-    const summary = await getArticleSummary(slug)
-    if (!summary) return null
-    const found = findArticleFile(slug)
-    if (!found) return null
-    const fileContent = fs.readFileSync(found.filePath, 'utf8')
-    const { content: markdownContent } = matter(fileContent)
-    const toc = await extractToc(markdownContent)
-    let htmlContent: string | undefined
-    let mdxSource: string | undefined
-    if (found.contentType === 'mdx') {
-      mdxSource = markdownContent
-    } else {
-      htmlContent = await markdownToHtml(markdownContent, slug)
+export const getArticleMetadata = cache(
+  async (slug: string, config?: ArticlesConfig): Promise<Article | null> => {
+    try {
+      const summary = await getArticleSummary(slug)
+      if (!summary) return null
+      const found = findArticleFile(slug)
+      if (!found) return null
+      const fileContent = fs.readFileSync(found.filePath, 'utf8')
+      const { content: markdownContent } = matter(fileContent)
+      const toc = await extractToc(markdownContent)
+      let htmlContent: string | undefined
+      let mdxSource: string | undefined
+      if (found.contentType === 'mdx') {
+        mdxSource = markdownContent
+      } else {
+        htmlContent = await markdownToHtml(markdownContent, slug, config)
+      }
+      return { ...summary, content: markdownContent, htmlContent, mdxSource, toc }
+    } catch (error) {
+      reportArticlesError({
+        code: 'article-load-failed',
+        message: 'Unable to load article metadata.',
+        error,
+        context: { slug },
+      })
+      return null
     }
-    return { ...summary, content: markdownContent, htmlContent, mdxSource, toc }
-  } catch (error) {
-    reportArticlesError({
-      code: 'article-load-failed',
-      message: 'Unable to load article metadata.',
-      error,
-      context: { slug },
-    })
-    return null
   }
-})
+)
 
 export const getAllArticles = cache(async (): Promise<Article[]> => {
   const slugs = getAvailableArticleSlugs()

package/src/server.ts

@@ -17,6 +17,7 @@ export {
 } from './server-articles'
 
 export {
+  generateRssFeed,
   generateArticleStaticParams,
   generateCategoryStaticParams,
   generateArticlesIndexMetadata,
@@ -31,7 +32,7 @@ export { ArticleContent } from './ArticleContent'
 export { ArticleTOC } from './ArticleTOC'
 
 export type { Article, CategoryInfo, TocItem } from './articleTypes'
-export type { ArticlesConfig } from './articlesConfig'
+export type { ArticlesConfig, LinkTargetStrategy } from './articlesConfig'
 export type {
   ArticlesErrorCode,
   ArticlesErrorContext,