// The trimmed copy of seo-data.json (no keyword lists or lastmod dates, which // the browser never reads): scripts/seo-runtime.mjs writes it. import seoData from './seo-runtime.json'; import { ToolGroup, groupForTool, groupBySlug } from '../tool-groups'; import { toolStatus } from '../tool-catalog/tool-status'; /** SEO metadata for a single route. Mirrors the shape in seo-data.json. */ export interface SeoEntry { title: string; description: string; ogTitle: string; ogDescription: string; // seo-data.json also carries `keywords` (they steer the copy) and `lastmod` // (sitemap only); neither is in seo-runtime.json, which is what this reads. /** * 'site' renders WebSite JSON-LD and belongs to the home page alone — it * claims to describe johnmcm.com itself. 'page' is an ordinary content page, * 'tool' is one of the toolkits. */ kind: 'site' | 'page' | 'tool'; /** schema.org applicationCategory for tools, e.g. 'DeveloperApplication'. */ appCategory?: string; /** * The page's language, as a BCP 47 tag, for the one page not in English * (/fattura-elettronica is "it"). Absent means English. It becomes the * JSON-LD inLanguage and the og:locale. */ lang?: string; /** When false, the page is marked noindex and excluded from the sitemap. */ index: boolean; /** * A real page taken out of search on purpose (always with index false): it * keeps its place on its category page, in related links and its share card, * and stays out of the sitemap, IndexNow, llms.txt and the ItemList. */ parked?: boolean; } interface SeoFile { base: string; default: SeoEntry; routes: Record; } const data = seoData as unknown as SeoFile; export const SEO_BASE_URL = data.base; export const SEO_DEFAULT = data.default; export const SEO_ROUTES = data.routes; /** * True for a page that people should be shown links to: an indexable page, or * one parked out of search but still part of the site. Search-facing output * (robots meta, sitemap, ItemList) reads `index` itself instead. */ export function isListed(key: string): boolean { const e = SEO_ROUTES[key]; return !!e && (e.index || !!e.parked); } /** * The tools a category page lists, in order: the group's own, then its "also" * tools, less any that are not listed. The Toolkits menu's "All N" link counts * this same list, so the number in the menu is the number on the page. */ export function categoryPaths(group: ToolGroup): string[] { return [...group.tools, ...(group.also ?? [])].filter((path) => isListed(path)); } /** Normalise a router URL to a seo-data key: no leading slash, no query/hash, no trailing slash. */ export function normalizeRouteKey(url: string): string { const path = url.split(/[?#]/)[0].replace(/^\/+/, '').replace(/\/+$/, ''); return path; } /** Resolve the SEO entry for a route key, falling back to the site default. */ export function resolveSeoEntry(key: string): SeoEntry { return SEO_ROUTES[key] ?? SEO_DEFAULT; } /** og:locale by page language. finalize-seo.mjs has the same table. */ const OG_LOCALES: Record = { it: 'it_IT', de: 'de_DE' }; /** The og:locale a page declares, or null for an English page, which needs none. */ export function ogLocale(entry: SeoEntry): string | null { return entry.lang ? OG_LOCALES[entry.lang] ?? null : null; } /** Absolute canonical URL for a route key. */ export function canonicalUrl(key: string): string { return key ? `${SEO_BASE_URL}/${key}` : `${SEO_BASE_URL}/`; } /** * What a downloadable program needs in place of browserRequirements, by route. * Read off its page. Empty since Colin's Clicker, the only download, was taken * down on 13 Oct 2026. finalize-seo.mjs has the same table. */ const DOWNLOAD_LD: Record> = {}; /** * The person a profile page is about, by route: /hire-me is John's, so it is a * ProfilePage whose mainEntity is a Person, which is how Google links a page to * a name. finalize-seo.mjs has the same table. */ const PROFILE_LD: Record> = { 'hire-me': { '@type': 'Person', name: 'John McMillan', jobTitle: 'Senior Full-Stack Software Engineer', url: `${data.base}/hire-me`, sameAs: [ 'https://www.linkedin.com/in/john-mcmillan-898b3972', 'https://github.com/johnmcmillan', 'https://app.pluralsight.com/profile/johnmcmillan', ], }, }; /** * Who is behind the site, as schema.org data (9 Nov 2026): the Organization * johnmcm.com, run by John McMillan Consulting LLC, and its founder, named as * /about names him (first name only, the owner's choice), with the profiles * /hire-me links to. Stated in full on the home page (the WebSite's publisher) and on /about * (the AboutPage's mainEntity); every tool's publisher points at it by @id. * Only facts already on the site. finalize-seo.mjs has the same objects. */ const ORGANIZATION_ID = `${data.base}/#organization`; export const ORGANIZATION_LD: Record = { '@type': 'Organization', '@id': ORGANIZATION_ID, name: 'johnmcm.com', legalName: 'John McMillan Consulting LLC', url: `${data.base}/`, logo: `${data.base}/assets/app/icon-512.png`, email: 'webmaster@johnmcm.com', founder: { '@type': 'Person', '@id': `${data.base}/about#founder`, name: 'John', url: `${data.base}/about`, sameAs: ['https://www.linkedin.com/in/john-mcmillan-898b3972', 'https://github.com/johnmcmillan'], }, }; /** A content page that is a particular kind of WebPage. finalize-seo.mjs has the same table. */ const PAGE_TYPES: Record = { about: 'AboutPage' }; /** Build the schema.org JSON-LD object for an entry. */ export function buildJsonLd(entry: SeoEntry, key: string): Record { const url = canonicalUrl(key); if (entry.kind === 'site') { return { '@context': 'https://schema.org', '@type': 'WebSite', // Google takes the site name shown beside results from WebSite.name, // so it is the site's name, and alternateName is the short form of // it - not the home page's slogan, which it was until 9 Nov 2026. The // url matches the home page's canonical. name: 'johnmcm.com', alternateName: 'johnmcm', url: `${SEO_BASE_URL}/`, description: entry.description, publisher: ORGANIZATION_LD, }; } if (entry.kind === 'page') { const person = PROFILE_LD[key]; const about = PAGE_TYPES[key] === 'AboutPage'; return { '@context': 'https://schema.org', '@type': person ? 'ProfilePage' : PAGE_TYPES[key] ?? 'WebPage', name: entry.ogTitle, url, description: entry.description, ...(entry.lang ? { inLanguage: entry.lang } : {}), ...(person ? { mainEntity: person } : {}), ...(about ? { mainEntity: ORGANIZATION_LD } : {}), }; } // A download (Colin's Clicker) is a Windows program, not a page that runs in // any browser, so it states its own platform and runtime instead. const download = toolStatus(key)?.processing === 'download'; return { '@context': 'https://schema.org', '@type': 'SoftwareApplication', // The clean name, as in the breadcrumb: ogTitle may add an explainer after // a dash, which is for a share card, not for the application's name. name: crumbName(entry.ogTitle), description: entry.description, url, ...(entry.lang ? { inLanguage: entry.lang } : {}), applicationCategory: entry.appCategory ?? 'UtilitiesApplication', operatingSystem: download ? 'Windows' : 'Any', offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' }, // price: '0' already says free, but only to something that reads the offer. // isAccessibleForFree is the explicit flag, and "free" is the whole claim // these pages compete on, so it is worth stating twice in the one place a // machine is reading. isAccessibleForFree: true, // Every web tool here is a page that does its work in JavaScript. Stating // the requirement is honest about what it needs, and true of all of them. ...(download ? DOWNLOAD_LD[key] ?? {} : { browserRequirements: 'Requires JavaScript' }), // No featureList here: the list lives in each tool's template, not in // data, so finalize-seo.mjs adds it at build time, read from the page. // The site, by reference to the Organization stated in full on the home // page and /about, rather than a person. publisher: { '@type': 'Organization', '@id': ORGANIZATION_ID, name: 'johnmcm.com', url: `${SEO_BASE_URL}/` }, }; } /** * ItemList for a category page, naming the tools it links to, or null. * * A category page is a list of things; saying so lets the tools be read as * members of it rather than as loose links. Each entry points at the tool's own * canonical URL, so nothing here competes with the tool page itself. */ export function buildItemList(key: string): Record | null { const group = groupBySlug(key); if (!group) return null; const tools = group.tools.filter((t) => SEO_ROUTES[t]?.index); if (!tools.length) return null; return { '@context': 'https://schema.org', '@type': 'ItemList', name: group.heading, numberOfItems: tools.length, itemListElement: tools.map((t, i) => ({ '@type': 'ListItem', position: i + 1, name: crumbName(SEO_ROUTES[t].ogTitle), url: canonicalUrl(t), })), }; } /** One step in a breadcrumb trail: what it says, and where it goes. */ export interface Crumb { name: string; /** Route path with no leading slash. '' is the home page. */ key: string; } /** * The name a page goes by in a breadcrumb. * * ogTitle is written to be found in a results page, so several are a name plus * an explainer after a dash - "SVG Optimizer — Shrink SVG Files". That is right * for a title and wrong for a crumb, where it swamps the trail it sits at the * end of. Only the leading name survives; a title with no dash is untouched. * * The dash must be surrounded by spaces to count, so a hyphenated name is left * alone rather than being cut at its own hyphen. */ export function crumbName(ogTitle: string): string { return ogTitle.split(/\s+[—–-]\s+/)[0].trim(); } /** * The breadcrumb trail for a route, or null for a page that has no trail worth * showing (the home page is its own root; a stray noindex page leads nowhere). * * A tool in a group gets Home > Category > Tool, which is the trail Google * renders in place of the raw URL in a result. A tool in no group gets * Home > Tool rather than an invented category - a breadcrumb that claims a * section the site does not have is worse than a short one. * * The final crumb is the current page. It is included because schema.org * expects the trail to end at the page itself, and dropped from the links in * the rendered markup by BreadcrumbsComponent. */ /** Format pages of the shared viewer live under /open-file/; finalize-seo.mjs has the same two constants. */ export const OPEN_FILE_PREFIX = 'open-file/'; export const OPEN_FILE_CRUMB = 'Open a file'; export function buildCrumbs(key: string): Crumb[] | null { if (!key) return null; const entry = SEO_ROUTES[key]; if (!entry) return null; const home: Crumb = { name: 'Home', key: '' }; const asGroup = groupBySlug(key); if (asGroup) return [home, { name: asGroup.name, key: asGroup.slug }]; const self: Crumb = { name: crumbName(entry.ogTitle), key }; // A format page sits under /open-file, which is how people reach it. if (key.startsWith(OPEN_FILE_PREFIX)) return [home, { name: OPEN_FILE_CRUMB, key: 'open-file' }, self]; const group = groupForTool(key); return group ? [home, { name: group.name, key: group.slug }, self] : [home, self]; } /** * schema.org BreadcrumbList for a route, or null where there is no trail. * * Emitted as a second JSON-LD block rather than folded into the first: the * existing block is verified byte-for-byte against an independent * implementation at build time, and merging two objects into a @graph would * mean rewriting that check for no gain. Multiple ld+json scripts on a page * are valid and Google reads them all. */ export function buildBreadcrumbList(key: string): Record | null { const crumbs = buildCrumbs(key); if (!crumbs) return null; return { '@context': 'https://schema.org', '@type': 'BreadcrumbList', itemListElement: crumbs.map((c, i) => ({ '@type': 'ListItem', position: i + 1, name: c.name, item: canonicalUrl(c.key), })), }; }