@fullstackdatasolutions/articles 0.4.3 → 0.5.1

package/src/markdown.ts

@@ -1,13 +1,17 @@
 import type { Element, Root, ElementContent } from 'hast'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
 import rehypePrism from 'rehype-prism-plus'
 import rehypeSanitize from 'rehype-sanitize'
+import rehypeSlug from 'rehype-slug'
 import rehypeStringify from 'rehype-stringify'
 import { remark } from 'remark'
 import remarkGfm from 'remark-gfm'
+import remarkGithubBlockquoteAlert from 'remark-github-blockquote-alert'
 import remarkParse from 'remark-parse'
 import remarkRehype from 'remark-rehype'
 import { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
+import type { TocItem } from './articleTypes'
 
 // Import the sanitizeImagePath function
 function sanitizeImagePath(rawPath: string, articleSlug: string): string | null {
@@ -51,6 +55,108 @@ function sanitizeImagePath(rawPath: string, articleSlug: string): string | null
   }
 }
 
+function styleFootnoteLinks(nodes: ElementContent[]): void {
+  nodes.forEach((n) => {
+    if (n.type !== 'element') return
+    const el = n as Element
+    if (el.tagName === 'a') {
+      const isBackRef =
+        el.properties?.['dataFootnoteBackref'] !== undefined ||
+        (el.children[0]?.type === 'text' && el.children[0].value === '↩')
+      if (isBackRef) {
+        el.properties.className = 'text-primary hover:underline ml-1'
+        if (typeof el.properties.href === 'string') {
+          el.properties.href = el.properties.href.replaceAll('#user-content-fnref-', '#ref-')
+        }
+      } else {
+        el.properties.className = 'text-primary hover:underline break-all'
+      }
+    }
+    if (el.children) styleFootnoteLinks(el.children)
+  })
+}
+
+function processFootnoteRef(node: Element): void {
+  if (
+    node.tagName !== 'sup' ||
+    node.children?.[0]?.type !== 'element' ||
+    (node.children[0] as Element).tagName !== 'a'
+  )
+    return
+
+  const link = node.children[0] as Element
+  const href = link.properties?.href
+  if (typeof href !== 'string' || !href.startsWith('#user-content-fn-')) return
+
+  delete link.properties.target
+  delete link.properties.rel
+  link.properties.className = 'text-primary hover:underline'
+  link.properties.href = href.replaceAll('#user-content-fn-', '#footnote-')
+
+  if (typeof node.properties?.id === 'string') {
+    link.properties.id = node.properties.id.replaceAll('user-content-fnref-', 'ref-')
+    delete node.properties.id
+  }
+
+  if (link.children?.[0]?.type === 'text') {
+    link.children[0].value = `[${link.children[0].value}]`
+  }
+}
+
+function processFootnotesSection(node: Element): void {
+  const cls = node.properties?.className
+  const isFootnotes =
+    node.tagName === 'section' &&
+    (Array.isArray(cls) ? cls.includes('footnotes') : cls === 'footnotes')
+  if (!isFootnotes) return
+
+  const olCandidate = node.children.find(
+    (child) => child.type === 'element' && (child as Element).tagName === 'ol'
+  )
+  if (olCandidate?.type !== 'element') return
+
+  const ol = olCandidate as Element
+  ol.properties.className = 'list-decimal ml-6 space-y-2 text-sm text-muted-foreground'
+
+  ol.children.forEach((li) => {
+    if (li.type !== 'element' || li.tagName !== 'li') return
+    const liEl = li as Element
+
+    if (liEl.properties) {
+      liEl.properties.className = 'pl-2'
+      if (typeof liEl.properties.id === 'string') {
+        liEl.properties.id = liEl.properties.id.replaceAll('user-content-fn-', 'footnote-')
+      }
+    }
+
+    const pIndex = liEl.children.findIndex(
+      (child) => child.type === 'element' && (child as Element).tagName === 'p'
+    )
+    if (pIndex !== -1) {
+      const p = liEl.children[pIndex] as Element
+      liEl.children.splice(pIndex, 1, ...p.children)
+    }
+
+    styleFootnoteLinks(liEl.children)
+  })
+
+  const hr: Element = {
+    type: 'element',
+    tagName: 'hr',
+    properties: { className: 'my-8 border-border' },
+    children: [],
+  }
+  const h3: Element = {
+    type: 'element',
+    tagName: 'h3',
+    properties: { className: 'text-lg font-semibold mb-4' },
+    children: [{ type: 'text', value: 'References' }],
+  }
+
+  node.children = [hr, h3, ol]
+  if (node.properties) node.properties.className = undefined
+}
+
 const customRenderer: Plugin<[], Root> = () => {
   return (tree: Root) => {
     // First pass: Apply general styles
@@ -124,136 +230,8 @@ const customRenderer: Plugin<[], Root> = () => {
 
     // Second pass: Fix footnotes and references
     visit(tree, 'element', (node: Element) => {
-      // Handle footnote references in the body
-      if (
-        node.tagName === 'sup' &&
-        node.children?.[0]?.type === 'element' &&
-        node.children[0].tagName === 'a'
-      ) {
-        const link = node.children[0] as Element
-        if (
-          link.properties?.href &&
-          typeof link.properties.href === 'string' &&
-          link.properties.href.startsWith('#user-content-fn-')
-        ) {
-          // Remove target and rel, and update class
-          if (link.properties) {
-            delete link.properties.target
-            delete link.properties.rel
-            link.properties.className = 'text-primary hover:underline'
-          }
-
-          // Update link href
-          link.properties.href = link.properties.href.replaceAll('#user-content-fn-', '#footnote-')
-
-          // Move ID from sup to link and update format
-          if (node.properties?.id && typeof node.properties.id === 'string') {
-            const newId = node.properties.id.replaceAll('user-content-fnref-', 'ref-')
-            link.properties.id = newId
-            delete node.properties.id
-          }
-
-          // Add brackets to content
-          if (link.children?.[0]?.type === 'text') {
-            link.children[0].value = `[${link.children[0].value}]`
-          }
-        }
-      }
-
-      // Handle footnotes section
-      if (
-        node.tagName === 'section' &&
-        (Array.isArray(node.properties?.className)
-          ? node.properties.className.includes('footnotes')
-          : node.properties?.className === 'footnotes')
-      ) {
-        // Find the ol
-        const olCandidate = node.children.find(
-          (child) => child.type === 'element' && (child as Element).tagName === 'ol'
-        )
-        if (olCandidate?.type === 'element') {
-          const ol = olCandidate as Element
-          ol.properties.className = 'list-decimal ml-6 space-y-2 text-sm text-muted-foreground'
-
-          // Process list items
-          ol.children.forEach((li) => {
-            if (li.type === 'element' && li.tagName === 'li') {
-              const liEl = li as Element
-              if (liEl.properties) {
-                liEl.properties.className = 'pl-2'
-                // Update ID: user-content-fn-1 -> footnote-1
-                if (typeof liEl.properties.id === 'string') {
-                  liEl.properties.id = liEl.properties.id.replaceAll(
-                    'user-content-fn-',
-                    'footnote-'
-                  )
-                }
-              }
-
-              // Unwrap p tags inside li
-              const pIndex = liEl.children.findIndex(
-                (child) => child.type === 'element' && (child as Element).tagName === 'p'
-              )
-
-              if (pIndex !== -1) {
-                const p = liEl.children[pIndex] as Element
-                liEl.children.splice(pIndex, 1, ...p.children)
-              }
-
-              // Style links inside the list item
-              const styleLinks = (nodes: ElementContent[]): void => {
-                nodes.forEach((n) => {
-                  if (n.type !== 'element') return
-                  const el = n as Element
-                  if (el.tagName === 'a') {
-                    const isBackRef =
-                      el.properties?.['dataFootnoteBackref'] !== undefined ||
-                      (el.children[0]?.type === 'text' && el.children[0].value === '↩')
-
-                    if (isBackRef) {
-                      el.properties.className = 'text-primary hover:underline ml-1'
-                      // Update backref href: #user-content-fnref-1 -> #ref-1
-                      if (typeof el.properties.href === 'string') {
-                        el.properties.href = el.properties.href.replaceAll(
-                          '#user-content-fnref-',
-                          '#ref-'
-                        )
-                      }
-                    } else {
-                      el.properties.className = 'text-primary hover:underline break-all'
-                    }
-                  }
-                  if (el.children) styleLinks(el.children)
-                })
-              }
-
-              styleLinks(liEl.children)
-            }
-          })
-
-          // Reconstruct section children with HR and H3
-          const hr: Element = {
-            type: 'element',
-            tagName: 'hr',
-            properties: { className: 'my-8 border-border' },
-            children: [],
-          }
-
-          const h3: Element = {
-            type: 'element',
-            tagName: 'h3',
-            properties: { className: 'text-lg font-semibold mb-4' },
-            children: [{ type: 'text', value: 'References' }],
-          }
-
-          node.children = [hr, h3, ol]
-
-          // Remove the footnotes class to avoid default styling interference
-          if (node.properties) {
-            node.properties.className = undefined
-          }
-        }
-      }
+      processFootnoteRef(node)
+      processFootnotesSection(node)
     })
   }
 }
@@ -286,8 +264,11 @@ export async function markdownToHtml(markdown: string, articleSlug?: string) {
     let processor = remark()
       .use(remarkParse)
       .use(remarkGfm)
+      .use(remarkGithubBlockquoteAlert)
       .use(remarkRehype)
       .use(customRenderer)
+      .use(rehypeSlug)
+      .use(rehypeAutolinkHeadings, { behavior: 'wrap' })
       // @ts-ignore
       .use(rehypePrism)
       .use(rehypeSanitize, {
@@ -312,3 +293,35 @@ export async function markdownToHtml(markdown: string, articleSlug?: string) {
     return markdown
   }
 }
+
+function nodeTextValue(c: ElementContent): string {
+  return c.type === 'text' ? (c as { value: string }).value : ''
+}
+
+function extractHeadingItem(node: Element): TocItem | null {
+  const match = /^h([1-6])$/.exec(node.tagName)
+  if (!match) return null
+  const id = typeof node.properties?.id === 'string' ? node.properties.id : ''
+  const text = node.children.map(nodeTextValue).join('')
+  if (!id || !text) return null
+  return { id, depth: Number.parseInt(match[1], 10), text }
+}
+
+export async function extractToc(markdown: string): Promise<TocItem[]> {
+  const headings: TocItem[] = []
+  const collectHeadings: Plugin<[], Root> = () => (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      const item = extractHeadingItem(node)
+      if (item) headings.push(item)
+    })
+  }
+  await remark()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(rehypeSlug)
+    .use(collectHeadings)
+    .use(rehypeStringify)
+    .process(markdown)
+  return headings
+}

package/src/seoUtils.ts

@@ -40,6 +40,7 @@ export async function generateArticleMetadata(
 
   const siteUrl = config.siteUrl.replace(/\/$/, '')
   const articleUrl = `${siteUrl}/articles/${slug}`
+  const canonicalUrl = article.canonicalUrl ?? articleUrl
   const imageUrl = article.featuredImage
     ? resolveImageUrl(article.featuredImage, siteUrl)
     : `${siteUrl}/placeholder-logo.png`
@@ -48,13 +49,7 @@ export async function generateArticleMetadata(
   return {
     title: `${article.title} | ${config.siteName}`,
     description,
-    keywords: [
-      'volunteer management software',
-      'political campaign software',
-      'campaign operations',
-      'civic tech',
-      ...(article.tags ?? []).map((tag) => tag.toLowerCase()),
-    ].join(', '),
+    keywords: [...(article.tags ?? []).map((tag) => tag.toLowerCase())].join(', '),
     openGraph: {
       title: article.title,
       description,
@@ -64,6 +59,7 @@ export async function generateArticleMetadata(
       locale: 'en_US',
       type: 'article',
       ...(article.date && { publishedTime: article.date }),
+      ...(article.lastmod && { modifiedTime: new Date(article.lastmod).toISOString() }),
       authors: [article.author],
       tags: article.tags ?? [],
     },
@@ -74,7 +70,7 @@ export async function generateArticleMetadata(
       images: [imageUrl],
     },
     alternates: {
-      canonical: articleUrl,
+      canonical: canonicalUrl,
     },
     robots: {
       index: true,
@@ -92,6 +88,9 @@ export async function generateArticleMetadata(
       ...(article.date && {
         'article:published_time': new Date(article.date).toISOString(),
       }),
+      ...(article.lastmod && {
+        'article:modified_time': new Date(article.lastmod).toISOString(),
+      }),
       'article:section': article.category,
       'article:tag': article.tags?.join(',') ?? '',
       'linkedin:owner': process.env.NEXT_PUBLIC_LINKEDIN_COMPANY_ID ?? '',
@@ -123,6 +122,9 @@ export function generateArticlesIndexMetadata(config: ArticlesConfig): Metadata
     },
     alternates: {
       canonical: indexUrl,
+      types: {
+        'application/rss+xml': `${siteUrl}/articles/feed.xml`,
+      },
     },
     robots: {
       index: true,
@@ -198,12 +200,16 @@ export async function getArticleSitemapEntries(
   try {
     const [articles, categories] = await Promise.all([getAllArticles(), getAllCategories()])
 
-    const articleEntries: MetadataRoute.Sitemap = articles.map((article) => ({
-      url: `${baseUrl}/articles/${article.slug}`,
-      lastModified: article.date ? new Date(article.date) : undefined,
-      changeFrequency: 'weekly' as const,
-      priority: 0.8,
-    }))
+    const articleEntries: MetadataRoute.Sitemap = articles.map((article) => {
+      const dateStr = article.lastmod ?? article.date
+      const lastModified = dateStr ? new Date(dateStr) : undefined
+      return {
+        url: `${baseUrl}/articles/${article.slug}`,
+        lastModified,
+        changeFrequency: 'weekly' as const,
+        priority: 0.8,
+      }
+    })
 
     const categoryEntries: MetadataRoute.Sitemap = categories.map((cat) => ({
       url: `${baseUrl}/articles/category/${cat.slug}`,

package/src/server-articles.ts

@@ -3,8 +3,8 @@ import matter from 'gray-matter'
 import fs from 'node:fs'
 import path from 'node:path'
 import readingTime from 'reading-time'
-import { markdownToHtml } from './markdown'
-import type { Article, CategoryInfo } from './articleTypes'
+import { markdownToHtml, extractToc } from './markdown'
+import type { Article, CategoryInfo, FaqItem, HowToStep } from './articleTypes'
 
 const articlesDirectory = path.join(process.cwd(), 'public/articles')
 
@@ -56,6 +56,14 @@ function sanitizeImagePath(rawPath: string, articleSlug: string): string | null
   return `/articles/${articleSlug}/${cleanPath}`
 }
 
+function findArticleFile(slug: string): { filePath: string; contentType: 'md' | 'mdx' } | null {
+  const mdPath = path.join(articlesDirectory, slug, 'article.md')
+  const mdxPath = path.join(articlesDirectory, slug, 'article.mdx')
+  if (fs.existsSync(mdPath)) return { filePath: mdPath, contentType: 'md' }
+  if (fs.existsSync(mdxPath)) return { filePath: mdxPath, contentType: 'mdx' }
+  return null
+}
+
 export function getAvailableArticleSlugs(): string[] {
   try {
     if (!fs.existsSync(articlesDirectory)) return []
@@ -63,18 +71,8 @@ export function getAvailableArticleSlugs(): string[] {
     return items
       .filter((item) => item.isDirectory())
       .filter((dir) => {
-        const articleDir = path.join(articlesDirectory, dir.name)
         try {
-          const entries: (fs.Dirent | string)[] = fs.readdirSync(articleDir, {
-            withFileTypes: true,
-          })
-          return entries.some((entry) => {
-            const name = typeof entry === 'string' ? entry : entry?.name
-            if (name !== 'article.md') return false
-            if (typeof entry === 'string') return true
-            if (typeof entry?.isFile === 'function') return entry.isFile()
-            return true
-          })
+          return findArticleFile(dir.name) !== null
         } catch {
           return false
         }
@@ -86,31 +84,55 @@ export function getAvailableArticleSlugs(): string[] {
   }
 }
 
+function parseDateField(rawDate: unknown): string | undefined {
+  if (!rawDate) return undefined
+  try {
+    const parsed = new Date(rawDate as string)
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString().split('T')[0]
+  } catch {
+    // ignore invalid dates
+  }
+  return undefined
+}
+
+function resolveFeaturedImage(rawImage: unknown, slug: string): string {
+  const img = typeof rawImage === 'string' ? rawImage : ''
+  if (img && !img.startsWith('http')) return sanitizeImagePath(img, slug) || '/placeholder-logo.png'
+  if (!img) return findArticleImage(slug) || '/placeholder-logo.png'
+  return img
+}
+
+function parseFaqItems(raw: unknown): FaqItem[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  const items = raw.filter(
+    (item): item is FaqItem =>
+      typeof item === 'object' &&
+      item !== null &&
+      typeof (item as FaqItem).question === 'string' &&
+      typeof (item as FaqItem).answer === 'string'
+  )
+  return items.length ? items : undefined
+}
+
+function parseHowToSteps(raw: unknown): HowToStep[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  const steps = raw.filter(
+    (item): item is HowToStep =>
+      typeof item === 'object' &&
+      item !== null &&
+      typeof (item as HowToStep).name === 'string' &&
+      typeof (item as HowToStep).text === 'string'
+  )
+  return steps.length ? steps : undefined
+}
+
 async function getArticleSummary(slug: string): Promise<Article | null> {
   try {
-    const articlePath = path.join(articlesDirectory, slug, 'article.md')
-    if (!fs.existsSync(articlePath)) return null
-    const fileContent = fs.readFileSync(articlePath, 'utf8')
+    const found = findArticleFile(slug)
+    if (!found) return null
+    const fileContent = fs.readFileSync(found.filePath, 'utf8')
     const { data, content: markdownContent } = matter(fileContent)
     const readTime = getReadingTime(markdownContent)
-    let featuredImage = data.featuredImage || ''
-    if (featuredImage && !featuredImage.startsWith('http')) {
-      const sanitizedPath = sanitizeImagePath(featuredImage, slug)
-      featuredImage = sanitizedPath || '/placeholder-logo.png'
-    } else if (!featuredImage) {
-      featuredImage = findArticleImage(slug) || '/placeholder-logo.png'
-    }
-    let articleDate: string | undefined
-    if (data.date) {
-      try {
-        const parsedDate = new Date(data.date)
-        if (!Number.isNaN(parsedDate.getTime())) {
-          articleDate = parsedDate.toISOString().split('T')[0]
-        }
-      } catch {
-        console.warn(`Invalid date for article ${slug}: ${data.date}`)
-      }
-    }
     const allTags: string[] = Array.isArray(data.tags)
       ? data.tags.filter((t: unknown) => typeof t === 'string' && String(t).trim())
       : []
@@ -120,13 +142,21 @@ async function getArticleSummary(slug: string): Promise<Article | null> {
       slug,
       title: data.title || slug.replaceAll('-', ' '),
       excerpt: data.excerpt || '',
-      date: articleDate,
+      date: parseDateField(data.date),
+      lastmod: parseDateField(data.lastmod),
       author: data.author || 'Andrew Blase',
       category: categories[0],
       categories,
       readTime,
-      featuredImage,
+      featuredImage: resolveFeaturedImage(data.featuredImage, slug),
       tags: data.tags || [],
+      contentType: found.contentType,
+      draft: data.draft === true,
+      faq: parseFaqItems(data.faq),
+      howTo: parseHowToSteps(data.howTo),
+      canonicalUrl: typeof data.canonicalUrl === 'string' ? data.canonicalUrl : undefined,
+      articleType: typeof data.articleType === 'string' ? data.articleType : undefined,
+      series: typeof data.series === 'string' ? data.series : undefined,
     }
   } catch (error) {
     console.error(`Error loading article ${slug}:`, error)
@@ -136,49 +166,21 @@ async function getArticleSummary(slug: string): Promise<Article | null> {
 
 export const getArticleMetadata = cache(async (slug: string): Promise<Article | null> => {
   try {
-    const articlePath = path.join(articlesDirectory, slug, 'article.md')
-    if (!fs.existsSync(articlePath)) return null
-    const fileContent = fs.readFileSync(articlePath, 'utf8')
-    const { data, content: markdownContent } = matter(fileContent)
-    const htmlContent = await markdownToHtml(markdownContent, slug)
-    const readTime = getReadingTime(markdownContent)
-    let featuredImage = data.featuredImage || ''
-    if (featuredImage && !featuredImage.startsWith('http')) {
-      const sanitizedPath = sanitizeImagePath(featuredImage, slug)
-      featuredImage = sanitizedPath || '/placeholder-logo.png'
-    } else if (!featuredImage) {
-      featuredImage = findArticleImage(slug) || '/placeholder-logo.png'
-    }
-    let articleDate: string | undefined
-    if (data.date) {
-      try {
-        const parsedDate = new Date(data.date)
-        if (!Number.isNaN(parsedDate.getTime())) {
-          articleDate = parsedDate.toISOString().split('T')[0]
-        }
-      } catch {
-        console.warn(`Invalid date for article ${slug}: ${data.date}`)
-      }
-    }
-    const allTags: string[] = Array.isArray(data.tags)
-      ? data.tags.filter((t: unknown) => typeof t === 'string' && String(t).trim())
-      : []
-    const categories: string[] =
-      allTags.length > 0 ? allTags.map((t: string) => t.replaceAll('-', ' ').trim()) : ['Campaigns']
-    return {
-      slug,
-      title: data.title || slug.replaceAll('-', ' '),
-      excerpt: data.excerpt || '',
-      date: articleDate,
-      author: data.author || 'Andrew Blase',
-      category: categories[0],
-      categories,
-      readTime,
-      featuredImage,
-      tags: data.tags || [],
-      content: markdownContent,
-      htmlContent,
+    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)
     }
+    return { ...summary, content: markdownContent, htmlContent, mdxSource, toc }
   } catch (error) {
     console.error(`Error loading article ${slug}:`, error)
     return null
@@ -192,6 +194,7 @@ export const getAllArticles = cache(async (): Promise<Article[]> => {
   return articles
     .filter((article): article is Article => article !== null)
     .filter((article) => !article.date || article.date <= currentDate)
+    .filter((article) => !(article.draft && process.env.NODE_ENV === 'production'))
     .sort((a, b) => {
       if (!a.date && !b.date) return 0
       if (!a.date) return 1

package/src/server.ts

@@ -20,7 +20,9 @@ export {
   getArticleSitemapEntries,
 } from './seoUtils'
 
-export { markdownToHtml } from './markdown'
+export { markdownToHtml, extractToc } from './markdown'
+export { ArticleContent } from './ArticleContent'
+export { ArticleTOC } from './ArticleTOC'
 
-export type { Article, CategoryInfo } from './articleTypes'
+export type { Article, CategoryInfo, TocItem } from './articleTypes'
 export type { ArticlesConfig } from './articlesConfig'