react-cheminfo 0.35.0 → 0.36.0

package/src/seo/core/routeProblems.ts

@@ -0,0 +1,111 @@
+/**
+ * What is wrong with the prose a site is indexed under.
+ *
+ * A route table is the only place a search result is written, and it is written
+ * once and read for years, so the limits that decide whether a result is
+ * readable are checked rather than trusted: a title Google cuts in half, a
+ * description too short to say anything or long enough to be clipped, two pages
+ * sharing a sentence — which is how a site asks to be deduplicated down to one
+ * result — and a snippet promising something the page does not carry.
+ *
+ * The paths are `assertRoutes`' business; this is about the words.
+ */
+
+import type { RouteMeta } from './routes.ts';
+
+/** The longest title that survives a search result whole. */
+const TITLE_LIMIT = 60;
+/** The shortest description that says anything. */
+const DESCRIPTION_MIN = 110;
+/** The longest description a result shows without clipping it. */
+const DESCRIPTION_MAX = 160;
+
+/**
+ * What a site never says about itself, in the words it would say it in. A
+ * snippet naming a repository, a tracker or a licence is both a promise the
+ * page does not keep and a thing we do not publish.
+ */
+const WITHHELD =
+  /\b(?:licence|license|licensing|open[ -]source|repositor(?:y|ies)|issue tracker|source code|report a (?:problem|bug|issue))\b/i;
+
+/**
+ * The phrase in a snippet that names something a site does not publish.
+ *
+ * Shared with the build-time checker, which reads the same sentences back out
+ * of the pages they were written into: one list of words, checked where they
+ * are authored and again where they landed.
+ * @param text - A title or a description.
+ * @returns The phrase, or `undefined` when there is none.
+ */
+export function withheldPhrase(text: string): string | undefined {
+  return WITHHELD.exec(text)?.[0];
+}
+
+/**
+ * Check the table a site is indexed under, before a build reads it.
+ *
+ * Returns the problems rather than throwing, so a site asserts an empty list in
+ * its own test and reads every one of them at once.
+ * @param routes - Every address the site answers.
+ * @returns One line per problem, empty when the table is fit to ship.
+ */
+export function routeProblems(routes: readonly RouteMeta[]): string[] {
+  const problems: string[] = [];
+
+  if (routes.length === 0) {
+    problems.push('the table is empty: a site answers at least one route.');
+    return problems;
+  }
+
+  const titles = new Map<string, string>();
+  const descriptions = new Map<string, string>();
+
+  for (const route of routes) {
+    const at = route.path;
+
+    if (route.title.trim() === '') {
+      problems.push(`${at}: the title is empty.`);
+    } else if (route.title.length > TITLE_LIMIT) {
+      problems.push(
+        `${at}: the title is ${route.title.length} characters, and the site name is appended to it — at most ${TITLE_LIMIT} survives a result whole.`,
+      );
+    }
+
+    const length = route.description.length;
+    if (length < DESCRIPTION_MIN) {
+      problems.push(
+        `${at}: the description is ${length} characters — at least ${DESCRIPTION_MIN}, or the result says half of what the page is.`,
+      );
+    } else if (length > DESCRIPTION_MAX) {
+      problems.push(
+        `${at}: the description is ${length} characters — at most ${DESCRIPTION_MAX}, or the sentence is cut off in the result itself.`,
+      );
+    }
+
+    const titleFirst = titles.get(route.title);
+    if (titleFirst === undefined) {
+      titles.set(route.title, at);
+    } else {
+      problems.push(`${at}: the title repeats the one at ${titleFirst}.`);
+    }
+
+    const descriptionFirst = descriptions.get(route.description);
+    if (descriptionFirst === undefined) {
+      descriptions.set(route.description, at);
+    } else {
+      problems.push(
+        `${at}: the description repeats the one at ${descriptionFirst}.`,
+      );
+    }
+
+    const withheld =
+      withheldPhrase(route.title) ?? withheldPhrase(route.description);
+    if (withheld !== undefined) {
+      problems.push(
+        `${at}: the snippet says "${withheld}" — a site names no repository, tracker or licence of ours.`,
+      );
+    }
+  }
+
+  return problems;
+}

package/src/seo/core/routes.ts

@@ -42,6 +42,20 @@ export interface RouteMeta {
    * @default undefined — the link stands on its own
    */
   note?: string;
+  /**
+   * Whether a search engine is meant to list the page.
+   *
+   * A maintenance screen — a curation queue, an import run, an admin table — is
+   * a real address a signed-in person opens, so it belongs in the table the
+   * router and the tab title read. It is not a result anybody wants: it says
+   * nothing a visitor searched for, and a chemist who lands on it has been sent
+   * to the wrong place. Such a route is left out of the sitemap and the page
+   * answers `noindex`, which is how a page is kept out of the index — never a
+   * `Disallow`, which only stops the crawl and still lets the address be listed
+   * from a link somewhere else.
+   * @default true
+   */
+  indexed?: boolean;
   /**
    * Whether the route also answers every address beneath it, so a section
    * carrying more pages than a table can hold — an entry per structure, per

package/src/seo/core/siteFiles.ts

@@ -50,10 +50,11 @@ export interface SiteFilesOptions {
  */
 export function sitemapXml(options: SiteFilesOptions): string {
   const origin = originOf(options);
-  if (options.routes.length === 0) {
+  if (options.routes.every((route) => route.indexed === false)) {
     throw new Error('a sitemap lists at least one address');
   }
   const entries = options.routes
+    .filter((route) => route.indexed !== false)
     .map(
       (route) =>
         `  <url><loc>${escapeText(`${origin}${route.path}`)}</loc></url>`,

package/src/seo/vite/prerender.ts

@@ -27,6 +27,7 @@ import { trimTrailingSlash } from '../../router/core/address.ts';
 import type { NoscriptText } from '../core/noscript.ts';
 import { noscriptIndex } from '../core/noscript.ts';
 import { pageHeadTags } from '../core/pageMeta.ts';
+import type { PageContent } from '../core/pageProse.ts';
 import type { RobotsDisallow } from '../core/robots.ts';
 import { robotsTxt } from '../core/robots.ts';
 import type { RouteMeta } from '../core/routes.ts';
@@ -91,6 +92,18 @@ export interface PrerenderOptions {
    * @default true
    */
   noscript?: boolean | NoscriptText;
+  /**
+   * What each page says for itself, above the crawl path: its own heading, its
+   * prose and the facts it would show anyway, read from the same data the app
+   * renders from.
+   *
+   * Without it every address ships the same body — the site's menu — and a
+   * search engine handed a hundred identical bodies keeps one of them. It is a
+   * function of the route rather than a field of it, so the prose stays out of
+   * the bundle the browser downloads: only the build ever calls it.
+   * @default undefined — every page carries the menu alone
+   */
+  content?: (route: RouteMeta) => PageContent | undefined;
 }
 
 /**
@@ -104,18 +117,18 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
   const { site, routes, origin, robots = [] } = options;
   assertRoutes(routes);
   const structuredData = structuredDataOf(options);
-  const crawlPath = crawlPathOf(options);
 
   let out = 'dist';
   let serve = false;
   let logger: Logger | null = null;
 
-  const page = (template: string, url: string) => {
+  const page = (template: string, route: RouteMeta) => {
     const head = fill(
       template,
       PAGE_HEAD_MARKER,
-      `${pageHeadTags({ site, routes, origin, url })}${structuredData}`,
+      `${pageHeadTags({ site, routes, origin, url: route.path })}${structuredData}`,
     );
+    const crawlPath = crawlPathOf(options, route);
     return crawlPath === '' ? head : fill(head, PAGE_BODY_MARKER, crawlPath);
   };
 
@@ -132,17 +145,16 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
     // from the home route rather than shipped with its markers showing.
     transformIndexHtml: {
       order: 'post',
-      handler: (html: string) =>
-        serve ? page(html, homeRoute(routes).path) : html,
+      handler: (html: string) => (serve ? page(html, homeRoute(routes)) : html),
     },
 
     closeBundle() {
       if (serve) return;
       const template = readFileSync(join(out, 'index.html'), 'utf8');
 
-      const write = (url: string, file: string) => {
+      const write = (route: RouteMeta, file: string) => {
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, page(template, url));
+        writeFileSync(file, page(template, route));
       };
 
       let root = false;
@@ -150,7 +162,7 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
         const address = trimTrailingSlash(route.path);
         if (address === '/') root = true;
         write(
-          route.path,
+          route,
           address === '/'
             ? join(out, 'index.html')
             : join(out, address.slice(1), 'index.html'),
@@ -159,7 +171,7 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
       // The file a static server hands out for the mount itself. A table naming
       // no root would otherwise leave the template vite built, and ship a site
       // whose front page carries its markers instead of a head.
-      if (!root) write(homeRoute(routes).path, join(out, 'index.html'));
+      if (!root) write(homeRoute(routes), join(out, 'index.html'));
 
       writeFileSync(
         join(out, 'sitemap.xml'),
@@ -196,9 +208,16 @@ function structuredDataOf(options: PrerenderOptions): string {
   })}`;
 }
 
-function crawlPathOf(options: PrerenderOptions): string {
+function crawlPathOf(options: PrerenderOptions, route: RouteMeta): string {
   const { site, routes, origin, noscript = true } = options;
   if (noscript === false) return '';
+  const content = options.content?.(route);
   const { routes: listed, ...prose } = noscript === true ? {} : noscript;
-  return noscriptIndex({ site, origin, ...prose, routes: listed ?? routes });
+  return noscriptIndex({
+    site,
+    origin,
+    ...prose,
+    routes: listed ?? routes,
+    content,
+  });
 }