ferst-core 0.9.2 → 0.9.3

package/content/schemas.ts

@@ -36,7 +36,8 @@ const siteIdentitySchema = z
     /** Town / city — appended to the brand in alt text. */
     location: z.string().default(''),
     /** What the site is for, which types its structured data for search engines
-     *  (lib/structured-data.mjs): Church, School, NGO, LocalBusiness or Organization. */
+     *  (lib/structured-data.mjs): School, NGO, LocalBusiness or Organization. A church is an
+     *  Organization (the parish), its churches its places. */
     kind: z.enum(['church', 'school', 'charity', 'business', 'organisation']).default('organisation'),
   })
   .default({});

package/integration.mjs

@@ -35,16 +35,28 @@
  *   `public/` win.
  * @param {boolean} [options.seo=true] Search signals (lib/seo.mjs): `/robots.txt`, and once
  *   `ferst-site.json` has a `siteUrl`, `/sitemap.xml`, a canonical address on every page,
- *   structured data and link previews, and (with the blog) `/posts/rss.xml`.
+ *   structured data and link previews, and (with the blog) `/posts/rss.xml`. Every build's
+ *   internal links to a page point at its own address (`/about-us/`), not at a redirect.
  *   A test copy (any branch but the production one) is marked noindex on every file. A
  *   site's own `public/robots.txt` or `public/sitemap.xml` wins.
  * @returns {import('astro').AstroIntegration}
  */
 import { copyFileSync, createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { deploymentBranch } from './bin/cms-config.mjs';
-import { seoContext, withNoindexHeader } from './lib/seo.mjs';
+import { linksToPageAddresses, seoContext, withNoindexHeader } from './lib/seo.mjs';
 import { writeSiteIcons } from './lib/site-icon.mjs';
 
+/** Every page of a build (its .html files, at any depth), as file URLs. */
+function htmlFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+    entry.isDirectory()
+      ? htmlFiles(new URL(`${encodeURIComponent(entry.name)}/`, dir))
+      : entry.name.endsWith('.html')
+        ? [new URL(encodeURIComponent(entry.name), dir)]
+        : [],
+  );
+}
+
 /** The self-hosted fonts the engine's CSS requests (/fonts/*.woff2), shipped in the package. */
 const FONTS_DIR = new URL('./fonts/', import.meta.url);
 const FONT_URL = /^\/fonts\/([a-z0-9-]+\.woff2)(?:\?.*)?$/;
@@ -197,6 +209,21 @@ export default function ferst(options = {}) {
       'astro:server:setup': fonts['astro:server:setup'],
       'astro:build:done': async (ctx) => {
         await fonts['astro:build:done'](ctx);
+        // Internal links point at each page's one address, never at a redirect (lib/seo.mjs).
+        if (seo) {
+          const isPage = (path) => {
+            try {
+              return existsSync(new URL(`.${path}index.html`, ctx.dir));
+            } catch {
+              return false;
+            }
+          };
+          for (const file of htmlFiles(ctx.dir)) {
+            const html = readFileSync(file, 'utf8');
+            const linked = linksToPageAddresses(html, isPage);
+            if (linked !== html) writeFileSync(file, linked);
+          }
+        }
         // A test copy is noindex on every file: pages, and the PDFs and images beside them.
         if (search && !search.production) {
           const file = new URL('_headers', ctx.dir);

package/layouts/Base.astro

@@ -32,6 +32,7 @@ import { getCalloutSettings } from '../lib/callout';
 import { buildThemeStyle } from '../lib/themeTokens';
 import { canonicalUrl, previewTags } from '../lib/seo.mjs';
 import { structuredData } from '../lib/structured-data.mjs';
+import { titlesAbove } from '../lib/pages';
 
 interface Props {
   title: string;
@@ -101,9 +102,13 @@ const canonical = siteUrl && indexable ? canonicalUrl(siteUrl, path) : null;
 const noindex = !indexable || import.meta.env.FERST_SEO_PRODUCTION === false;
 
 // What the page tells search engines and link previews about the site (lib/structured-data,
-// lib/seo): from the site's own details, the same facts it shows visitors.
+// lib/seo): from the site's own details, the same facts it shows visitors. A nested page also
+// carries its breadcrumb trail, from the titles of the pages above it.
+const nested = path.split('/').filter(Boolean).length >= 2;
+const breadcrumbs = indexable && siteUrl && nested ? await titlesAbove(path) : {};
 const ld = indexable
   ? structuredData({
+      breadcrumbs,
       siteUrl: siteUrl || null,
       path,
       identity,

package/lib/pages.ts

@@ -22,6 +22,24 @@
  * can still hand-build a one-off page beside the JSON-driven ones.
  */
 import { getCollection } from 'astro:content';
+import { getPostsSettings } from './posts';
+
+/**
+ * The titles of the pages above a nested address, for its breadcrumb trail
+ * (lib/structured-data): each address above it that is a page of its own, and the news page
+ * above a post. Keyed by address (`/about-us/`).
+ */
+export async function titlesAbove(path: string): Promise<Record<string, string>> {
+  const segments = path.split('/').filter(Boolean);
+  const above = new Set(segments.slice(0, -1).map((_, i) => segments.slice(0, i + 1).join('/')));
+  const titles: Record<string, string> = {};
+  if (!above.size) return titles;
+  for (const entry of await getPageEntries()) {
+    if (above.has(entry.id) && entry.data.title) titles[`/${entry.id}/`] = entry.data.title;
+  }
+  if (above.has('posts') && !titles['/posts/']) titles['/posts/'] = (await getPostsSettings()).title;
+  return titles;
+}
 
 /** All non-draft `pages` entries. */
 export async function getPageEntries() {

package/lib/seo.mjs

@@ -129,6 +129,22 @@ export function withNoindexHeader(existing) {
   return `${current.replace(/\s*$/, '')}\n\n${NOINDEX_RULE}`;
 }
 
+/**
+ * Internal links pointed at each page's one address. A page's address is its trailing-slash
+ * form (`/about-us/`), and Cloudflare Pages answers the slash-less form with a redirect: a link
+ * to `/about-us` costs every visit and crawl a hop, and search engines list the slash-less form
+ * as a page with a redirect. So `href="/about-us"` gains its slash, keeping any `?query` or
+ * `#section`, when `isPage('/about-us/')` says that page exists. Files, other sites and
+ * addresses that are already right are left alone.
+ * @param {string} html
+ * @param {(path: string) => boolean} isPage  whether `/x/` is a page of the site
+ */
+export function linksToPageAddresses(html, isPage) {
+  return String(html).replace(/(\shref=")(\/(?!\/)[^"?#]*[^"/?#])([?#][^"]*)?"/g, (match, attr, path, rest = '') =>
+    isPage(`${path}/`) ? `${attr}${path}/${rest}"` : match,
+  );
+}
+
 /**
  * Link-preview tags (Open Graph and Twitter card) for one page: what a link shared on
  * Facebook, WhatsApp or LinkedIn shows. The picture is the page's own (its hero), else the

package/lib/structured-data.mjs

@@ -4,17 +4,18 @@
  * same facts the site shows visitors. Base renders it in each page's head once the site has
  * an address (its links must be absolute). Pure, so it's unit-testable.
  *
- * - The site is one entity (`#organization`), typed by its kind: a church with one place is
- *   a `Church` at that address; with several places (a parish of several churches) it's an
- *   `Organization` with each church as a `location`.
+ * - The site is one entity (`#organization`), typed by its kind. A church site is the parish,
+ *   an `Organization` with each of its churches as a `location` (schema.org's `Church` is a
+ *   building, and a building can't publish the website or write its posts); with one church,
+ *   the parish is at that church's address. Other kinds list several places as `location`s.
  * - The website names that entity as its publisher.
  * - A post is an `Article`, dated, published by the site.
  */
 import { canonicalUrl } from './seo.mjs';
 
-/** The schema.org type for each kind of site (`identity.kind`). */
-const TYPE = { church: 'Church', school: 'School', charity: 'NGO', business: 'LocalBusiness', organisation: 'Organization' };
-/** The type of each of a site's places, when it has several. */
+/** The schema.org type for each kind of site (`identity.kind`). A church site is an `Organization`. */
+const TYPE = { school: 'School', charity: 'NGO', business: 'LocalBusiness', organisation: 'Organization' };
+/** The type of each of a site's places, when it lists them. */
 const PLACE_TYPE = { church: 'Church', school: 'School', business: 'LocalBusiness' };
 
 /** Drop empty values (undefined, '', empty arrays and objects) so the data says only what's known. */
@@ -36,22 +37,45 @@ const isoDate = (d) => {
   return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
 };
 
+/**
+ * The trail to a nested page (the site › each page above it › the page), or undefined for a
+ * top-level page. `titles` maps each address above the page to its page title; an address
+ * that isn't a page of its own is left out, and a trail with nothing between the site and
+ * the page isn't worth showing.
+ */
+function breadcrumbList(site, path, title, siteName, titles) {
+  const segments = String(path).split('/').filter(Boolean);
+  if (segments.length < 2 || !title) return undefined;
+  const items = [{ name: siteName, item: `${site}/` }];
+  for (let i = 1; i < segments.length; i++) {
+    const above = `/${segments.slice(0, i).join('/')}/`;
+    if (titles[above]) items.push({ name: titles[above], item: canonicalUrl(site, above) });
+  }
+  if (items.length < 2) return undefined;
+  items.push({ name: title, item: canonicalUrl(site, path) });
+  return {
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((it, i) => ({ '@type': 'ListItem', position: i + 1, name: it.name, item: it.item })),
+  };
+}
+
 /**
  * The JSON-LD for one page, or null when the site has no address.
  * @param {{ siteUrl: string | null, path: string, identity: any, contact: any, places?: any[], logo?: string,
- *   title?: string, description?: string, article?: { date: Date | string, image?: string } }} p
+ *   title?: string, description?: string, article?: { date: Date | string, image?: string },
+ *   breadcrumbs?: Record<string, string> }} p  `breadcrumbs`: the titles of the pages above this one.
  */
-export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article }) {
+export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article, breadcrumbs = {} }) {
   if (!siteUrl) return null;
   const site = siteUrl.replace(/\/+$/, '');
   const abs = (u) => (!u ? undefined : /^https?:\/\//i.test(u) ? u : `${site}${u.startsWith('/') ? '' : '/'}${u}`);
   const orgId = `${site}/#organization`;
   const kind = identity?.kind || 'organisation';
   const filled = places.filter((p) => p && (p.name || p.streetAddress || p.postalCode));
-  const several = filled.length > 1;
+  const listPlaces = filled.length > 1 || kind === 'church';
 
   const organisation = clean({
-    '@type': several && kind === 'church' ? 'Organization' : TYPE[kind] || 'Organization',
+    '@type': TYPE[kind] || 'Organization',
     '@id': orgId,
     name: identity?.siteTitle,
     alternateName: identity?.shortName && identity.shortName !== identity.siteTitle ? identity.shortName : undefined,
@@ -62,7 +86,7 @@ export function structuredData({ siteUrl, path, identity, contact = {}, places =
     email: contact.email,
     sameAs: [contact.facebookUrl],
     address: filled.length === 1 ? postal(filled[0]) : undefined,
-    location: several
+    location: listPlaces
       ? filled.map((p) => ({ '@type': PLACE_TYPE[kind] || 'Place', name: p.name, address: postal(p), hasMap: p.mapUrl }))
       : undefined,
   });
@@ -70,6 +94,8 @@ export function structuredData({ siteUrl, path, identity, contact = {}, places =
     organisation,
     { '@type': 'WebSite', '@id': `${site}/#website`, url: `${site}/`, name: identity?.siteTitle, inLanguage: 'en-GB', publisher: { '@id': orgId } },
   ];
+  const trail = breadcrumbList(site, path, title, identity?.siteTitle, breadcrumbs);
+  if (trail) graph.push(trail);
   if (article) {
     graph.push(
       clean({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",