@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/src/articleTypes.ts

@@ -14,6 +14,23 @@ export interface HowToStep {
   text: string
 }
 
+/**
+ * A real-world thing an article is about, emitted as schema.org `about`.
+ * `sameAs` should point at an authoritative identifier for the entity
+ * (Wikipedia, Wikidata, an official site) - that URL is what lets a consumer
+ * resolve "Pathfinder" the game system rather than guessing from the string.
+ */
+export interface EntityReference {
+  name: string
+  sameAs?: string
+}
+
+/** An outbound source an article cites, emitted as schema.org `citation`. */
+export interface CitationReference {
+  name: string
+  url?: string
+}
+
 export interface Article {
   slug: string
   title: string
@@ -44,6 +61,18 @@ export interface Article {
   toc?: TocItem[]
   faq?: FaqItem[]
   howTo?: HowToStep[]
+  /**
+   * A direct, self-contained answer to the article's core question, 40-60
+   * words. Rendered by `ArticleAnswer`, emitted as the Article schema's
+   * `abstract`, used as the `acceptedAnswer` when `articleType` is
+   * `'QAPage'`, and placed at the top of the article's markdown twin - the
+   * one passage most likely to be lifted verbatim by an answer engine.
+   */
+  answer?: string
+  /** Entities this article is about. Emitted as schema.org `about`. */
+  about?: EntityReference[]
+  /** Outbound sources. Emitted as schema.org `citation`. */
+  citation?: CitationReference[]
   canonicalUrl?: string
   articleType?: string
   series?: string
@@ -165,6 +194,13 @@ export interface AuthorProfile {
   promise?: string
   /** Structured long-form origin story - see `RichText`/`RichTextSection`. */
   originStory?: RichText
+  /**
+   * Topics this author writes about, emitted as Person `knowsAbout`. Omit to
+   * derive it from the categories of their own published articles - unlike
+   * `credentials`/`proof`, subject matter is verifiable from the corpus
+   * itself, so it does belong in structured data.
+   */
+  knowsAbout?: string[]
   /** Who this author's content/work is for, e.g. "New game masters", "Streaming DMs". */
   servesWho?: string[]
   /** Core beliefs/approach statements. */
@@ -177,6 +213,27 @@ export interface AuthorProfile {
   credentials?: string[]
   /** Concrete, sourceable proof points. */
   proof?: ProofItem[]
+  /**
+   * The one canonical URL identifying this person across every site they
+   * publish on. Used *only* to derive the Person `@id`, so the same author
+   * resolves to a single entity everywhere instead of one entity per site.
+   *
+   * Deliberately separate from `url`: that field also drives byline link
+   * targets, the author page's Open Graph URL, and its `CollectionPage` URL,
+   * so pointing it at another domain would send readers off-site and hand
+   * this site's author page a canonical belonging to a different one.
+   * `identityUrl` changes nothing a reader sees.
+   *
+   * Set the same value on every site. Falls back to `url`, then to this
+   * site's own author page.
+   */
+  identityUrl?: string
+  /**
+   * Additional profile URLs identifying this same person elsewhere, merged
+   * into the Person schema's `sameAs` alongside the derived social links.
+   * List the author's pages on the other sites here.
+   */
+  sameAs?: string[]
   /** Primary call-to-action rendered on the author's page. */
   primaryCta?: {
     label: string

package/src/articlesConfig.ts

@@ -1,5 +1,5 @@
 import type { ComponentType } from 'react'
-import type { AuthorProfile, PathDefinition } from './articleTypes'
+import type { AuthorProfile, EntityReference, PathDefinition } from './articleTypes'
 import type { ArticleEventHandler } from './events'
 
 /** Keys for each renderable section of the articles listing page. */
@@ -141,6 +141,56 @@ export interface BreadcrumbsConfig {
   labels?: BreadcrumbLabels
 }
 
+/** Payload passed to `ArticlesConfig.onAiCrawl`. */
+export interface AiCrawlEvent {
+  /** Article slug whose markdown twin was fetched. */
+  slug: string
+  /** Matched crawler name (e.g. `'GPTBot'`), or `'unknown'` when the agent is not recognized. */
+  crawler: string
+  /** Raw `User-Agent` header, or an empty string when absent. */
+  userAgent: string
+}
+
+/**
+ * The publishing entity behind the site. Drives `OrganizationSchema`,
+ * `WebSiteSchema`, and the `publisher` reference on every article - so all
+ * three point at one `@id` instead of repeating an inline, unlinked
+ * `Organization` stub per page.
+ */
+export interface OrganizationConfig {
+  /** schema.org type. Use `'Person'` for a personal brand. Default: `'Organization'`. */
+  type?: 'Organization' | 'Person'
+  /** Entity name. Falls back to `siteName`. */
+  name?: string
+  /** Entity homepage. Falls back to `siteUrl`. */
+  url?: string
+  /** Logo URL. Site-relative paths are resolved against `siteUrl`. */
+  logo?: string
+  /** Entity description. Falls back to `ArticlesConfig.description`. */
+  description?: string
+  /** Profile URLs that identify the same entity elsewhere (social, Crunchbase, Wikidata). */
+  sameAs?: string[]
+  /**
+   * The umbrella entity this site belongs to, for a network of sites run by
+   * one publisher. Emitted as `parentOrganization` - the link that lets
+   * authority earned by the network attach to each site in it, instead of
+   * each site standing alone.
+   */
+  parentOrganization?: {
+    name: string
+    url: string
+  }
+  /**
+   * Search URL template for the `WebSite` `SearchAction`, e.g.
+   * `'/search?q={search_term_string}'`. Omitted by default - the library's
+   * own search is client-side with no crawlable results URL, so declaring one
+   * that does not exist would be a false claim. Only set this if the app
+   * actually serves search results at that URL. Must contain the literal
+   * `{search_term_string}` placeholder.
+   */
+  searchUrlTemplate?: string
+}
+
 /** Top-level configuration object. Pass one instance to every library component. */
 export interface ArticlesConfig {
   /** Canonical base URL of the site, used in metadata and JSON-LD. Example: `'https://yoursite.com'` */
@@ -203,6 +253,94 @@ export interface ArticlesConfig {
    * step rather than a build-time failure otherwise.
    */
   paths?: Record<string, PathDefinition>
+  /**
+   * Template for the `<title>` tag on article, category, series, and author
+   * pages. Supports `{title}` and `{siteName}` placeholders.
+   * Default: `'{title} | {siteName}'`.
+   *
+   * Google truncates a result title around 60 characters, and a site name
+   * suffix spends that budget on every page. Set `'{title}'` to drop it when
+   * your titles are already long and your brand draws little search volume -
+   * the suffix is only earning its characters if people search for the brand.
+   */
+  titleTemplate?: string
+  /**
+   * BCP 47 language tag for the site's content. Emitted as the Article
+   * schema's `inLanguage` and the RSS channel `<language>`. Default: `'en'`.
+   */
+  language?: string
+  /**
+   * Set to `false` when articles sit behind a paywall or registration wall.
+   * Default: `true`, emitted as the Article schema's `isAccessibleForFree` -
+   * an explicit "this is readable" signal, since consumers that cannot tell
+   * tend to skip suspected-paywalled sources.
+   */
+  isAccessibleForFree?: boolean
+  /**
+   * CSS selectors marking the parts of an article suitable for text-to-speech,
+   * emitted as the Article schema's `speakable`. Omitted by default - the
+   * correct selectors depend on the consuming app's own markup, and guessing
+   * them would point at elements that may not exist.
+   */
+  speakableSelectors?: string[]
+  /**
+   * Set to `true` to derive `FAQPage` entries from question-shaped `##`
+   * headings and the paragraph that follows each one. Default: `false` -
+   * turning prose into structured data without the author's intent can
+   * promote a rhetorical heading into a published Q&A pair, so this is
+   * opt-in. Explicit `faq` frontmatter always wins over derived entries.
+   */
+  deriveFaqFromHeadings?: boolean
+  /**
+   * Shared entity vocabulary, keyed by an app-chosen slug. Article `about`
+   * entries may reference a key here instead of repeating a name/`sameAs`
+   * pair - the point of `about` is that a consumer can resolve one entity
+   * across a corpus, which free-text names spelled three different ways
+   * defeat. `validateArticles` warns on `about` keys with no registry entry.
+   */
+  entities?: Record<string, EntityReference>
+  /**
+   * Where `lastmod` comes from when frontmatter omits it.
+   * - `'published'` (default): reuse the publish date, as before 1.3.0.
+   * - `'none'`: leave `lastmod` unset, so `dateModified` is omitted rather
+   *   than repeating a stale publish date.
+   * - `'fileMtime'`: read the article file's modification time. Accurate
+   *   locally; on a CI runner that clones fresh, every file's mtime is the
+   *   checkout time, which would report the whole corpus as updated today.
+   *   Only use it where the build preserves mtimes.
+   */
+  lastmodFallback?: 'published' | 'none' | 'fileMtime'
+  /**
+   * Called when an AI crawler fetches an article's markdown twin. The one
+   * choke point where those requests land, so it is the only place a site
+   * can measure whether any of its AI-readable content is being read, and
+   * by which bot. No PII: the payload carries the slug, the matched crawler
+   * name, and the raw user agent string only.
+   */
+  onAiCrawl?: (event: AiCrawlEvent) => void
+  /**
+   * The publishing entity behind the site. Omit to keep the pre-1.3.0 inline
+   * `{'@type':'Organization', name: siteName}` publisher stub on articles.
+   * Set it to emit `OrganizationSchema`/`WebSiteSchema` in the root layout and
+   * have every article, author, and collection page reference the same `@id`.
+   */
+  organization?: OrganizationConfig
+  /**
+   * Default `aiCrawl` value for articles whose frontmatter omits the key.
+   * Default: `false` (every article stays opted out unless it sets
+   * `aiCrawl: true`). Set to `true` on a site whose goal is being cited by
+   * answer engines to opt the whole corpus in at once; per-article
+   * `aiCrawl: false` still wins and keeps that article blocked.
+   */
+  aiCrawlDefault?: boolean
+  /**
+   * Set to `false` to serve article markdown twins as the bare body, with no
+   * attribution header. Default: `true` - the twin is prefixed with the
+   * title, excerpt, canonical source URL, dates, author, and site name so a
+   * model reading `/articles/[slug].md` can attribute it. Only applies when
+   * a config is available (i.e. via `getArticleMarkdownResponse`).
+   */
+  markdownTwinHeader?: boolean
   /**
    * Vendor-neutral event callback (Phase 27F). Fired by components/hooks at
    * meaningful reader-journey moments (see `ArticleEvent` in `events.ts`).
@@ -231,3 +369,40 @@ export function getBreadcrumbsConfig(config: ArticlesConfig): BreadcrumbsConfig
   if (config.breadcrumbs === false) return {}
   return config.breadcrumbs ?? {}
 }
+
+/** Stable `@id` for the site's publishing entity. */
+export function getOrganizationId(config: Pick<ArticlesConfig, 'siteUrl'>): string {
+  return `${config.siteUrl.replace(/\/$/, '')}/#organization`
+}
+
+/** Stable `@id` for the site itself. */
+export function getWebSiteId(config: Pick<ArticlesConfig, 'siteUrl'>): string {
+  return `${config.siteUrl.replace(/\/$/, '')}/#website`
+}
+
+/** Stable `@id` for an author, so every article by them resolves to one Person. */
+export function getPersonId(authorUrl: string): string {
+  return `${authorUrl.replace(/\/$/, '')}#person`
+}
+
+/** Resolves a possibly site-relative asset path against `siteUrl`. */
+export function resolveEntityUrl(value: string, config: Pick<ArticlesConfig, 'siteUrl'>): string {
+  if (/^https?:\/\//.test(value)) return value
+  return `${config.siteUrl.replace(/\/$/, '')}/${value.replace(/^\/+/, '')}`
+}
+
+export const DEFAULT_TITLE_TEMPLATE = '{title} | {siteName}'
+
+/**
+ * Applies `ArticlesConfig.titleTemplate` to a page title. Kept here rather
+ * than inlined at each call site so article, category, series, and author
+ * pages can never drift apart on how the site name is appended.
+ */
+export function formatPageTitle(
+  title: string,
+  config: Pick<ArticlesConfig, 'siteName' | 'titleTemplate'>
+): string {
+  return (config.titleTemplate ?? DEFAULT_TITLE_TEMPLATE)
+    .replaceAll('{title}', title)
+    .replaceAll('{siteName}', config.siteName)
+}

package/src/authorUtils.ts

@@ -1,6 +1,22 @@
 import type { ArticlesConfig } from './articlesConfig'
 import type { AuthorProfile, AuthorSocial } from './articleTypes'
 
+/**
+ * The canonical identity URL a Person `@id` derives from. Prefers the
+ * explicit cross-site `identityUrl`, then `url`, then this site's own author
+ * page - so an author who configures nothing keeps a per-site identity, and
+ * one who sets `identityUrl` gets the same `@id` on every site.
+ */
+export function getAuthorIdentityUrl(
+  author: AuthorProfile,
+  config?: Pick<ArticlesConfig, 'siteUrl'>
+): string | undefined {
+  if (author.identityUrl) return author.identityUrl
+  if (author.url) return author.url
+  if (!config) return undefined
+  return `${config.siteUrl.replace(/\/$/, '')}/articles/authors/${author.slug}`
+}
+
 export function getAuthorUrl(author: AuthorProfile): string {
   return author.url ?? `/articles/authors/${author.slug}`
 }
@@ -19,7 +35,9 @@ export function getAuthorAvatar(
 }
 
 export function getAuthorSameAs(author: AuthorProfile): string[] {
-  return getAuthorSocialLinks(author).map((link) => link.href)
+  const derived = getAuthorSocialLinks(author).map((link) => link.href)
+  const explicit = author.sameAs?.filter((url) => url.trim() !== '') ?? []
+  return [...new Set([...derived, ...explicit])]
 }
 
 export interface AuthorSocialLink {

package/src/errorReporting.ts

@@ -2,6 +2,7 @@ export type ArticlesErrorCode =
   | 'article-directory-read-failed'
   | 'article-load-failed'
   | 'article-markdown-load-failed'
+  | 'ai-crawl-handler-failed'
   | 'markdown-conversion-failed'
   | 'unsafe-image-path'
 

package/src/index.ts

@@ -16,13 +16,20 @@ export { AuthorArticlesPage } from './AuthorArticlesPage'
 export { AuthorCard, AuthorSocialLinks } from './AuthorCard'
 export { AuthorDetailHero } from './AuthorDetailHero'
 export { Breadcrumb, BreadcrumbSchema } from './Breadcrumb'
-export { ArticleSEO, CollectionPageSchema, FAQPageSchema } from './ArticleSchemas'
+export {
+  ArticleSEO,
+  CollectionPageSchema,
+  FAQPageSchema,
+  OrganizationSchema,
+  WebSiteSchema,
+} from './ArticleSchemas'
 
 export { ArticleSocialShare } from './ArticleSocialShare'
 export { ArticleNavigation } from './ArticleNavigation'
 export { RelatedArticlesSection } from './RelatedArticlesSection'
 export { ArticleBackLink } from './ArticleBackLink'
 export { ArticleTOC } from './ArticleTOC'
+export { ArticleAnswer } from './ArticleAnswer'
 export { ScrollToTop } from './ScrollToTop'
 export { PaginationNav } from './PaginationNav'
 export { ArticleViewTracker, CtaViewTracker } from './eventTracking'
@@ -56,13 +63,20 @@ export type {
   CategoryBreadcrumbEntry,
   AuthorBreadcrumbEntry,
   CustomBreadcrumbItem,
+  OrganizationConfig,
+  AiCrawlEvent,
 } from './articlesConfig'
 export {
   DEFAULT_LAYOUT,
   DEFAULT_PAGE_SIZE,
   DEFAULT_CATEGORIES_PAGE_SIZE,
+  DEFAULT_TITLE_TEMPLATE,
   breadcrumbsAreEnabled,
+  formatPageTitle,
   getBreadcrumbsConfig,
+  getOrganizationId,
+  getPersonId,
+  getWebSiteId,
 } from './articlesConfig'
 export type {
   Article,
@@ -70,6 +84,8 @@ export type {
   AuthorSocial,
   BreadcrumbItem,
   CategoryInfo,
+  CitationReference,
+  EntityReference,
   FaqItem,
   HowToStep,
   PathDefinition,

package/src/markdown.ts

@@ -10,7 +10,7 @@ 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 type { FaqItem, TocItem } from './articleTypes'
 import type { ArticlesConfig, LinkTargetStrategy } from './articlesConfig'
 import { reportArticlesError } from './errorReporting'
 import { isExternalHttpLink, isNonBrowserNavigationLink } from './linkClassification'
@@ -473,3 +473,102 @@ export async function extractToc(markdown: string): Promise<TocItem[]> {
     .process(stripInlineTagsFromHeadings(markdown))
   return headings
 }
+
+// Interrogatives that open a genuine reader question. Deliberately a closed
+// list rather than "any heading ending in ?" - a rhetorical heading like
+// "Sound familiar?" ends in a question mark too, and promoting it to a
+// published Q&A pair would be worse than omitting it.
+const QUESTION_OPENERS =
+  /^(what|how|why|when|where|who|which|can|should|does|do|is|are|will|would|must)\b/i
+
+/**
+ * Derives `FaqItem`s from question-shaped `##` headings and the prose that
+ * follows each one, for `ArticlesConfig.deriveFaqFromHeadings`.
+ *
+ * Line-based on purpose: it runs for every article at summary time, and the
+ * shapes it must reject (fenced code, a heading with no prose under it) are
+ * cheaper to detect by scanning than by walking a parsed AST.
+ */
+export function deriveFaqFromHeadings(markdown: string): FaqItem[] {
+  const items: FaqItem[] = []
+  const collector = createFaqCollector(items)
+  let inFence = false
+
+  for (const line of markdown.split('\n')) {
+    if (FENCE.test(line)) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+    collector.consume(line)
+  }
+  collector.flush()
+
+  return items
+}
+
+const FENCE = /^\s*(```|~~~)/
+const ANY_HEADING = /^#{1,6}\s/
+
+function isSpace(char: string | undefined): boolean {
+  return char === ' ' || char === '\t'
+}
+
+/** Drops closing-hash decoration (`## Heading ##`) without a `#+$` scan. */
+function trimTrailingHashes(value: string): string {
+  let end = value.length
+  while (end > 0 && value[end - 1] === '#') end--
+  return value.slice(0, end).trimEnd()
+}
+
+/**
+ * Extracts a question-shaped h2's text, or `null` for any other line.
+ *
+ * Deliberately string operations rather than a capture regex: every anchored
+ * form of this (`(.*\S)\s*$`, `\s+(.*)$`, `#+$`) backtracks super-linearly,
+ * and this runs over every line of every article.
+ */
+function readQuestionHeading(line: string): string | null {
+  if (!line.startsWith('##') || line.startsWith('###')) return null
+  if (!isSpace(line[2])) return null
+  const text = trimTrailingHashes(line.slice(3).trim())
+  if (!text.endsWith('?') || !QUESTION_OPENERS.test(text)) return null
+  return text
+}
+
+/**
+ * Line-at-a-time state machine pairing a question heading with the prose
+ * under it. Split out of `deriveFaqFromHeadings` so the loop there stays a
+ * flat fence check plus a delegation.
+ */
+function createFaqCollector(items: FaqItem[]) {
+  let pending: string | null = null
+  let buffer: string[] = []
+
+  const flush = (): void => {
+    if (pending && buffer.length > 0) {
+      items.push({ question: pending, answer: buffer.join(' ').trim() })
+    }
+    pending = null
+    buffer = []
+  }
+
+  const consume = (line: string): void => {
+    if (ANY_HEADING.test(line)) {
+      flush()
+      pending = readQuestionHeading(line)
+      return
+    }
+    if (!pending) return
+    // A blank line only ends an answer that has already started - the blank
+    // between a heading and its first paragraph must not discard the pending
+    // question.
+    if (line.trim() === '') {
+      if (buffer.length > 0) flush()
+      return
+    }
+    buffer.push(line.trim())
+  }
+
+  return { consume, flush }
+}

package/src/nextjs.ts

@@ -1,11 +1,14 @@
 // 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 { getMarkdownTwinResponse } from './server-articles'
 import type { ArticlesConfig } from './articlesConfig'
 
 /**
- * Returns a Next.js App Router GET handler for serving article markdown.
+ * Returns a Next.js App Router GET handler for serving markdown twins -
+ * articles plus category/author/series listings, dispatched by slug prefix.
+ * The request is passed through so `ArticlesConfig.onAiCrawl` can see the
+ * user agent.
  *
  * Usage in app/api/articles-markdown/[...slug]/route.ts:
  *   import { createArticleMarkdownHandler } from '@fullstackdatasolutions/articles/nextjs'
@@ -14,14 +17,14 @@ import type { ArticlesConfig } from './articlesConfig'
  */
 export function createArticleMarkdownHandler(config: ArticlesConfig) {
   async function GET(
-    _request: NextRequest,
+    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 getMarkdownTwinResponse(cleanSlug, config, { headers: request.headers })
   }
   return { GET }
 }