react-cheminfo 0.35.0 → 0.36.0

package/bin/check-seo.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/*
+ * Report every page of a build a search engine cannot tell apart from the rest
+ * of the site: a missing or repeated title, a description outside the room a
+ * result gives it, an absent canonical, card or crawl path, a sitemap naming a
+ * page the build never wrote, and a social card pointing at a file that is not
+ * there.
+ *
+ * It reads the build rather than the route table, because the defects that
+ * actually cost us ranking were never in the prose — they were a site whose
+ * head injector was never wired, which writes one generic page for every
+ * address and looks entirely correct in the source. `routeProblems` from
+ * `react-cheminfo/core` checks the prose; this checks that it arrived.
+ *
+ * Wire it as an npm script, after the build:
+ *   "check-seo": "node node_modules/react-cheminfo/bin/check-seo.mjs dist"
+ *
+ * Usage: check-seo.mjs [directory] [--quiet]
+ *   directory   the build output, `dist` when none is given
+ *   --quiet     say nothing when the build is clean
+ *
+ * A page carrying `<!--cheminfo:head-->` has its head written per request by a
+ * server, so its own tags are that server's business and are reported as
+ * deferred rather than missing. Everything the build still owns is checked.
+ *
+ * Exits 1 when anything is reported, 2 when it was called wrongly, 0 otherwise.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import process from 'node:process';
+
+import { PAGE_HEAD_MARKER, withheldPhrase } from '../lib/core.js';
+
+import { countOf, usageError } from './cli.mjs';
+
+const TOOL = 'check-seo';
+const SKIPPED = new Set(['assets', 'node_modules']);
+const DESCRIPTION_MIN = 110;
+const DESCRIPTION_MAX = 160;
+
+const roots = [];
+let quiet = false;
+
+for (const argument of process.argv.slice(2)) {
+  if (argument === '--quiet') {
+    quiet = true;
+  } else if (argument.startsWith('-')) {
+    process.exit(usageError(TOOL, `unknown option: ${argument}`));
+  } else {
+    roots.push(argument);
+  }
+}
+const root = roots[0] ?? 'dist';
+if (roots.length > 1) {
+  process.exit(usageError(TOOL, 'one directory at a time'));
+}
+
+const stats = statSync(root, { throwIfNoEntry: false });
+if (stats === undefined || !stats.isDirectory()) {
+  process.exit(usageError(TOOL, `no such build directory: ${root}`));
+}
+
+const pages = [];
+collect(root, pages);
+if (pages.length === 0) {
+  process.exit(usageError(TOOL, `no index.html under ${root}`));
+}
+
+const problems = [];
+const deferred = [];
+const excluded = [];
+const titles = new Map();
+const descriptions = new Map();
+
+for (const page of pages) {
+  const html = readFileSync(page.file, 'utf8');
+  const at = page.address;
+
+  // A page that takes itself out of the index has nothing to be indexed under,
+  // and an admin site is right to do it. Saying its head is wrong would be
+  // reporting a decision as a defect.
+  if (/<meta\s+name="robots"\s+content="[^"]*noindex/i.test(html)) {
+    excluded.push(at);
+    continue;
+  }
+
+  if (html.includes(PAGE_HEAD_MARKER)) {
+    deferred.push(at);
+    continue;
+  }
+  checkHead(at, html);
+
+  if (!/<html[^>]*\slang="[^"]+"/i.test(html)) {
+    problems.push(`${at}: no lang on <html>.`);
+  }
+  if (!html.includes('application/ld+json')) {
+    problems.push(`${at}: no structured-data block.`);
+  }
+  if (!/<noscript[\s>]/i.test(html)) {
+    problems.push(
+      `${at}: no <noscript> crawl path — a crawler that does not render sees an empty page.`,
+    );
+  }
+  const keywords = tag(html, /<meta\s+name="keywords"\s+content="([^"]*)"/i);
+  if (keywords !== undefined) {
+    problems.push(
+      `${at}: a keywords meta tag — no search engine has read one since 2009.`,
+    );
+  }
+}
+
+// A build whose every page defers its head is the shell of a site a server
+// writes the head of: the sitemap it serves names addresses this build was
+// never going to write, and the card, the structured data and the crawl path
+// arrive with the page rather than with the file. There is nothing here to
+// check, and checking it anyway would report a correct site as broken — that
+// server's own route tests are what covers it.
+const served = deferred.length + excluded.length === pages.length;
+if (!served) checkSiteFiles();
+
+let report = '';
+for (const problem of problems) report += `${problem}\n`;
+
+if (problems.length > 0) {
+  report += `${countOf(problems.length, 'problem')} in ${countOf(pages.length, 'page')}\n`;
+  process.stdout.write(report);
+  process.exit(1);
+}
+if (!quiet) {
+  if (served && deferred.length === 0) {
+    process.stdout.write(
+      `${countOf(pages.length, 'page')} answering noindex: deliberately out of the index\n`,
+    );
+  } else if (served) {
+    process.stdout.write(
+      `${countOf(pages.length, 'page')} writing its head per request: covered by the server's own route tests, not here\n`,
+    );
+  } else {
+    const note =
+      deferred.length === 0
+        ? ''
+        : `, ${countOf(deferred.length, 'page')} writing its head per request`;
+    process.stdout.write(
+      `no indexing problem in ${countOf(pages.length, 'page')}${note}\n`,
+    );
+  }
+}
+
+/**
+ * Check the tags a result, a card and a canonical are built from.
+ * @param {string} at - The address the page was written at.
+ * @param {string} html - The page.
+ */
+function checkHead(at, html) {
+  const title = tag(html, /<title>([\s\S]*?)<\/title>/i);
+  if (title === undefined || title.trim() === '') {
+    problems.push(`${at}: no title.`);
+  } else {
+    const first = titles.get(title);
+    if (first === undefined) titles.set(title, at);
+    else problems.push(`${at}: the title repeats the one at ${first}.`);
+  }
+
+  const description = tag(
+    html,
+    /<meta\s+name="description"\s+content="([^"]*)"/i,
+  );
+  if (description === undefined || description === '') {
+    problems.push(`${at}: no description.`);
+  } else {
+    if (description.length < DESCRIPTION_MIN) {
+      problems.push(
+        `${at}: the description is ${description.length} characters — at least ${DESCRIPTION_MIN}.`,
+      );
+    }
+    if (description.length > DESCRIPTION_MAX) {
+      problems.push(
+        `${at}: the description is ${description.length} characters — at most ${DESCRIPTION_MAX}.`,
+      );
+    }
+    const first = descriptions.get(description);
+    if (first === undefined) descriptions.set(description, at);
+    else problems.push(`${at}: the description repeats the one at ${first}.`);
+  }
+
+  const withheld =
+    withheldPhrase(title ?? '') ?? withheldPhrase(description ?? '');
+  if (withheld !== undefined) {
+    problems.push(
+      `${at}: the snippet says "${withheld}" — a site names no repository, tracker or licence of ours.`,
+    );
+  }
+
+  const canonical = tag(html, /<link\s+rel="canonical"\s+href="([^"]*)"/i);
+  if (canonical === undefined) {
+    problems.push(`${at}: no canonical address.`);
+  } else if (canonical.includes('?')) {
+    problems.push(`${at}: the canonical carries a query string.`);
+  }
+
+  for (const property of ['og:title', 'og:description', 'og:url']) {
+    const pattern = new RegExp(
+      String.raw`<meta\s+property="${property}"\s+content="[^"]`,
+      'i',
+    );
+    if (!pattern.test(html)) problems.push(`${at}: no ${property}.`);
+  }
+  if (!/<meta\s+name="twitter:card"/i.test(html)) {
+    problems.push(`${at}: no twitter:card, so a shared link unfurls bare.`);
+  }
+
+  const image = tag(html, /<meta\s+property="og:image"\s+content="([^"]*)"/i);
+  if (image === undefined) {
+    problems.push(`${at}: no og:image.`);
+  } else {
+    const own = ownPath(image);
+    if (own !== undefined && !exists(join(root, own))) {
+      problems.push(
+        `${at}: og:image names ${own}, which the build never wrote.`,
+      );
+    }
+  }
+}
+
+/** Check the two files a crawler asks for before it reads any page. */
+function checkSiteFiles() {
+  const robots = join(root, 'robots.txt');
+  const sitemap = join(root, 'sitemap.xml');
+
+  if (!exists(robots)) {
+    problems.push('robots.txt: not in the build.');
+  } else {
+    const named = /^\s*Sitemap:\s*(\S+)\s*$/im.exec(
+      readFileSync(robots, 'utf8'),
+    );
+    if (named !== null && !exists(sitemap)) {
+      problems.push(
+        `robots.txt names ${named[1]}, which the build never wrote — a sitemap that answers 404 is reported on every fetch.`,
+      );
+    }
+  }
+
+  if (!exists(sitemap)) {
+    problems.push('sitemap.xml: not in the build.');
+    return;
+  }
+  const xml = readFileSync(sitemap, 'utf8');
+  const written = new Set(pages.map((page) => page.address));
+  const claimed = new Set();
+  let listed = 0;
+  for (const match of xml.matchAll(/<loc>([^<]+)<\/loc>/g)) {
+    listed++;
+    const own = ownPath(match[1] ?? '');
+    if (own !== undefined) claimed.add(own === '' ? '/' : own);
+    if (own !== undefined && !written.has(own === '' ? '/' : own)) {
+      problems.push(
+        `sitemap.xml lists ${match[1]}, which the build never wrote.`,
+      );
+    }
+  }
+  if (listed === 0) problems.push('sitemap.xml lists no address.');
+
+  // The other direction, which is the one that quietly costs traffic: a page
+  // the build wrote and the sitemap never named is a page nothing links a
+  // crawler to but the crawl path, and it is the long tail — an element, a
+  // space group, an exercise — that goes missing first.
+  for (const page of pages) {
+    if (deferred.includes(page.address) || excluded.includes(page.address)) {
+      continue;
+    }
+    if (!claimed.has(page.address)) {
+      problems.push(
+        `${page.address}: written by the build and named in no sitemap entry.`,
+      );
+    }
+  }
+}
+
+/**
+ * The part of an address this build is answerable for.
+ * @param {string} target - An absolute address, or a path.
+ * @returns {string | undefined} Its path, or `undefined` when it is somebody
+ * else's host.
+ */
+function ownPath(target) {
+  if (!URL.canParse(target)) {
+    return target.startsWith('/') ? trimSlash(target) : undefined;
+  }
+  return trimSlash(new URL(target).pathname);
+}
+
+/**
+ * @param {string} path - A path.
+ * @returns {string} The same path without its trailing slash, `/` kept.
+ */
+function trimSlash(path) {
+  return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
+/**
+ * @param {string} html - The page.
+ * @param {RegExp} pattern - A pattern whose first group is the value.
+ * @returns {string | undefined} The value, or `undefined` when it is absent.
+ */
+function tag(html, pattern) {
+  return pattern.exec(html)?.[1];
+}
+
+/**
+ * @param {string} path - A path.
+ * @returns {boolean} Whether anything is there.
+ */
+function exists(path) {
+  return statSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+
+/**
+ * Add every built page under a path to the list, with the address it answers.
+ * @param {string} path - A directory of the build.
+ * @param {Array<{ file: string, address: string }>} pages - Collected so far.
+ */
+function collect(path, pages) {
+  for (const entry of readdirSync(path, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || SKIPPED.has(entry.name)) continue;
+    const next = join(path, entry.name);
+    if (entry.isDirectory()) {
+      collect(next, pages);
+    } else if (entry.name === 'index.html') {
+      const address = `/${relative(root, next).replace(/index\.html$/, '')}`;
+      pages.push({ file: next, address: trimSlash(address) });
+    }
+  }
+}

package/lib/language/core/index.d.ts

@@ -1,3 +1,5 @@
 export { languageName } from './languageName.ts';
+export type { LanguagePath } from './languagePath.ts';
+export { readLanguagePath, withLanguagePath } from './languagePath.ts';
 export { LANGUAGE_PARAM, isLanguageTag, readLanguageParam, withLanguageParam, } from './languageParam.ts';
 //# sourceMappingURL=index.d.ts.map

package/lib/language/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/language/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/language/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/lib/language/core/index.js

@@ -1,3 +1,4 @@
 export { languageName } from "./languageName.js";
+export { readLanguagePath, withLanguagePath } from "./languagePath.js";
 export { LANGUAGE_PARAM, isLanguageTag, readLanguageParam, withLanguageParam, } from "./languageParam.js";
 //# sourceMappingURL=index.js.map

package/lib/language/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/language/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/language/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC"}

package/lib/language/core/languagePath.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The language a translated site routes by: a prefix on its own addresses.
+ *
+ * `/fr/tutorial` is the French tutorial, and English is written with no prefix
+ * at all, so every link already handed out in a course stays alive and the site
+ * does not acquire a second spelling of its own front page.
+ *
+ * This is the half of the design that makes a translation *findable*. A site
+ * that keeps its language in a query parameter, in the hash or in
+ * `localStorage` serves five languages at one address: a crawler sees one page,
+ * indexes one language, and the other four may as well not have been written.
+ * The parameter stays — it is how the language travels to a sibling that may
+ * not speak it (`./languageParam.ts`) — but it is not how a translated site
+ * routes.
+ *
+ * The prefix sits between the mount and the route, so a tool served as one of
+ * several on a shared host reads `/surge/fr/exercises`: the mount comes off
+ * first (`router/core/basePath.ts`), then the language, then the table is read.
+ */
+import type { Language } from '../../i18n/core/languages.ts';
+/** An address split into the language it names and the page it opens. */
+export interface LanguagePath {
+    /** The language named, or the default one when the address names none. */
+    language: Language;
+    /** The address from the site's own root, with the prefix taken off. */
+    path: string;
+}
+/**
+ * Read the language prefix off one of the site's own addresses.
+ *
+ * Only a language the site actually speaks is read as a prefix: on a site with
+ * no Italian, `/it` is whatever page is called `it`, not an empty Italian front
+ * page. So the list is the site's, never the family's.
+ * @param path - An address from the site's own root, the mount already off,
+ * e.g. `/fr/tutorial`.
+ * @param languages - The languages this site is written in, the default one
+ * included.
+ * @returns The language it names and the page it opens.
+ */
+export declare function readLanguagePath(path: string, languages: readonly Language[]): LanguagePath;
+/**
+ * Write one of the site's own addresses in a language.
+ *
+ * The default language is written with no prefix: an address naming no language
+ * is English, which is what keeps every link handed out before the site was
+ * translated pointing at the same page.
+ * @param language - The language to write it in.
+ * @param path - The address from the site's own root, e.g. `/tutorial`.
+ * @returns The address under that language, e.g. `/fr/tutorial`.
+ */
+export declare function withLanguagePath(language: Language, path: string): string;
+//# sourceMappingURL=languagePath.d.ts.map

package/lib/language/core/languagePath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languagePath.d.ts","sourceRoot":"","sources":["../../../src/language/core/languagePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAI7D,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,EAAE,QAAQ,CAAC;IACnB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC7B,YAAY,CAcd;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIzE"}

package/lib/language/core/languagePath.js

@@ -0,0 +1,65 @@
+/**
+ * The language a translated site routes by: a prefix on its own addresses.
+ *
+ * `/fr/tutorial` is the French tutorial, and English is written with no prefix
+ * at all, so every link already handed out in a course stays alive and the site
+ * does not acquire a second spelling of its own front page.
+ *
+ * This is the half of the design that makes a translation *findable*. A site
+ * that keeps its language in a query parameter, in the hash or in
+ * `localStorage` serves five languages at one address: a crawler sees one page,
+ * indexes one language, and the other four may as well not have been written.
+ * The parameter stays — it is how the language travels to a sibling that may
+ * not speak it (`./languageParam.ts`) — but it is not how a translated site
+ * routes.
+ *
+ * The prefix sits between the mount and the route, so a tool served as one of
+ * several on a shared host reads `/surge/fr/exercises`: the mount comes off
+ * first (`router/core/basePath.ts`), then the language, then the table is read.
+ */
+import { DEFAULT_LANGUAGE } from "../../i18n/core/languages.js";
+import { trimTrailingSlash } from "../../router/core/address.js";
+/**
+ * Read the language prefix off one of the site's own addresses.
+ *
+ * Only a language the site actually speaks is read as a prefix: on a site with
+ * no Italian, `/it` is whatever page is called `it`, not an empty Italian front
+ * page. So the list is the site's, never the family's.
+ * @param path - An address from the site's own root, the mount already off,
+ * e.g. `/fr/tutorial`.
+ * @param languages - The languages this site is written in, the default one
+ * included.
+ * @returns The language it names and the page it opens.
+ */
+export function readLanguagePath(path, languages) {
+    const opened = path.startsWith('/') ? path : `/${path}`;
+    const cut = opened.indexOf('/', 1);
+    const first = cut === -1 ? opened.slice(1) : opened.slice(1, cut);
+    for (const language of languages) {
+        if (language === DEFAULT_LANGUAGE || language !== first)
+            continue;
+        const rest = cut === -1 ? '/' : opened.slice(cut);
+        return { language, path: trimTrailingSlash(rest) || '/' };
+    }
+    return {
+        language: DEFAULT_LANGUAGE,
+        path: trimTrailingSlash(opened) || '/',
+    };
+}
+/**
+ * Write one of the site's own addresses in a language.
+ *
+ * The default language is written with no prefix: an address naming no language
+ * is English, which is what keeps every link handed out before the site was
+ * translated pointing at the same page.
+ * @param language - The language to write it in.
+ * @param path - The address from the site's own root, e.g. `/tutorial`.
+ * @returns The address under that language, e.g. `/fr/tutorial`.
+ */
+export function withLanguagePath(language, path) {
+    const opened = path.startsWith('/') ? path : `/${path}`;
+    if (language === DEFAULT_LANGUAGE)
+        return opened;
+    return opened === '/' ? `/${language}` : `/${language}${opened}`;
+}
+//# sourceMappingURL=languagePath.js.map

package/lib/language/core/languagePath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"languagePath.js","sourceRoot":"","sources":["../../../src/language/core/languagePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAUjE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,SAA8B;IAE9B,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IACxD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAElE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,QAAQ,KAAK,gBAAgB,IAAI,QAAQ,KAAK,KAAK;YAAE,SAAS;QAClE,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,gBAAgB;QAC1B,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,IAAI,GAAG;KACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAkB,EAAE,IAAY;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IACxD,IAAI,QAAQ,KAAK,gBAAgB;QAAE,OAAO,MAAM,CAAC;IACjD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,MAAM,EAAE,CAAC;AACnE,CAAC"}

package/lib/seo/core/alternates.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The tags that tell a search engine five addresses are one page written five
+ * times.
+ *
+ * Without them a translated site is read as five sites that happen to look
+ * alike: the French tutorial competes with the English one instead of being
+ * offered to a French reader, and a search engine picks one of them to keep.
+ * With them each address is served to the audience it was written for, and the
+ * four it was not stop diluting it.
+ *
+ * Every page names **every** language including itself — a set that does not
+ * list the page it is on is ignored whole — plus `x-default`, which is where a
+ * reader whose language we do not speak is sent.
+ */
+import type { Language } from '../../i18n/core/languages.ts';
+/** Which page, in which languages, served from where. */
+export interface AlternateOptions {
+    /**
+     * Where the site is served, mount path included and no trailing slash, e.g.
+     * `https://3d.cheminfo.org`.
+     */
+    origin: string;
+    /**
+     * The page, from the site's own root and with no language prefix on it, e.g.
+     * `/tutorial`.
+     */
+    path: string;
+    /**
+     * Every language the site is written in. One language alone means there is
+     * nothing to point at, and no tag is written.
+     */
+    languages: readonly Language[];
+}
+/**
+ * The `rel="alternate"` block for one page of a translated site.
+ * @param options - The page, its languages and where the site is served.
+ * @returns The tags, one per line, or `''` when the site speaks one language.
+ */
+export declare function alternateLinkTags(options: AlternateOptions): string;
+//# sourceMappingURL=alternates.d.ts.map

package/lib/seo/core/alternates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alternates.d.ts","sourceRoot":"","sources":["../../../src/seo/core/alternates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAK7D,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAYnE"}

package/lib/seo/core/alternates.js

@@ -0,0 +1,42 @@
+/**
+ * The tags that tell a search engine five addresses are one page written five
+ * times.
+ *
+ * Without them a translated site is read as five sites that happen to look
+ * alike: the French tutorial competes with the English one instead of being
+ * offered to a French reader, and a search engine picks one of them to keep.
+ * With them each address is served to the audience it was written for, and the
+ * four it was not stop diluting it.
+ *
+ * Every page names **every** language including itself — a set that does not
+ * list the page it is on is ignored whole — plus `x-default`, which is where a
+ * reader whose language we do not speak is sent.
+ */
+import { DEFAULT_LANGUAGE } from "../../i18n/core/languages.js";
+import { withLanguagePath } from "../../language/core/languagePath.js";
+import { escapeAttribute } from "../../share/core/escape.js";
+/**
+ * The `rel="alternate"` block for one page of a translated site.
+ * @param options - The page, its languages and where the site is served.
+ * @returns The tags, one per line, or `''` when the site speaks one language.
+ */
+export function alternateLinkTags(options) {
+    const { origin, path, languages } = options;
+    if (languages.length < 2)
+        return '';
+    const tags = [];
+    for (const language of languages) {
+        tags.push(linkTag(language, address(origin, language, path)));
+    }
+    // A reader we have no language for gets the unprefixed address, which is the
+    // one every link handed out before the site was translated already points at.
+    tags.push(linkTag('x-default', address(origin, DEFAULT_LANGUAGE, path)));
+    return tags.join('\n');
+}
+function address(origin, language, path) {
+    return `${origin}${withLanguagePath(language, path)}`;
+}
+function linkTag(hreflang, href) {
+    return `<link rel="alternate" hreflang="${escapeAttribute(hreflang)}" href="${escapeAttribute(href)}" />`;
+}
+//# sourceMappingURL=alternates.js.map

package/lib/seo/core/alternates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alternates.js","sourceRoot":"","sources":["../../../src/seo/core/alternates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAqB7D;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAyB;IACzD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAC5C,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,6EAA6E;IAC7E,8EAA8E;IAC9E,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,OAAO,CAAC,MAAc,EAAE,QAAkB,EAAE,IAAY;IAC/D,OAAO,GAAG,MAAM,GAAG,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,OAAO,CAAC,QAAgB,EAAE,IAAY;IAC7C,OAAO,mCAAmC,eAAe,CAAC,QAAQ,CAAC,WAAW,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC;AAC5G,CAAC"}

package/lib/seo/core/index.d.ts

@@ -4,10 +4,13 @@ export type { NoscriptEcosystem, NoscriptHrefs, NoscriptOptions, NoscriptRoute,
 export { noscriptIndex } from './noscript.ts';
 export type { PageMetaOptions } from './pageMeta.ts';
 export { injectPageMeta, pageDocumentMeta, pageHeadTags } from './pageMeta.ts';
+export type { PageContent, PageSection, PageTable } from './pageProse.ts';
+export { pageProseHtml } from './pageProse.ts';
 export type { PlainDescriptionOptions } from './plainDescription.ts';
 export { plainDescription, plainProse } from './plainDescription.ts';
 export type { RobotsDisallow } from './robots.ts';
 export { robotsTxt } from './robots.ts';
+export { routeProblems, withheldPhrase } from './routeProblems.ts';
 export type { RouteMeta } from './routes.ts';
 export { assertRoutes, homeRoute, pageMetaFor, routeFor } from './routes.ts';
 export type { SiteFilesOptions } from './siteFiles.ts';

package/lib/seo/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/seo/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/seo/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/lib/seo/core/index.js

@@ -1,8 +1,10 @@
 export { writeDocumentMeta } from "./documentMeta.js";
 export { noscriptIndex } from "./noscript.js";
 export { injectPageMeta, pageDocumentMeta, pageHeadTags } from "./pageMeta.js";
+export { pageProseHtml } from "./pageProse.js";
 export { plainDescription, plainProse } from "./plainDescription.js";
 export { robotsTxt } from "./robots.js";
+export { routeProblems, withheldPhrase } from "./routeProblems.js";
 export { assertRoutes, homeRoute, pageMetaFor, routeFor } from "./routes.js";
 export { sitemapXml } from "./siteFiles.js";
 export { startDocumentMeta } from "./startDocumentMeta.js";

package/lib/seo/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/seo/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAQtD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/seo/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAQtD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/lib/seo/core/noscript.d.ts

@@ -6,6 +6,7 @@
  * the tool needs JavaScript, and links the addresses it answers.
  */
 import type { SiteId } from '../../ecosystem/core/sites.ts';
+import type { PageContent } from './pageProse.ts';
 import type { RouteMeta } from './routes.ts';
 import type { SiteFilesOptions } from './siteFiles.ts';
 /** How the addresses of the site's own pages are written. */
@@ -80,6 +81,14 @@ export interface NoscriptText {
 export interface NoscriptOptions extends Omit<SiteFilesOptions, 'routes'>, Omit<NoscriptText, 'routes'> {
     /** The addresses it links, each with the label it is linked under. */
     routes: readonly NoscriptRoute[];
+    /**
+     * What the page being written says, above the crawl path. The block is the
+     * only text a crawler is handed before anything runs, so a page with nothing
+     * of its own here is indexed on its title and on this site's menu — which
+     * every other page of the site carries too.
+     * @default undefined — the block is the menu alone
+     */
+    content?: PageContent;
 }
 /**
  * The `noscript` block, ready to put in the body.

package/lib/seo/core/noscript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"noscript.d.ts","sourceRoot":"","sources":["../../../src/seo/core/noscript.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAiB,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAK3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD,6DAA6D;AAC7D,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACrC;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACxC;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACnC;AAED,yDAAyD;AACzD,MAAM,WAAW,eACf,SAAQ,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC;IACtE,sEAAsE;IACtE,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAc9D"}
+{"version":3,"file":"noscript.d.ts","sourceRoot":"","sources":["../../../src/seo/core/noscript.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAiB,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAK3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD,6DAA6D;AAC7D,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACrC;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACxC;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACnC;AAED,yDAAyD;AACzD,MAAM,WAAW,eACf,SAAQ,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC;IACtE,sEAAsE;IACtE,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAoB9D"}