ferst-core 0.8.2 → 0.9.1

package/bin/ferst-update.mjs

@@ -142,6 +142,26 @@ export function coreRangeFor(version) {
   return `^${m[1]}.${m[2]}.0`;
 }
 
+/** Whether `b` is a newer plain x.y.z version than `a`; anything unparsable is not newer. */
+export function isNewerVersion(a, b) {
+  const parse = (v) => String(v ?? '').trim().replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)$/)?.slice(1).map(Number);
+  const [x, y] = [parse(a), parse(b)];
+  if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return y[i] > x[i];
+  return false;
+}
+
+/**
+ * The dry run's line about the engine. A site's scheduled run decides from the dry run
+ * whether to update, so a newer ferst-core has to read as a change that WOULD apply, like
+ * the scaffold changes above it; otherwise an engine-only release never reaches the site.
+ */
+export function coreUpdateNote(installed, latest) {
+  if (!latest) return `ferst-core is ${installed ?? '(not installed)'}; the latest version is unknown`;
+  if (!installed) return `ferst-core ${latest} WOULD be installed (none installed yet)`;
+  return isNewerVersion(installed, latest) ? `ferst-core ${installed} → ${latest} WOULD be installed` : `ferst-core is current (${installed})`;
+}
+
 /** Read the `version` out of a package.json's text. Throws if absent. */
 export function extractVersion(pkgJsonText) {
   let v;
@@ -451,8 +471,7 @@ function main() {
     console.log('ferst-update: --no-core — skipping the ferst-core npm bump.');
   } else if (dryRun) {
     dryLatest = (tryExec('npm view ferst-core version', cwd) || '').trim() || null;
-    const current = readInstalledCoreVersion(cwd);
-    console.log(`ferst-update: ferst-core installed=${current ?? '(none)'} latest=${dryLatest || '(unknown)'}`);
+    console.log(`ferst-update: --dry-run — ${coreUpdateNote(readInstalledCoreVersion(cwd), dryLatest)}`);
   } else {
     const before = readInstalledCoreVersion(cwd);
     console.log('ferst-update: npm install ferst-core@latest --save ...');

package/cms/config.template.yml

@@ -76,6 +76,7 @@ collections:
               - { name: shortName, label: Short name, widget: string }
               - { name: description, label: Description, widget: text }
               - { name: location, label: Location, widget: string, required: false }
+              - { name: kind, label: Kind of organisation, widget: select, required: false, default: organisation, options: [{ label: Church, value: church }, { label: School, value: school }, { label: Charity, value: charity }, { label: Business, value: business }, { label: Other organisation, value: organisation }], hint: "Tells search engines what the site is for." }
           - name: contact
             label: Contact
             widget: object
@@ -84,6 +85,28 @@ collections:
               - { name: phoneTel, label: 'Phone (tel: digits)', widget: string, required: false }
               - { name: email, label: Email, widget: string, required: false }
               - { name: facebookUrl, label: Facebook URL, widget: string, required: false }
+          - name: places
+            label: Places
+            label_singular: Place
+            widget: list
+            required: false
+            hint: "Each place the site is for, with its address (a parish may have several churches). Search engines read these."
+            fields:
+              - { name: name, label: Name, widget: string }
+              - { name: streetAddress, label: Street address, widget: string, required: false }
+              - { name: locality, label: Town, widget: string, required: false }
+              - { name: postalCode, label: Postcode, widget: string, required: false }
+              - { name: country, label: Country code, widget: string, required: false, default: GB }
+              - { name: mapUrl, label: Map link, widget: string, required: false }
+          - name: verification
+            label: Search engine verification
+            widget: object
+            required: false
+            collapsed: true
+            hint: "Codes from Google Search Console and Bing Webmaster Tools, when they ask for an HTML tag."
+            fields:
+              - { name: google, label: Google code, widget: string, required: false }
+              - { name: bing, label: Bing code, widget: string, required: false }
 
       - name: logos
         label: Logos
@@ -154,6 +177,16 @@ collections:
           - { name: provider, label: Provider name, widget: string, default: Google Calendar }
           - { name: weekStart, label: Week starts on, widget: select, default: monday, options: [{ label: "Monday", value: monday }, { label: "Sunday", value: sunday }] }
 
+      - name: posts-settings
+        label: News
+        file: src/content/postsSettings/index.json
+        icon: newspaper
+        fields:
+          - { name: title, label: Heading, widget: string, default: News }
+          - { name: intro, label: Intro, widget: text, required: false }
+          - { name: perPage, label: Posts per page, widget: number, default: 12, value_type: int, min: 1, max: 48, hint: "How many posts each news page shows. 12 fills rows of one, two, three or four evenly." }
+          - { name: excludeFromIndex, label: Tags kept off the main news page, widget: list, required: false, hint: "Tag names (for example newsletter) whose posts appear only on their own tag page." }
+
   - name: posts
     label: Posts
     label_singular: Post

package/content/posts.ts

@@ -43,8 +43,8 @@ export const postsSettingsSchema = z.object({
   title: z.string().default('News'),
   /** Optional intro copy for the index. */
   intro: z.string().default(''),
-  /** Posts per page in the paginated index. */
-  perPage: z.number().int().min(1).default(9),
+  /** Posts per page in the paginated index. 12 fills rows of 1, 2, 3 or 4 tiles evenly. */
+  perPage: z.number().int().min(1).default(12),
   /** Tag slugs excluded from the MAIN index (e.g. a `newsletter` tag that has its
    *  own view). Kept generic — no capability knows what "newsletter" means. */
   excludeFromIndex: z.array(z.string()).default([]),

package/content/schemas.ts

@@ -35,6 +35,30 @@ const siteIdentitySchema = z
     description: z.string().default('A website built with Ferst.'),
     /** 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. */
+    kind: z.enum(['church', 'school', 'charity', 'business', 'organisation']).default('organisation'),
+  })
+  .default({});
+
+/** One of the places the site is for (a parish may have several churches). Search engines
+ *  read each address from here (structured data); blocks can show the same facts. */
+const placeSchema = z.object({
+  name: z.string().default(''),
+  streetAddress: z.string().default(''),
+  locality: z.string().default(''),
+  postalCode: z.string().default(''),
+  country: z.string().default('GB'),
+  /** A link to the place on a map (e.g. Google Maps). */
+  mapUrl: z.string().default(''),
+});
+
+/** Search-engine verification codes (Search Console, Bing Webmaster Tools), rendered as
+ *  meta tags, for sites whose DNS we don't run. */
+const verificationSchema = z
+  .object({
+    google: z.string().default(''),
+    bing: z.string().default(''),
   })
   .default({});
 
@@ -54,6 +78,8 @@ const siteContactSchema = z
 export const siteSettingsSchema = z.object({
   identity: siteIdentitySchema,
   contact: siteContactSchema,
+  places: z.array(placeSchema).default([]),
+  verification: verificationSchema,
 });
 
 export const logoSettingsSchema = z.object({

package/integration.mjs

@@ -34,7 +34,8 @@
  *   square logo, else the site's initial in its brand colour. A site's own files in
  *   `public/` win.
  * @param {boolean} [options.seo=true] Search signals (lib/seo.mjs): `/robots.txt`, and once
- *   `ferst-site.json` has a `siteUrl`, `/sitemap.xml` and a canonical address on every page.
+ *   `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`.
  *   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}
@@ -186,6 +187,10 @@ export default function ferst(options = {}) {
           if (search.siteUrl && !hasPublicFile(root, 'sitemap.xml')) {
             injectRoute({ pattern: '/sitemap.xml', entrypoint: 'ferst-core/routes/sitemap.xml.ts' });
           }
+          // The news feed lists absolute addresses too.
+          if (search.siteUrl && blog) {
+            injectRoute({ pattern: '/posts/rss.xml', entrypoint: 'ferst-core/routes/posts/rss.xml.ts' });
+          }
         }
       },
       // The engine's self-hosted fonts: served in dev, copied into every build.

package/layouts/Base.astro

@@ -30,7 +30,8 @@ import SecondaryLogo from '../components/SecondaryLogo.astro';
 import { loadSiteSettings } from '../lib/siteSettings';
 import { getCalloutSettings } from '../lib/callout';
 import { buildThemeStyle } from '../lib/themeTokens';
-import { canonicalUrl } from '../lib/seo.mjs';
+import { canonicalUrl, previewTags } from '../lib/seo.mjs';
+import { structuredData } from '../lib/structured-data.mjs';
 
 interface Props {
   title: string;
@@ -47,6 +48,8 @@ interface Props {
   /** False for a page with no address of its own (the "page not found" page): it gets no
    *  canonical address and asks search engines not to index it. */
   indexable?: boolean;
+  /** A post: shared and described to search engines as an article with this date. */
+  article?: { date: Date | string; image?: string };
 }
 
 const {
@@ -59,6 +62,7 @@ const {
   showSecondaryLogo = false,
   align = 'start',
   indexable = true,
+  article,
 } = Astro.props;
 
 const settings = await loadSiteSettings();
@@ -95,6 +99,36 @@ const metaDescription = description ?? identity.description;
 const siteUrl = import.meta.env.FERST_SITE_URL || '';
 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.
+const ld = indexable
+  ? structuredData({
+      siteUrl: siteUrl || null,
+      path,
+      identity,
+      contact,
+      places: settings.places,
+      logo: settings.primaryLogoLight,
+      title,
+      description: metaDescription,
+      article,
+    })
+  : null;
+// `<` escaped so the JSON can't close its script tag.
+const ldJson = ld ? JSON.stringify(ld).replace(/</g, '\\u003c') : '';
+const preview = previewTags({
+  siteUrl: siteUrl || null,
+  path,
+  title,
+  siteName: identity.siteTitle,
+  description: metaDescription,
+  image: heroImage,
+  logo: settings.primaryLogoLight,
+  article,
+});
+const { verification } = settings;
+const hasFeed = Boolean(siteUrl) && import.meta.env.FERST_ROUTES_BLOG !== false;
 ---
 
 <!doctype html>
@@ -106,6 +140,11 @@ const noindex = !indexable || import.meta.env.FERST_SEO_PRODUCTION === false;
     <meta name="description" content={metaDescription} />
     {canonical && <link rel="canonical" href={canonical} />}
     {noindex && <meta name="robots" content="noindex" />}
+    {preview.map((t) => (t.property ? <meta property={t.property} content={t.content} /> : <meta name={t.name} content={t.content} />))}
+    {verification.google && <meta name="google-site-verification" content={verification.google} />}
+    {verification.bing && <meta name="msvalidate.01" content={verification.bing} />}
+    {hasFeed && <link rel="alternate" type="application/rss+xml" title={`${identity.siteTitle}: news`} href="/posts/rss.xml" />}
+    {ldJson && <script type="application/ld+json" is:inline set:html={ldJson} />}
     <title>{title} — {identity.siteTitle}</title>
     <!-- The browser icon, written into every build by the ferst() integration (lib/site-icon). -->
     <link rel="icon" href="/favicon.ico" sizes="32x32 48x48" />

package/lib/seo.mjs

@@ -128,3 +128,71 @@ export function withNoindexHeader(existing) {
   if (!current.trim()) return NOINDEX_RULE;
   return `${current.replace(/\s*$/, '')}\n\n${NOINDEX_RULE}`;
 }
+
+/**
+ * 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
+ * site's logo, else its browser icon. Addresses must be absolute, so without the site's
+ * address only the title, description and type are given.
+ * @param {{ siteUrl: string | null, path: string, title: string, siteName: string, description?: string,
+ *   image?: string, logo?: string, article?: { date: Date | string } }} p
+ * @returns {Array<{ property?: string, name?: string, content: string }>}
+ */
+export function previewTags({ siteUrl, path, title, siteName, description, image, logo, article }) {
+  const site = siteUrl ? siteUrl.replace(/\/+$/, '') : null;
+  const abs = (u) => (/^https?:\/\//i.test(u) ? u : `${site}${u.startsWith('/') ? '' : '/'}${u}`);
+  const tags = [
+    { property: 'og:type', content: article ? 'article' : 'website' },
+    { property: 'og:title', content: title },
+    ...(description ? [{ property: 'og:description', content: description }] : []),
+    ...(siteName ? [{ property: 'og:site_name', content: siteName }] : []),
+    { property: 'og:locale', content: 'en_GB' },
+  ];
+  if (site) {
+    tags.push({ property: 'og:url', content: canonicalUrl(site, path) });
+    tags.push({ property: 'og:image', content: abs(image || logo || '/apple-touch-icon.png') });
+  }
+  tags.push({ name: 'twitter:card', content: image && site ? 'summary_large_image' : 'summary' });
+  if (article) {
+    const d = article.date instanceof Date ? article.date : new Date(article.date);
+    if (!Number.isNaN(d.getTime())) tags.push({ property: 'article:published_time', content: d.toISOString().slice(0, 10) });
+  }
+  return tags;
+}
+
+/**
+ * The site's news feed (RSS 2.0) at /posts/rss.xml: its posts in the order given (newest
+ * first), each with its address, date and summary.
+ * @param {{ siteUrl: string, title: string, description?: string,
+ *   items: Array<{ title: string, path: string, date: Date | string, summary?: string }> }} p
+ */
+export function rssXml({ siteUrl, title, description = '', items }) {
+  const site = siteUrl.replace(/\/+$/, '');
+  const entries = items.map((item) => {
+    const link = canonicalUrl(site, item.path);
+    const d = item.date instanceof Date ? item.date : new Date(item.date);
+    return [
+      '    <item>',
+      `      <title>${xmlEscape(item.title)}</title>`,
+      `      <link>${xmlEscape(link)}</link>`,
+      `      <guid isPermaLink="true">${xmlEscape(link)}</guid>`,
+      ...(Number.isNaN(d.getTime()) ? [] : [`      <pubDate>${d.toUTCString()}</pubDate>`]),
+      ...(item.summary ? [`      <description>${xmlEscape(item.summary)}</description>`] : []),
+      '    </item>',
+    ].join('\n');
+  });
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+    '  <channel>',
+    `    <title>${xmlEscape(title)}</title>`,
+    `    <link>${xmlEscape(`${site}/`)}</link>`,
+    `    <description>${xmlEscape(description)}</description>`,
+    '    <language>en-gb</language>',
+    `    <atom:link href="${xmlEscape(`${site}/posts/rss.xml`)}" rel="self" type="application/rss+xml"/>`,
+    ...entries,
+    '  </channel>',
+    '</rss>',
+    '',
+  ].join('\n');
+}

package/lib/structured-data.mjs

@@ -0,0 +1,88 @@
+/**
+ * What every page tells search engines about the site: schema.org structured data (JSON-LD),
+ * built from the site's own details in `siteSettings` (its kind, places and contact), the
+ * 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 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. */
+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. */
+function clean(value) {
+  if (Array.isArray(value)) {
+    const items = value.map(clean).filter((v) => v !== undefined);
+    return items.length ? items : undefined;
+  }
+  if (value && typeof value === 'object' && !(value instanceof Date)) {
+    const entries = Object.entries(value).map(([k, v]) => [k, clean(v)]).filter(([, v]) => v !== undefined);
+    return entries.length ? Object.fromEntries(entries) : undefined;
+  }
+  return value === '' || value === null ? undefined : value;
+}
+
+const postal = (p) => ({ '@type': 'PostalAddress', streetAddress: p.streetAddress, addressLocality: p.locality, postalCode: p.postalCode, addressCountry: p.country || 'GB' });
+const isoDate = (d) => {
+  const date = d instanceof Date ? d : new Date(d);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
+};
+
+/**
+ * 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
+ */
+export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article }) {
+  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 organisation = clean({
+    '@type': several && kind === 'church' ? 'Organization' : TYPE[kind] || 'Organization',
+    '@id': orgId,
+    name: identity?.siteTitle,
+    alternateName: identity?.shortName && identity.shortName !== identity.siteTitle ? identity.shortName : undefined,
+    description: identity?.description,
+    url: `${site}/`,
+    logo: abs(logo),
+    telephone: contact.phoneDisplay || contact.phoneTel,
+    email: contact.email,
+    sameAs: [contact.facebookUrl],
+    address: filled.length === 1 ? postal(filled[0]) : undefined,
+    location: several
+      ? filled.map((p) => ({ '@type': PLACE_TYPE[kind] || 'Place', name: p.name, address: postal(p), hasMap: p.mapUrl }))
+      : undefined,
+  });
+  const graph = [
+    organisation,
+    { '@type': 'WebSite', '@id': `${site}/#website`, url: `${site}/`, name: identity?.siteTitle, inLanguage: 'en-GB', publisher: { '@id': orgId } },
+  ];
+  if (article) {
+    graph.push(
+      clean({
+        '@type': 'Article',
+        headline: title,
+        description,
+        datePublished: isoDate(article.date),
+        image: abs(article.image),
+        mainEntityOfPage: canonicalUrl(site, path),
+        author: { '@id': orgId },
+        publisher: { '@id': orgId },
+      }),
+    );
+  }
+  return { '@context': 'https://schema.org', '@graph': graph };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "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",

package/routes/posts/[...slug].astro

@@ -15,7 +15,7 @@ const { Content } = await entry.render();
 const tags = await resolveTagLabels(entry.data.tags);
 ---
 
-<Base title={entry.data.title} description={entry.data.summary} heroImage={entry.data.heroImage}>
+<Base title={entry.data.title} description={entry.data.summary} heroImage={entry.data.heroImage} article={{ date: entry.data.date, image: entry.data.heroImage }}>
   <PostArticle
     title={entry.data.title}
     date={entry.data.date}

package/routes/posts/rss.xml.ts

@@ -0,0 +1,21 @@
+// /posts/rss.xml: the site's news feed, injected by the ferst() integration once the site
+// has an address (`ferst-site.json` `siteUrl`) and its blog is on. Its newest 50 posts, each
+// with its address, date and summary, for feed readers and search engines.
+import type { APIRoute } from 'astro';
+import { getPublishedPosts } from '../../lib/posts';
+import { loadSiteSettings } from '../../lib/siteSettings';
+import { rssXml } from '../../lib/seo.mjs';
+
+export const prerender = true;
+
+export const GET: APIRoute = async () => {
+  const { identity } = await loadSiteSettings();
+  const posts = (await getPublishedPosts()).slice(0, 50);
+  const xml = rssXml({
+    siteUrl: String(import.meta.env.FERST_SITE_URL || ''),
+    title: `${identity.siteTitle}: news`,
+    description: identity.description,
+    items: posts.map((post) => ({ title: post.data.title, path: `/posts/${post.slug}`, date: post.data.date, summary: post.data.summary })),
+  });
+  return new Response(xml, { headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' } });
+};