wiki-formant 0.46.0 → 0.47.0

package/README.md

@@ -431,6 +431,13 @@ The schema.org nodes sit beside it, because they state the same facts to a diffe
 <JsonLd data={articleLd({ headline: title, url, image, published, modified, publisher: { '@id': `${SITE_URL}/#organization` }, citation: citationsFromReferences(refs) })} />
 ```
 
+`questionPairs(html)` reads a page's FAQ out of its own headings: every `h2`/`h3` ending in `?`, answered by the text beneath it. It never rewrites a statement heading as a question, so a page earns `FAQPage` by being written as one. `faqPageLd(pairs, url)` is that node, or null under two pairs, and takes an authored list just as well.
+
+```tsx
+const faq = faqPageLd(questionPairs(html), url);
+{faq && <JsonLd data={faq} />}
+```
+
 `sitePageMetadata({ siteName, handle })` binds the three fields Next drops from every page that sets its own card, with `locale` defaulting to `en_US`. `siteGraphLd` is the Organization, WebSite (with its `SearchAction`) and `WebAPI` as one `@graph` for the root layout, every node carrying an `@id`, and `siteRefs(url)` hands out the same ids for a page's `publisher` and `isPartOf` — so no page writes an inline copy of the publisher that can disagree with the layout's.
 
 ```ts

package/dist/metadata.d.ts

@@ -121,6 +121,27 @@ export declare function collectionLd(o: CollectionLdOptions): LdNode;
  * an authored `&` is not what a crawler reads.
  */
 export declare function citationsFromReferences(items: readonly ReferenceItem[], max?: number): LdNode[];
+export interface QaPair {
+    q: string;
+    a: string;
+}
+/**
+ * The question/answer pairs in a page's HTML: every `h2`/`h3` that ends in a
+ * question mark, with the text up to the next such heading as its answer.
+ *
+ * It never turns a statement heading into a question. Markup that rewrites
+ * "Protocol fees" as "What is Protocol fees?" claims a question the page never
+ * asked, so a page earns an FAQ by being written as one. An answer under 40
+ * characters is a heading with no section, and is skipped.
+ */
+export declare function questionPairs(html: string): QaPair[];
+/**
+ * `FAQPage` over question/answer pairs, or null under two. One question is an
+ * article with a question for a heading, not an FAQ. Pairs come from
+ * `questionPairs` on stored HTML, or from a list the caller authors directly
+ * as plain text, so a home-page FAQ and a wiki article render the same node.
+ */
+export declare function faqPageLd(pairs: readonly QaPair[], url: string): LdNode | null;
 /**
  * Characters a document `<title>` has before a search result truncates it.
  *

package/dist/metadata.js

@@ -19,6 +19,7 @@
 // with no image while their og:image named a card, one listed citations, one
 // collection page had no ItemList at all.
 import { decodeEntities } from './markdown.js';
+import { stripHtml } from './text.js';
 export function pageMetadata(o) {
     const { title, description, url, type = 'website', image, imageSize = { width: 1200, height: 630 }, siteName, locale, handle, markdownTwin, article } = o;
     const images = image ? [{ url: image, ...imageSize, alt: o.imageAlt ?? title }] : undefined;
@@ -107,6 +108,49 @@ export function citationsFromReferences(items, max = 50) {
     })
         .slice(0, max);
 }
+/**
+ * The question/answer pairs in a page's HTML: every `h2`/`h3` that ends in a
+ * question mark, with the text up to the next such heading as its answer.
+ *
+ * It never turns a statement heading into a question. Markup that rewrites
+ * "Protocol fees" as "What is Protocol fees?" claims a question the page never
+ * asked, so a page earns an FAQ by being written as one. An answer under 40
+ * characters is a heading with no section, and is skipped.
+ */
+export function questionPairs(html) {
+    const pairs = [];
+    const sections = html.split(/<h[23][^>]*>/i);
+    for (const section of sections.slice(1)) {
+        const [heading = '', ...rest] = section.split(/<\/h[23]>/i);
+        const q = stripHtml(heading).replace(/\s+/g, ' ');
+        if (!q.endsWith('?'))
+            continue;
+        const a = stripHtml(rest.join('')).replace(/\s+/g, ' ');
+        if (a.length >= 40)
+            pairs.push({ q, a: a.slice(0, 1000) });
+    }
+    return pairs;
+}
+/**
+ * `FAQPage` over question/answer pairs, or null under two. One question is an
+ * article with a question for a heading, not an FAQ. Pairs come from
+ * `questionPairs` on stored HTML, or from a list the caller authors directly
+ * as plain text, so a home-page FAQ and a wiki article render the same node.
+ */
+export function faqPageLd(pairs, url) {
+    if (pairs.length < 2)
+        return null;
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'FAQPage',
+        url,
+        mainEntity: pairs.map(p => ({
+            '@type': 'Question',
+            name: p.q,
+            acceptedAnswer: { '@type': 'Answer', text: p.a },
+        })),
+    };
+}
 /**
  * Characters a document `<title>` has before a search result truncates it.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",