@stack-mode/site-manager-kit 1.47.0 → 1.48.0

package/README.md

@@ -547,7 +547,7 @@ Site Manager's `docs/wiring.md` explains the whole process and how to fix each k
 With the Blog section on, a site reads posts, categories and tags. Set the Blog posts page pattern in Site Manager (Search Listings, page addresses) to match the site's route, for example `/blog/{slug}`, so each post gets its search listing, sitemap entry and `url`.
 
 ```tsx
-import { blogPostingJsonLd, getPost, getPosts, pageMetadata } from "site-manager-kit";
+import { blogPostingJsonLd, faqPageJsonLd, getPost, getPosts, pageMetadata, tableOfContents } from "site-manager-kit";
 
 // app/blog/page.tsx
 const { posts, paging } = await getPosts({ page, perPage: 12 });
@@ -556,6 +556,9 @@ const { posts, paging } = await getPosts({ page, perPage: 12 });
 export const generateMetadata = async ({ params }) => pageMetadata(`/blog/${(await params).slug}`);
 const post = await getPost(slug); // null: notFound()
 const ld = JSON.stringify(blogPostingJsonLd(post, { publisherName: site.business.displayName })).replace(/</g, "\\u003c");
+// The article's own FAQs (empty when it has none or the site turns them off) and its table of contents:
+const faqLd = faqPageJsonLd(post.faqs, post.url); // render with jsonLdScript when not null
+const toc = tableOfContents(post.bodyHtml, post.tocLevels); // [{ id, text, level }], link each as #id
 <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: ld }} />
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stack-mode/site-manager-kit",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "description": "Reads a site's content from Site Manager and builds its metadata, sitemap, robots, redirects, forms and refreshes. For Next.js App Router sites on Vercel.",
   "license": "UNLICENSED",
   "repository": {

package/src/blog.ts

@@ -1,5 +1,5 @@
 import { bp, bpWithMeta, tagsFor } from "./client";
-import type { BlogCategory, BlogFeed, BlogPage, BlogPost, BlogPostSummary, BlogTag, Paging } from "./types";
+import type { ArticleFaq, BlogCategory, BlogFeed, BlogPage, BlogPost, BlogPostSummary, BlogTag, Paging, TocLevel } from "./types";
 
 // Reads for the Blog section. Posts are cached under the blog tag; a single post also under seo, since its search
 // listing is edited in Search Listings.
@@ -26,8 +26,53 @@ export async function getPosts(opts: PageOpts & { category?: string; tag?: strin
   return r ? { posts: r.data, paging: paging(r.meta, opts) } : { posts: [], paging: emptyPaging(opts) };
 }
 
-/** One published post with its body and search listing, or null. */
-export const getPost = (slug: string) => bp<BlogPost>(`/blog/posts/${encodeURIComponent(slug)}`, { tags: tagsFor("blog", "seo") });
+/** One published post with its body, FAQs, table of contents levels and search listing, or null. */
+export async function getPost(slug: string): Promise<(BlogPost & { faqs: ArticleFaq[]; tocLevels: TocLevel[] }) | null> {
+  const p = await bp<BlogPost>(`/blog/posts/${encodeURIComponent(slug)}`, { tags: tagsFor("blog", "seo") });
+  // Older Site Manager servers send neither field.
+  return p ? { ...p, faqs: p.faqs ?? [], tocLevels: p.tocLevels ?? [] } : null;
+}
+
+/**
+ * schema.org `FAQPage` structured data for an article's own FAQs, or null when it has none. Use it only on the page
+ * that shows them, and render it with `jsonLdScript`.
+ */
+export function faqPageJsonLd(faqs: Pick<ArticleFaq, "question" | "answerHtml">[] | null | undefined, url?: string | null): Record<string, unknown> | null {
+  if (!faqs?.length) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    ...(url ? { url } : {}),
+    mainEntity: faqs.map((f) => ({ "@type": "Question", name: f.question, acceptedAnswer: { "@type": "Answer", text: f.answerHtml } })),
+  };
+}
+
+export type TocItem = { id: string; text: string; level: 2 | 3 };
+
+const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+const plain = (html: string) =>
+  html
+    .replace(/<[^>]+>/g, "")
+    .replace(/&(#\d+|[a-z]+);/gi, (m, e: string) => (e.startsWith("#") ? String.fromCharCode(Number(e.slice(1))) : (ENTITIES[e.toLowerCase()] ?? m)))
+    .replace(/\s+/g, " ")
+    .trim();
+
+/**
+ * A table of contents from an article's body: its H2 (and H3, when `levels` has it) headings that carry an id, in
+ * order. Site Manager gives every article heading an id, so links like `#costs` work. Empty for `[]`.
+ */
+export function tableOfContents(bodyHtml: string, levels: TocLevel[] | null | undefined): TocItem[] {
+  const want = new Set(levels ?? []);
+  if (!want.size) return [];
+  const out: TocItem[] = [];
+  for (const m of bodyHtml.matchAll(/<h([23])\b([^>]*)>([\s\S]*?)<\/h\1>/gi)) {
+    const level = Number(m[1]) as 2 | 3;
+    const id = m[2].match(/\bid="([^"]+)"/i)?.[1];
+    const text = plain(m[3]);
+    if (id && text && want.has(`h${level}` as TocLevel)) out.push({ id, text, level });
+  }
+  return out;
+}
 
 export const getBlogCategories = async () => (await bp<BlogCategory[]>("/blog/categories", { tags: tagsFor("blog") })) ?? [];
 

package/src/index.ts

@@ -9,7 +9,7 @@
 
 export { bp, bpWithMeta, BlueprintError, siteId, tagsFor } from "./client";
 export * from "./data";
-export { blogPostingJsonLd, buildRss, getBlogCategories, getBlogCategory, getBlogFeed, getBlogTags, getPost, getPosts } from "./blog";
+export { blogPostingJsonLd, buildRss, faqPageJsonLd, getBlogCategories, getBlogCategory, getBlogFeed, getBlogTags, getPost, getPosts, tableOfContents, type TocItem } from "./blog";
 export { buildMetadata, defaultMetadata, pageMetadata, titleWithSuffix, TITLE_CHAR_LIMIT } from "./metadata";
 export { buildSitemap, sitemap } from "./sitemap";
 export { buildRobots, robots } from "./robots";

package/src/types.ts

@@ -498,11 +498,23 @@ export type BlogPostSummary = {
   tags: BlogTerm[];
 };
 
+/** One of an article's own questions and answers. `answerHtml` allows bold, italic and links only. */
+export type ArticleFaq = { question: string; answerHtml: string; answerText: string };
+/** Heading levels an article's table of contents lists; empty for none. */
+export type TocLevel = "h2" | "h3";
+
 export type BlogPost = BlogPostSummary & {
   /** Short takeaways, in order, up to seven. */
   keyPoints: string[];
   bodyHtml: string;
   wordCount: number;
+  /**
+   * The article's own FAQs, in order (Site Manager 2026-11; `getPost` gives `[]` from older servers). Empty when the
+   * site turns article FAQs off. Build FAQPage structured data with `faqPageJsonLd`.
+   */
+  faqs?: ArticleFaq[];
+  /** The headings the site's table of contents lists, by their ids in `bodyHtml` (`getPost` gives `[]` from older servers). */
+  tocLevels?: TocLevel[];
   /** The post's search listing from Site Manager, or null while it has no page. */
   seo: { title: string; description: string | null; canonical: string | null; ogImage: Image | null } | null;
 };

package/src/version.ts

@@ -1 +1 @@
-export const KIT_VERSION = "1.47.0";
+export const KIT_VERSION = "1.48.0";