@fullstackdatasolutions/articles 0.8.2 → 0.10.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/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>>
@@ -21,12 +22,14 @@ type MdxContent = ComponentType<{
 function makeImgComponent(basePath: string) {
   return function MdxImage({ src, alt, ...props }: ImgHTMLAttributes<HTMLImageElement>) {
     const resolvedSrc =
-      src && !src.startsWith('http') && !src.startsWith('/') ? `${basePath}/${src}` : src
+      typeof src === 'string' && !src.startsWith('http') && !src.startsWith('/')
+        ? `${basePath}/${src}`
+        : src
     return React.createElement('img', { src: resolvedSrc, alt, ...props })
   }
 }
 
-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 +37,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

@@ -2,12 +2,78 @@ import type { Metadata, MetadataRoute } from 'next'
 import {
   getArticleMetadata,
   getAllArticles,
+  getAllAuthors,
   getAllCategories,
+  getArticleAuthors,
   getArticlesByCategory,
+  getAuthorBySlug,
   getArticleMarkdownUrl,
   getAvailableArticleSlugs,
+  categoryToSlug,
 } from './server-articles'
-import { ArticlesConfig } from './articlesConfig'
+import {
+  breadcrumbsAreEnabled,
+  getBreadcrumbsConfig,
+  type ArticlesConfig,
+  type ArticleBreadcrumbEntry,
+  type AuthorBreadcrumbEntry,
+  type CategoryBreadcrumbEntry,
+  type CustomBreadcrumbItem,
+} from './articlesConfig'
+import type { Article, AuthorProfile, BreadcrumbItem } 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 }))
@@ -18,6 +84,11 @@ export async function generateCategoryStaticParams(): Promise<{ category: string
   return categories.map((cat) => ({ category: cat.slug }))
 }
 
+export function generateAuthorStaticParams(config: ArticlesConfig): { author: string }[] {
+  if (config.showAuthorPage === false) return []
+  return getAllAuthors(config).map((author) => ({ author: author.slug }))
+}
+
 function resolveImageUrl(featuredImage: string, siteUrl: string): string {
   const base = siteUrl.replace(/\/$/, '')
   if (featuredImage.startsWith('http://') || featuredImage.startsWith('https://')) {
@@ -30,7 +101,7 @@ export async function generateArticleMetadata(
   slug: string,
   config: ArticlesConfig
 ): Promise<Metadata> {
-  const article = await getArticleMetadata(slug)
+  const article = await getArticleMetadata(slug, config)
 
   if (!article) {
     return {
@@ -48,6 +119,7 @@ export async function generateArticleMetadata(
   const description = article.excerpt ?? `Read ${article.title} on ${config.siteName}.`
   const showAuthor = config.showAuthor !== false
   const markdownUrl = getArticleMarkdownUrl(article, config)
+  const authorNames = getArticleAuthors(article, config).map((author) => author.name)
 
   return {
     title: `${article.title} | ${config.siteName}`,
@@ -63,7 +135,7 @@ export async function generateArticleMetadata(
       type: 'article',
       ...(article.date && { publishedTime: article.date }),
       ...(article.lastmod && { modifiedTime: new Date(article.lastmod).toISOString() }),
-      ...(showAuthor && { authors: [article.author] }),
+      ...(showAuthor && authorNames.length > 0 && { authors: authorNames }),
       tags: article.tags ?? [],
     },
     twitter: {
@@ -92,7 +164,7 @@ export async function generateArticleMetadata(
       },
     },
     other: {
-      ...(showAuthor && { 'article:author': article.author }),
+      ...(showAuthor && authorNames.length > 0 && { 'article:author': authorNames.join(', ') }),
       ...(article.date && {
         'article:published_time': new Date(article.date).toISOString(),
       }),
@@ -198,6 +270,195 @@ export async function generateCategoryMetadata(
   }
 }
 
+export async function generateAuthorMetadata(
+  authorSlug: string,
+  config: ArticlesConfig
+): Promise<Metadata> {
+  const author = getAuthorBySlug(authorSlug, config)
+
+  if (!author || config.showAuthorPage === false) return { title: 'Author Not Found' }
+
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const authorUrl = author.url ?? `${siteUrl}/articles/authors/${author.slug}`
+  const title = `${author.name} Articles | ${config.siteName}`
+
+  return {
+    title,
+    description: author.bio,
+    openGraph: {
+      title,
+      description: author.bio,
+      url: authorUrl,
+      siteName: config.siteName,
+      type: 'profile',
+      locale: 'en_US',
+      ...(author.avatar && { images: [{ url: resolveAuthorAvatar(author, config) }] }),
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description: author.bio,
+      ...(author.avatar && { images: [resolveAuthorAvatar(author, config)] }),
+    },
+    alternates: {
+      canonical: authorUrl,
+    },
+    robots: {
+      index: true,
+      follow: true,
+    },
+  }
+}
+
+function formatCategoryName(category: string): string {
+  return category
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+export function buildArticleBreadcrumbs(
+  article: Pick<Article, 'slug' | 'title' | 'category'>,
+  config: ArticlesConfig
+): BreadcrumbItem[] {
+  if (!breadcrumbsAreEnabled(config)) return []
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const breadcrumbConfig = getBreadcrumbsConfig(config)
+  const labels = breadcrumbConfig.labels ?? {}
+  const categorySlug = categoryToSlug(article.category)
+  const trail = breadcrumbConfig.article ?? ['home', 'articles', 'primaryCategory', 'articleTitle']
+  const folderSegments = article.slug.split('/').filter(Boolean).slice(0, -1)
+  return trail.flatMap((token): BreadcrumbItem[] =>
+    buildArticleBreadcrumbToken(token, {
+      article,
+      siteUrl,
+      categorySlug,
+      folderSegments,
+      labels,
+    })
+  )
+}
+
+export function buildCategoryBreadcrumbs(
+  category: string,
+  config: ArticlesConfig,
+  categoryName = formatCategoryName(category)
+): BreadcrumbItem[] {
+  if (!breadcrumbsAreEnabled(config)) return []
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const breadcrumbConfig = getBreadcrumbsConfig(config)
+  const labels = breadcrumbConfig.labels ?? {}
+  const trail = breadcrumbConfig.category ?? ['home', 'articles', 'category']
+  return trail.flatMap((entry): BreadcrumbItem[] =>
+    buildCategoryBreadcrumbEntry(entry, { categoryName, siteUrl, labels })
+  )
+}
+
+export function buildAuthorBreadcrumbs(
+  author: AuthorProfile,
+  config: ArticlesConfig
+): BreadcrumbItem[] {
+  if (!breadcrumbsAreEnabled(config)) return []
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  const breadcrumbConfig = getBreadcrumbsConfig(config)
+  const labels = breadcrumbConfig.labels ?? {}
+  const trail = breadcrumbConfig.author ?? ['home', 'articles', 'authors', 'authorName']
+  return trail.flatMap((entry): BreadcrumbItem[] =>
+    buildAuthorBreadcrumbEntry(entry, { author, siteUrl, labels })
+  )
+}
+
+type BreadcrumbLabels = NonNullable<ReturnType<typeof getBreadcrumbsConfig>['labels']>
+
+function isCustomBreadcrumbItem(entry: unknown): entry is CustomBreadcrumbItem {
+  return typeof entry === 'object' && entry !== null && 'name' in entry && 'url' in entry
+}
+
+function resolveCustomBreadcrumbItem(item: CustomBreadcrumbItem, siteUrl: string): BreadcrumbItem {
+  if (item.url.startsWith('/')) return { name: item.name, url: `${siteUrl}${item.url}` }
+  return { name: item.name, url: item.url }
+}
+
+function buildArticleBreadcrumbToken(
+  entry: ArticleBreadcrumbEntry,
+  context: Readonly<{
+    article: Pick<Article, 'slug' | 'title' | 'category'>
+    siteUrl: string
+    categorySlug: string
+    folderSegments: string[]
+    labels: BreadcrumbLabels
+  }>
+): BreadcrumbItem[] {
+  if (isCustomBreadcrumbItem(entry)) {
+    return [resolveCustomBreadcrumbItem(entry, context.siteUrl)]
+  }
+  if (entry === 'home') return [{ name: context.labels.home ?? 'Home', url: context.siteUrl }]
+  if (entry === 'articles') {
+    return [{ name: context.labels.articles ?? 'Articles', url: `${context.siteUrl}/articles` }]
+  }
+  if (entry === 'primaryCategory') {
+    return [
+      {
+        name: context.article.category,
+        url: `${context.siteUrl}/articles/category/${context.categorySlug}`,
+      },
+    ]
+  }
+  if (entry === 'folderPath') {
+    return context.folderSegments.map((segment, index) => ({
+      name: formatCategoryName(segment),
+      url: `${context.siteUrl}/articles/${context.folderSegments.slice(0, index + 1).join('/')}`,
+    }))
+  }
+  return [{ name: context.article.title }]
+}
+
+function buildCategoryBreadcrumbEntry(
+  entry: CategoryBreadcrumbEntry,
+  context: Readonly<{ categoryName: string; siteUrl: string; labels: BreadcrumbLabels }>
+): BreadcrumbItem[] {
+  if (isCustomBreadcrumbItem(entry)) {
+    return [resolveCustomBreadcrumbItem(entry, context.siteUrl)]
+  }
+  if (entry === 'home') return [{ name: context.labels.home ?? 'Home', url: context.siteUrl }]
+  if (entry === 'articles') {
+    return [{ name: context.labels.articles ?? 'Articles', url: `${context.siteUrl}/articles` }]
+  }
+  return [{ name: context.categoryName }]
+}
+
+function buildAuthorBreadcrumbEntry(
+  entry: AuthorBreadcrumbEntry,
+  context: Readonly<{ author: AuthorProfile; siteUrl: string; labels: BreadcrumbLabels }>
+): BreadcrumbItem[] {
+  if (isCustomBreadcrumbItem(entry)) {
+    return [resolveCustomBreadcrumbItem(entry, context.siteUrl)]
+  }
+  if (entry === 'home') return [{ name: context.labels.home ?? 'Home', url: context.siteUrl }]
+  if (entry === 'articles') {
+    return [{ name: context.labels.articles ?? 'Articles', url: `${context.siteUrl}/articles` }]
+  }
+  if (entry === 'authors') {
+    return [
+      {
+        name: context.labels.authors ?? 'Authors',
+        url: `${context.siteUrl}/articles/authors`,
+      },
+    ]
+  }
+  return [{ name: context.author.name }]
+}
+
+export function resolveAuthorAvatar(author: AuthorProfile, config: ArticlesConfig): string {
+  if (!author.avatar) return ''
+  if (author.avatar.startsWith('http://') || author.avatar.startsWith('https://')) {
+    return author.avatar
+  }
+  const siteUrl = config.siteUrl.replace(/\/$/, '')
+  return `${siteUrl}/articles/authors/${author.slug}/${author.avatar.replace(/^\/+/, '')}`
+}
+
 export async function getArticleSitemapEntries(
   baseUrlOrConfig: string | ArticlesConfig
 ): Promise<MetadataRoute.Sitemap> {
@@ -206,7 +467,10 @@ export async function getArticleSitemapEntries(
   ).replace(/\/$/, '')
 
   try {
-    const [articles, categories] = await Promise.all([getAllArticles(), getAllCategories()])
+    const [articles, categories] = await Promise.all([
+      getAllArticles(typeof baseUrlOrConfig === 'string' ? undefined : baseUrlOrConfig),
+      getAllCategories(),
+    ])
 
     const articleEntries: MetadataRoute.Sitemap = articles.map((article) => {
       const dateStr = article.lastmod ?? article.date
@@ -226,7 +490,16 @@ export async function getArticleSitemapEntries(
       priority: 0.7,
     }))
 
-    return [...articleEntries, ...categoryEntries]
+    const authorEntries: MetadataRoute.Sitemap =
+      typeof baseUrlOrConfig === 'string' || baseUrlOrConfig.showAuthorPage === false
+        ? []
+        : getAllAuthors(baseUrlOrConfig).map((author) => ({
+            url: `${baseUrl}/articles/authors/${author.slug}`,
+            changeFrequency: 'monthly' as const,
+            priority: 0.6,
+          }))
+
+    return [...articleEntries, ...categoryEntries, ...authorEntries]
   } catch {
     return []
   }