Articles — @sonordev/site-kit/articles

import { Article, ArticleList } from '@sonordev/site-kit/articles/server-ui'
import {
  createPublicationRoutes, generateArticleMetadata, generateArticleSchema,
  generateArticleSitemap, generateArticleStaticParams, generateRssFeed,
  getArticle,
} from '@sonordev/site-kit/articles/server'
import type { PublicationRoutingOptions } from '@sonordev/site-kit/articles/server'

const siteUrl = 'https://example.com'
const routing = {
  basePath: '/journal',
  includeCategoryInPath: true,
  categoryPath: (slug: string) => `/journal?category=${encodeURIComponent(slug)}`,
} satisfies PublicationRoutingOptions

// Cards, related stories and cluster links now use /journal/category/slug.
const article = <Article slug="build-first" routing={routing} />
const archive = <ArticleList routing={routing} />

// Use these helpers from their corresponding Next.js route exports.
const metadata = await generateArticleMetadata('build-first', { siteUrl, ...routing })
const post = await getArticle('build-first')
const schema = post ? generateArticleSchema(post, { siteUrl, ...routing }) : null
// In app/journal/[category]/[slug]/page.tsx, wrap it to pass the routing:
// export function generateStaticParams() { return generateArticleStaticParams(routing) }
const params = await generateArticleStaticParams(routing) // { category, slug }[]
const sitemap = await generateArticleSitemap(siteUrl, {
  ...routing,
  includeCategories: false, // category filters don't need separate sitemap entries
  includeClusters: false, // enable when your site implements cluster routes
})
const rss = await generateRssFeed({ siteUrl, siteName: 'The Journal', ...routing })
const href = createPublicationRoutes(routing).post({ slug: 'build-first', category: 'guides' })

import { Article, ArticleList } from '@sonordev/site-kit/articles/server-ui'  // ✅
import { Article } from '@sonordev/site-kit/articles'                      // ❌ 500s

// app/article/page.tsx
import { ArticleList, PublicationLayout } from '@sonordev/site-kit/articles/server-ui'
import { generatePublicationMetadata } from '@sonordev/site-kit/articles/server'

export async function generateMetadata() {
  return generatePublicationMetadata({ siteName: 'My Site', siteUrl: 'https://example.com' })
}

export default function PublicationPage() {
  return (
    <PublicationLayout hero={{ title: 'The Journal', subtitle: 'Latest articles' }}>
      <ArticleList showCategoryFilter showPagination />
    </PublicationLayout>
  )
}

// app/article/[slug]/page.tsx
import { Article } from '@sonordev/site-kit/articles/server-ui'
import {
  generateArticleStaticParams,
  generateArticleMetadata,
  requireArticle,
} from '@sonordev/site-kit/articles/server'

export const generateStaticParams = generateArticleStaticParams

type Props = { params: Promise<{ slug: string }> }

export async function generateMetadata({ params }: Props) {
  const { slug } = await params
  await requireArticle(slug) // 404 for an unknown slug, before anything streams
  return generateArticleMetadata(slug, { siteName: 'My Site', siteUrl: 'https://example.com' })
}

export default async function Post({ params }: Props) {
  const { slug } = await params
  return <Article slug={slug} showRelated showToc showAuthor />
}

return generateArticleMetadata(slug, { siteName: 'My Site', images: false })

// app/article/topics/[slug]/page.tsx
// From `article/server-ui`, not `article` — it's an async server component that fetches
// the cluster, so it must stay out of the client-side `article` barrel.
import { ClusterLandingPage } from '@sonordev/site-kit/articles/server-ui'

export default function ClusterPage({ params }: { params: { slug: string } }) {
  return <ClusterLandingPage slug={params.slug} basePath="/article" />
}

// Data fetching
getArticle(slug)                    // Single post with full data, or null
requireArticle(slug)                // Same, but calls notFound() when there's no post
getAllArticleSlugs()                     // All published slugs (for generateStaticParams)
getArticleCategories()                  // Categories with post counts
getTopicCluster(slug)                // Cluster with pillar + support articles
getTopicClusters()                   // All clusters

// Next.js integration
generateArticleStaticParams(routing?)   // [{ slug }], or [{ category, slug }] with includeCategoryInPath
generateCategoryStaticParams()       // Returns [{ category }]
generateAuthorStaticParams()         // Returns [{ slug }]
// With no routing options, all three can be exported directly as
// `generateStaticParams`; the props Next passes are ignored.
generateArticleMetadata(slug, opts) // Next.js Metadata object; notFound() for a missing post.
                                     // opts.images: false when the route has its own opengraph-image card
generatePublicationMetadata(opts)      // Index page metadata
generateArticleCategoryMetadata(name, opts)

// Schema & SEO
generateArticleSchema(post, opts)   // JSON-LD Article with FAQ
generateArticleListSchema()             // JSON-LD for publication index
generateFaqSchema(items)             // FAQ Page schema
generateArticleSitemap(siteUrl)         // Sitemap entries for article

// Validation
validateArticleSeo(post)            // Returns field-by-field SEO audit
validateSeoTitle(title, keyphrase?)  // Title length + keyword checks
validateMetaDescription(desc)        // Description length check

<ArticleList site="charlotte.example.com" />           // also Article, PublicationSidebar, PublicationLayout, RelatedPosts, ClusterLandingPage
await getArticle(slug, { site: 'charlotte.example.com' })
await getAllArticles({ site: 'charlotte.example.com' })

interface ArticleProps {
  slug: string
  showRelated?: boolean    // Related posts section
  showToc?: boolean        // Table of contents
  showAuthor?: boolean     // Author card
  unstyled?: boolean       // Skip default styles
  notFound?: boolean       // Default true: notFound() when the post is missing. false renders a message.
  className?: string
  children?: (props: { post, toc, related }) => ReactNode  // Render prop
}

interface ArticleListProps {
  category?: string           // Filter by category slug
  tag?: string                // Filter by tag
  author?: string             // Filter by author
  featured?: boolean          // Featured posts only
  search?: string             // Search posts
  page?: number               // Default: 1
  perPage?: number            // Default: 12
  orderBy?: 'published_at' | 'title' | 'view_count'
  order?: 'asc' | 'desc'
  showCategoryFilter?: boolean
  showPagination?: boolean
  unstyled?: boolean
  className?: string
  children?: (props: { posts, pagination, categories }) => ReactNode
}

interface Article {
  slug: string; title: string; excerpt?: string; content: string;
  featured_image?: string; author?: ArticleAuthor; category?: ArticleCategory;
  tags?: string[]; meta_title?: string; meta_description?: string;
  faq_items?: { question: string; answer: string }[];
  article_type?: 'pillar' | 'support' | 'comparison' | 'faq' | 'glossary' | 'checklist';
  cluster_slug?: string; reading_time?: number; // the API column ('X min read')
  published_at?: string; status: 'draft' | 'published' | 'scheduled' | 'archived';
}

interface ArticleAuthor {
  name: string; slug: string; bio?: string; avatar_url?: string;
  title?: string; credentials?: string[]; expertise_areas?: string[];
  years_experience?: number; is_subject_matter_expert?: boolean;
}

interface TopicCluster {
  cluster_name: string; cluster_slug: string; core_topic: string;
  geo_target?: string; target_service_page?: string; article_count: number;
  pillar: Article | null; supports: Article[];
}