create-we8 0.1.0

package/template/src/lib/fixtures.ts

@@ -0,0 +1,307 @@
+/**
+ * The fixture content.
+ *
+ * Everything here is invented: a small maintenance-planning studio called
+ * Northgate Tools. It exists so the template builds, runs, and reads like a
+ * real site with no backend configured at all, which is what makes the
+ * data-layer contract testable rather than aspirational.
+ *
+ * Replace it with your own copy, or delete the whole fixture backend once you
+ * are pointed at a real CMS. Nothing else in the template imports this file.
+ */
+import type { Author, Post, SiteIdentity } from './types.js';
+
+export const identity: SiteIdentity = {
+  name: 'Northgate Tools',
+  siteUrl: 'https://northgatetools.example',
+  seo: {
+    defaultTitle: 'Northgate Tools: maintenance planning for small workshops',
+    titleTemplate: '%s | Northgate Tools',
+    metaDescription:
+      'Northgate Tools builds maintenance planning software for workshops with fewer than fifty machines. Plain scheduling, honest reporting, no consultants required.',
+    ogImageUrl: null,
+    twitterHandle: null,
+    noindex: false,
+  },
+  publisher: { name: 'Northgate Tools', logoUrl: null },
+  contentPaths: {
+    blog: '/blog',
+    article: '/blog',
+    news: '/blog',
+    research: '/resources',
+    whitepaper: '/resources',
+    'case-study': '/resources',
+  },
+};
+
+export const authors: Author[] = [
+  {
+    slug: 'jane-okonjo',
+    name: 'Jane Okonjo',
+    roleTitle: 'Founder',
+    bio: 'Jane ran the maintenance desk at a sheet metal shop for nine years before starting Northgate Tools. She writes about the gap between what a schedule says and what the floor actually does.',
+    avatarUrl: null,
+    links: [{ label: 'Email', url: 'mailto:jane@northgatetools.example' }],
+  },
+  {
+    slug: 'marek-lindqvist',
+    name: 'Marek Lindqvist',
+    roleTitle: 'Reliability lead',
+    bio: 'Marek spent a decade in condition monitoring across three continents. He is the reason our failure codes fit on an index card.',
+    avatarUrl: null,
+    links: [],
+  },
+];
+
+/**
+ * Fixture posts. Note the `answer` block on each: a question phrased the way
+ * someone would type it, and an answer short enough to be quoted whole. That
+ * is the AEO habit this template is built around.
+ */
+export const posts: Post[] = [
+  {
+    slug: 'how-often-should-a-small-workshop-service-its-machines',
+    type: 'blog',
+    title: 'How often should a small workshop service its machines?',
+    excerpt:
+      'Interval-based servicing is the wrong default for a shop under fifty machines. Here is what to use instead, and how to get there without buying sensors.',
+    content: `Most small workshops inherit a servicing interval from a manual and never revisit it. The manual was written for a machine running two shifts in a climate-controlled plant. Your machine runs four hours a day next to an open door.
+
+## Start from runtime, not from the calendar
+
+Count hours, not weeks. A machine that ran 40 hours last month and one that ran 400 do not need the same attention, and a calendar schedule cannot tell them apart. Most controllers already expose an hour meter. Read it once a week and write it down; that single number beats any interval a manual can give you.
+
+## Let failures reset the interval
+
+When something breaks, the interval that preceded it was wrong. Shorten it for that machine, not for the fleet. Fleet-wide changes are how a shop ends up servicing everything twice as often and still missing the one machine that actually fails.
+
+## What this looks like after a quarter
+
+You will have three groups: machines you barely touch, machines on a steady runtime interval, and two or three that need watching. That grouping is worth more than any sensor you could buy in year one.
+
+## When to add condition monitoring
+
+Add it when a specific machine has failed twice in a way runtime did not predict, and the downtime cost more than the sensor. Not before. Condition monitoring is an answer to a question you should be able to state out loud.`,
+    coverImageUrl: null,
+    category: 'Practice',
+    tags: ['maintenance', 'scheduling'],
+    authorSlugs: ['jane-okonjo'],
+    publishedAt: '2026-07-14T09:00:00.000Z',
+    answer: {
+      question: 'How often should a small workshop service its machines?',
+      summary:
+        'Service on runtime hours rather than the calendar, and shorten the interval for any individual machine that fails inside it. For a shop under fifty machines, a weekly hour-meter reading is more useful than sensors in the first year.',
+      source: 'authored',
+    },
+    cta: null,
+    readingMinutes: 4,
+  },
+  {
+    slug: 'what-belongs-on-a-maintenance-work-order',
+    type: 'blog',
+    title: 'What belongs on a maintenance work order?',
+    excerpt:
+      'Six fields, and a hard rule about the seventh. Anything longer stops being filled in by the second week.',
+    content: `A work order that nobody completes is worse than no work order, because it tells you a job was done when it was not.
+
+## The six fields that survive
+
+Machine, date, who did it, what they did, what it needed that they did not have, and how long it took. That is the whole form. Every shop that adds a seventh field discovers within a month that the seventh field is blank and the sixth has started going blank with it.
+
+## The rule about the seventh
+
+If you want to add a field, remove one first. This sounds like a slogan until you try it. It forces the question of which field has actually earned its place, and the answer is usually that the newest one has not.
+
+## Why "what it needed that they did not have" matters most
+
+That field is your parts list, your purchasing signal, and your best evidence for a budget conversation, and it costs the technician four words. It is the only field on the form that pays for itself the same week.
+
+## Paper is fine
+
+If the paper version works and the software version does not, the software is wrong. Start by photographing the paper.`,
+    coverImageUrl: null,
+    category: 'Practice',
+    tags: ['work-orders', 'process'],
+    authorSlugs: ['marek-lindqvist', 'jane-okonjo'],
+    publishedAt: '2026-06-02T09:00:00.000Z',
+    answer: {
+      question: 'What belongs on a maintenance work order?',
+      summary:
+        'Six fields: machine, date, technician, work performed, missing parts, and time taken. Adding a seventh field reliably empties the sixth, so remove one before you add one.',
+      source: 'authored',
+    },
+    cta: null,
+    readingMinutes: 3,
+  },
+  {
+    slug: 'why-your-downtime-number-is-probably-wrong',
+    type: 'article',
+    title: 'Why your downtime number is probably wrong',
+    excerpt:
+      'Three ways downtime gets miscounted in small shops, and the one change that fixes most of it.',
+    content: `Ask two people in the same shop how much downtime last month cost and you will get two answers an order of magnitude apart. Both are usually defensible, which is the problem.
+
+## The three miscounts
+
+First, waiting is not counted. The machine stopped at nine and the technician arrived at two; most shops record five minutes of work and no downtime. Second, partial capacity is counted as zero. A machine running at half rate is treated as running. Third, planned stoppages are excluded by definition, which hides the case where the plan itself was the failure.
+
+## The one change
+
+Record the stop time and the restart time, and nothing else. Not the repair duration, not the cause, not the category. Two timestamps. Everything else can be reconstructed later; the timestamps cannot.
+
+## What to do with a year of timestamps
+
+Sort by duration and look at the top ten. In every shop we have worked with, those ten stoppages account for more lost hours than the rest of the year combined, and at least three of them share a cause nobody had named.`,
+    coverImageUrl: null,
+    category: 'Analysis',
+    tags: ['downtime', 'measurement'],
+    authorSlugs: ['marek-lindqvist'],
+    publishedAt: '2026-04-21T09:00:00.000Z',
+    answer: {
+      question: 'Why is my downtime number wrong?',
+      summary:
+        'Downtime is usually undercounted because waiting time is excluded, reduced-rate running is treated as running, and planned stoppages are excluded by definition. Recording only the stop and restart timestamps fixes most of it.',
+      source: 'authored',
+    },
+    cta: null,
+    readingMinutes: 4,
+  },
+  {
+    slug: 'the-fifty-machine-maintenance-starter-kit',
+    type: 'whitepaper',
+    title: 'The fifty machine maintenance starter kit',
+    excerpt:
+      'A printable pack: the six-field work order, a runtime log, a failure code card, and a quarterly review agenda.',
+    content: `This pack is what we hand a shop on day one. It is four pages, it is deliberately boring, and it assumes you have a printer and nothing else.
+
+## What is in it
+
+The six-field work order, sized for a clipboard. A runtime log with room for twelve months of weekly readings. A failure code card with eleven codes, which is as many as anyone remembers. A one-page agenda for a quarterly review that takes forty minutes.
+
+## How to use it
+
+Print the work order double sided and put fifty of them on the wall by the tool crib. Put the runtime log next to the hour meter, not in an office. Give the failure code card to whoever writes the work orders, and accept that codes will be wrong for the first month.
+
+## What it deliberately leaves out
+
+There is no criticality ranking, no spare parts matrix, and no KPI sheet. All three are useful in year two and all three are abandoned in year one.`,
+    coverImageUrl: null,
+    category: 'Toolkit',
+    tags: ['toolkit', 'templates'],
+    authorSlugs: ['jane-okonjo'],
+    publishedAt: '2026-05-19T09:00:00.000Z',
+    answer: {
+      question: 'What should a small workshop set up first for maintenance?',
+      summary:
+        'A six-field work order, a weekly runtime log kept at the machine, a failure code card with about a dozen codes, and a forty minute quarterly review. Criticality rankings and KPI sheets can wait for year two.',
+      source: 'authored',
+    },
+    cta: {
+      style: 'gated-download',
+      heading: 'Get the printable pack',
+      buttonLabel: 'Send me the kit',
+      url: null,
+      formKey: 'contact',
+      assetUrl: 'https://northgatetools.example/downloads/starter-kit.pdf',
+    },
+    readingMinutes: 5,
+  },
+  {
+    slug: 'case-study-a-sheet-metal-shop-cuts-unplanned-stops-by-half',
+    type: 'case-study',
+    title: 'How one sheet metal shop cut unplanned stops by half',
+    excerpt:
+      'Eleven machines, two technicians, no new hardware. What changed was the order in which they wrote things down.',
+    content: `The shop runs eleven machines across one and a half shifts. Before the change, unplanned stops averaged nine a month. Twelve months later they average four.
+
+## What they changed
+
+They moved the runtime log from the office to the machine. They cut the work order from fourteen fields to six. They started reading the top ten stoppages every quarter instead of the monthly average.
+
+## What they did not change
+
+No sensors, no new software in the first nine months, no additional staff. The one purchase was a clipboard for each machine.
+
+## The honest part
+
+Two of the eleven machines got worse. Both were near the end of their service life, and the clearer records are what finally made that case to the owner. Better measurement does not always produce a better number; sometimes it produces a better decision.`,
+    coverImageUrl: null,
+    category: 'Case study',
+    tags: ['case-study', 'downtime'],
+    authorSlugs: ['jane-okonjo', 'marek-lindqvist'],
+    publishedAt: '2026-03-08T09:00:00.000Z',
+    answer: {
+      question: 'Can a small shop reduce unplanned downtime without buying sensors?',
+      summary:
+        'Yes. An eleven machine shop halved unplanned stops in a year by moving the runtime log to the machine, cutting the work order to six fields, and reviewing the ten longest stoppages quarterly. No new hardware was bought.',
+      source: 'authored',
+    },
+    cta: {
+      style: 'link',
+      heading: 'Want the same review?',
+      buttonLabel: 'Book a quarterly review',
+      url: 'https://northgatetools.example/contact',
+      formKey: null,
+      assetUrl: null,
+    },
+    readingMinutes: 4,
+  },
+  {
+    slug: 'runtime-versus-calendar-scheduling-a-field-comparison',
+    type: 'research',
+    title: 'Runtime versus calendar scheduling: a field comparison',
+    excerpt:
+      'Fourteen shops, two years of records, and what the comparison does and does not show.',
+    content: `We compared maintenance records from fourteen small shops, half on calendar intervals and half on runtime intervals, over two years.
+
+## What we found
+
+Runtime-scheduled shops performed fewer services overall and reported fewer unplanned stops per thousand running hours. The difference was clearest in shops with uneven machine utilisation, and nearly absent in shops where every machine ran roughly the same hours.
+
+## What this does not show
+
+The sample is small, self-selected, and not randomised: shops that switched to runtime scheduling were already paying more attention. We are reporting an association, not an effect. If your machines all run the same hours, this comparison gives you no reason to change anything.
+
+## Method
+
+Records were normalised to running hours from controller hour meters where available and estimated from shift logs elsewhere. Estimated shops are flagged separately in the appendix and excluded from the primary comparison.`,
+    coverImageUrl: null,
+    category: 'Research',
+    tags: ['research', 'scheduling'],
+    authorSlugs: ['marek-lindqvist'],
+    publishedAt: '2026-02-11T09:00:00.000Z',
+    answer: {
+      question: 'Is runtime-based maintenance scheduling better than calendar-based?',
+      summary:
+        'In a fourteen shop comparison, runtime scheduling meant fewer services and fewer unplanned stops per thousand running hours, with the benefit concentrated in shops whose machines run very different hours. The sample was small and self-selected, so treat it as an association.',
+      source: 'authored',
+    },
+    cta: {
+      style: 'gated-download',
+      heading: 'Read the full comparison',
+      buttonLabel: 'Send me the paper',
+      url: null,
+      formKey: 'contact',
+      assetUrl: 'https://northgatetools.example/downloads/runtime-comparison.pdf',
+    },
+    readingMinutes: 6,
+  },
+];
+
+/** The llms.txt body served at the site root when no backend supplies one. */
+export const llmsTxt = `# Northgate Tools
+
+> Maintenance planning software for workshops with fewer than fifty machines.
+
+Northgate Tools publishes practical maintenance guidance for small workshops.
+Our writing is answer-first: each article opens with the question it answers
+and a short summary you can quote whole.
+
+## Content
+- /blog: practice and analysis on maintenance scheduling, work orders, and downtime.
+- /resources: research, whitepapers, and case studies, several with printable packs.
+- /about: who we are and what we will not sell you.
+
+## Contact
+- /contact
+`;

package/template/src/lib/markdown.ts

@@ -0,0 +1,66 @@
+/**
+ * Markdown rendering, and the heading outline that goes with it.
+ *
+ * Post bodies arrive as markdown from whatever backend is in use, so rendering
+ * is a presentation concern, not a data one: the data layer hands pages a
+ * string and this module turns it into HTML.
+ *
+ * `marked` is the one runtime dependency this template adds, and it has no
+ * dependencies of its own. The content is the site owner's, published through
+ * their own CMS, so it is treated as trusted; if you accept markdown from
+ * anyone else, sanitize the output before rendering it.
+ */
+import { marked } from 'marked';
+
+marked.setOptions({ gfm: true, breaks: false });
+
+export function renderMarkdown(markdown: string): string {
+  return marked.parse(markdown, { async: false });
+}
+
+export interface Heading {
+  depth: number;
+  text: string;
+  id: string;
+}
+
+/** Turn a heading's text into a stable anchor id. */
+export function slugifyHeading(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * The `##` and `###` headings of a body, in order.
+ *
+ * This is the AEO workhorse: a page whose headings are questions gives an
+ * answer engine an outline it can lift directly, and gives a reader an
+ * on-page table of contents for free. It reads the markdown source rather
+ * than the rendered HTML so it never depends on the renderer's output shape.
+ */
+export function outline(markdown: string): Heading[] {
+  const headings: Heading[] = [];
+  for (const line of markdown.split('\n')) {
+    const match = /^(#{2,3})\s+(.+?)\s*#*$/.exec(line);
+    if (!match) continue;
+    const text = match[2] ?? '';
+    headings.push({ depth: match[1]?.length ?? 2, text, id: slugifyHeading(text) });
+  }
+  return headings;
+}
+
+/**
+ * Add the outline's anchor ids to the rendered HTML, so the table of contents
+ * links somewhere and a crawler can cite a section rather than a page.
+ */
+export function renderBody(markdown: string): { html: string; headings: Heading[] } {
+  const headings = outline(markdown);
+  let html = renderMarkdown(markdown);
+  for (const heading of headings) {
+    const tag = `h${heading.depth}`;
+    html = html.replace(`<${tag}>`, `<${tag} id="${heading.id}">`);
+  }
+  return { html, headings };
+}

package/template/src/lib/seo.ts

@@ -0,0 +1,191 @@
+/**
+ * SEO and AEO helpers, written against the site's own `SiteIdentity` rather
+ * than any backend's shape.
+ *
+ * The merge rule is code-first: whatever a page declares wins, and the site
+ * identity only fills the gaps. That is the same rule `@we8/astro`'s `mergeSeo`
+ * applies to a we8 site config; restating it over `SiteIdentity` is what keeps
+ * pages ignorant of the backend.
+ */
+import type { AnswerBlock, Author, Post, SiteIdentity } from './types.js';
+
+/** What a page declares about itself. All optional. */
+export interface PageSeo {
+  title?: string;
+  description?: string;
+  ogImageUrl?: string;
+  /** Absolute or site-relative canonical path. */
+  path?: string;
+  noindex?: boolean;
+}
+
+export interface ResolvedSeo {
+  title: string;
+  description: string | null;
+  ogTitle: string;
+  ogDescription: string | null;
+  ogImageUrl: string | null;
+  twitterHandle: string | null;
+  canonical: string | null;
+  noindex: boolean;
+}
+
+/**
+ * Code-first merge. A page title gets the site's `titleTemplate` applied; a
+ * page without one falls back to `defaultTitle` un-templated, since that value
+ * already names the site, and then to the site name.
+ */
+export function resolveSeo(page: PageSeo, identity: SiteIdentity): ResolvedSeo {
+  const { seo } = identity;
+  const title = page.title
+    ? seo.titleTemplate
+      ? seo.titleTemplate.replace('%s', page.title)
+      : page.title
+    : (seo.defaultTitle ?? identity.name);
+  const description = page.description ?? seo.metaDescription ?? null;
+  return {
+    title,
+    description,
+    ogTitle: page.title ?? seo.defaultTitle ?? identity.name,
+    ogDescription: description,
+    ogImageUrl: page.ogImageUrl ?? seo.ogImageUrl ?? null,
+    twitterHandle: seo.twitterHandle,
+    canonical: page.path ? `${identity.siteUrl}${page.path}` : null,
+    noindex: page.noindex ?? seo.noindex,
+  };
+}
+
+/** A robots.txt body honoring the site's indexing preference. */
+export function robotsTxt(identity: SiteIdentity, sitemapPath = '/sitemap.xml'): string {
+  if (identity.seo.noindex) return 'User-agent: *\nDisallow: /\n';
+  return [
+    'User-agent: *',
+    'Allow: /',
+    '',
+    `Sitemap: ${identity.siteUrl}${sitemapPath}`,
+    '',
+    '# Answer engines are welcome. Start with /llms.txt.',
+    '',
+  ].join('\n');
+}
+
+/** A minimal urlset document. One sitemap, whatever the content source. */
+export function sitemapXml(urls: readonly string[]): string {
+  const entries = urls.map((url) => `  <url><loc>${escapeXml(url)}</loc></url>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries}\n</urlset>\n`;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/* -------------------------------------------------------------------------- */
+/* JSON-LD                                                                    */
+/* -------------------------------------------------------------------------- */
+
+type JsonLd = Record<string, unknown>;
+
+/** The `@type` a content type maps to in schema.org terms. */
+function schemaTypeFor(type: Post['type']): string {
+  switch (type) {
+    case 'news':
+      return 'NewsArticle';
+    case 'blog':
+      return 'BlogPosting';
+    default:
+      return 'Article';
+  }
+}
+
+export function organizationJsonLd(identity: SiteIdentity): JsonLd {
+  const publisher = identity.publisher;
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    name: publisher?.name ?? identity.name,
+    url: identity.siteUrl,
+    ...(publisher?.logoUrl ? { logo: publisher.logoUrl } : {}),
+  };
+}
+
+export function websiteJsonLd(identity: SiteIdentity): JsonLd {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    name: identity.name,
+    url: identity.siteUrl,
+  };
+}
+
+export function articleJsonLd(
+  post: Post,
+  url: string,
+  byline: Author[],
+  identity: SiteIdentity,
+): JsonLd {
+  return {
+    '@context': 'https://schema.org',
+    '@type': schemaTypeFor(post.type),
+    headline: post.title,
+    ...(post.excerpt ? { description: post.excerpt } : {}),
+    ...(post.coverImageUrl ? { image: post.coverImageUrl } : {}),
+    datePublished: post.publishedAt,
+    mainEntityOfPage: { '@type': 'WebPage', '@id': url },
+    author: byline.map((author) => ({
+      '@type': 'Person',
+      name: author.name,
+      url: `${identity.siteUrl}/authors/${author.slug}`,
+    })),
+    publisher: {
+      '@type': 'Organization',
+      name: identity.publisher?.name ?? identity.name,
+      ...(identity.publisher?.logoUrl ? { logo: identity.publisher.logoUrl } : {}),
+    },
+    ...(post.tags.length ? { keywords: post.tags.join(', ') } : {}),
+  };
+}
+
+/**
+ * An `FAQPage` for a set of answer blocks.
+ *
+ * Only `authored` blocks qualify. A derived block is the site paraphrasing its
+ * own excerpt; presenting that to a crawler as a curated question and answer
+ * would be a claim the content does not support, and answer engines are
+ * getting better at noticing. Returns `null` when nothing qualifies, and the
+ * page then emits no FAQ markup at all.
+ */
+export function faqJsonLd(blocks: readonly (AnswerBlock | null)[]): JsonLd | null {
+  const authored = blocks.filter(
+    (block): block is AnswerBlock => block !== null && block.source === 'authored',
+  );
+  if (authored.length === 0) return null;
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: authored.map((block) => ({
+      '@type': 'Question',
+      name: block.question,
+      acceptedAnswer: { '@type': 'Answer', text: block.summary },
+    })),
+  };
+}
+
+export function breadcrumbJsonLd(
+  trail: readonly { name: string; path: string }[],
+  identity: SiteIdentity,
+): JsonLd {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: trail.map((crumb, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: crumb.name,
+      item: `${identity.siteUrl}${crumb.path}`,
+    })),
+  };
+}