create-we8 0.1.0

package/template/.env.example

@@ -0,0 +1,15 @@
+# The we8 backend. Set both and the site builds from your CMS; leave either
+# unset and it builds from the fixtures in src/lib/fixtures.ts.
+#
+# WE8_API_URL is your CMS's origin with NO path on the end: a self-hosted we8
+# CMS serves /v1 at its own root, so a trailing /api produces 404s. Locally
+# that is http://localhost:8787.
+WE8_API_URL=https://cms.example.com
+WE8_PUBLISHABLE_KEY=pk_replace_me
+
+# Force the fixture backend even with a live API configured. Useful for an
+# offline build, a screenshot, or a reproducible CI run.
+# WE8_DATA_SOURCE=fixtures
+
+# Your public origin. Drives canonical URLs and the sitemap.
+SITE=https://northgatetools.example

package/template/README.md

@@ -0,0 +1,202 @@
+# we8-template-astro
+
+The we8 Astro starter: a small marketing site with a blog, content pages, a
+resources shelf, a contact form, consent, and SEO and AEO built in. It is wired
+to a we8 CMS by default and it builds with no backend at all, from fixtures.
+
+It is not published to npm. `create-we8` copies it into your project, and from
+that moment it is your code: edit it, delete what you do not need, and do not
+expect an upgrade path.
+
+```sh
+npm install
+npm run dev      # http://localhost:4321, fixture content, no backend needed
+```
+
+Point it at a CMS by copying `.env.example` to `.env` and filling in two
+values:
+
+```sh
+WE8_API_URL=https://cms.example.com
+WE8_PUBLISHABLE_KEY=pk_...
+```
+
+That is the whole configuration. `WE8_API_URL` is the CMS origin with no path
+on the end, because a self-hosted we8 CMS serves `/v1` at its own root; locally
+that is `http://localhost:8787`. The publishable key is meant to ship in a
+frontend; never put a secret (`sk_`) key here.
+
+## What you get
+
+| Route              | What it is                                                                |
+| ------------------ | ------------------------------------------------------------------------- |
+| `/`                | Home: hero, answer blocks, recent writing, recent resources               |
+| `/about`           | A content page with question-phrased headings and the team roster          |
+| `/blog`            | The editorial listing                                                     |
+| `/blog/[slug]`     | A post: answer, byline, table of contents, body, CTA                       |
+| `/resources`       | Toolkits, case studies, and research, grouped                              |
+| `/resources/[slug]`| The same post page, in the resources section                              |
+| `/authors/[slug]`  | An author, their bio, and everything they wrote                            |
+| `/contact`         | The progressive-enhancement contact form                                  |
+| `/robots.txt`      | Honors the site's indexing preference, points at the sitemap and llms.txt  |
+| `/sitemap.xml`     | One sitemap: site pages, posts, authors, plus anything the CMS adds        |
+| `/llms.txt`        | The CMS document if there is one, otherwise generated from real content    |
+
+## The data-layer contract
+
+This template is backend-agnostic by construction, not by intention.
+
+```
+src/lib/types.ts            the contract: Post, Author, SiteIdentity, SiteBackend
+src/lib/we8-backend.ts      the we8 adapter  <- the ONLY file that imports we8
+src/lib/fixture-backend.ts  the static adapter
+src/lib/fixtures.ts         the invented content it serves
+src/lib/data.ts             picks one, and is the ONLY module pages import data from
+```
+
+Four rules, and the tests enforce the ones that can be enforced:
+
+1. **Pages never import a backend.** Every page and component imports from
+   `src/lib/data.js`. Nothing outside `src/lib/` knows which backend is in use.
+2. **`we8-backend.ts` is the only file that imports `@we8/astro` or
+   `@we8/client`.** `data.ts` does not, `types.ts` does not, no page does. The
+   one exception is UI: `<ConsentBanner>`, `<VisitBeacon>`, and `<We8Form>` are
+   imported by `BaseLayout.astro`, `contact.astro`, and `PostCta.astro`. They
+   are components, not data, and each is a one-line swap.
+3. **The contract owns its own vocabulary.** `Post`, `Author`, and
+   `SiteIdentity` are this site's types. They are not re-exported we8 types,
+   which is why a second backend owes we8 nothing.
+4. **Two implementations, one test suite.** `test/data-layer.test.ts` runs the
+   same contract assertions against both backends with `describe.each`. Adding
+   a third backend means adding one line to that array.
+
+To swap backends, write a `SiteBackend` and return it from `selectBackend` in
+`data.ts`. Nothing else changes.
+
+### Which backend a build uses
+
+| Environment                                          | Backend  | Browser features        |
+| ---------------------------------------------------- | -------- | ----------------------- |
+| `WE8_API_URL` and `WE8_PUBLISHABLE_KEY` both set      | we8      | form, consent, beacon   |
+| Either missing                                        | fixtures | none rendered           |
+| `WE8_DATA_SOURCE=fixtures`                            | fixtures | none rendered           |
+
+The fallback is deliberate: a template that cannot build without a backend is
+not backend-agnostic. `WE8_DATA_SOURCE=fixtures` forces the static path even
+with a live API configured, which is what makes an offline or CI build
+reproducible.
+
+When no backend is live, the contact form, the consent banner, and the visit
+beacon are not rendered at all. A form that silently discards a message is
+worse than a page that tells you to send an email.
+
+## SEO and AEO
+
+Search engines want a page they can index. Answer engines want a paragraph they
+can quote. This template is built for the second, which turns out to satisfy
+the first.
+
+**Per page.** `resolveSeo` in `src/lib/seo.ts` merges a page's own declarations
+over the site identity, page first. Title, description, canonical, Open Graph,
+Twitter, and the robots directive all come from one resolved object rendered by
+`SiteHead.astro`.
+
+**Structured data.** `Organization` and `WebSite` on every page;
+`BlogPosting`/`NewsArticle`/`Article` with a linked byline on posts;
+`BreadcrumbList` on inner pages; `Person` with a work list on author pages;
+`ItemList` on resources; `FAQPage` where there are real questions and answers.
+
+**Answer-first content.** Every post carries an answer block: the question a
+person would type, and an answer short enough to lift out whole. It renders
+directly under the title, before any preamble, and it is what the listing cards
+and `llms.txt` quote. Headings are questions, so the table of contents doubles
+as an outline a crawler can cite by anchor.
+
+**The honesty rule.** An answer block is `authored` when an editor wrote it and
+`derived` when the site built one from the title and the excerpt. Derived blocks
+render, because a summary helps a reader either way. Only authored blocks become
+`FAQPage` markup: presenting a paraphrased excerpt to a crawler as a curated
+answer is a claim the content does not support.
+
+**llms.txt.** Served from the CMS document when there is one, otherwise
+generated from real URLs and real answer summaries. A generated file that is
+true beats a hand-written one that has gone stale.
+
+### What the CMS needs to send
+
+The template reads two flat, optional AEO fields off each post, exactly as
+`@we8/cms` ships them:
+
+```jsonc
+{
+  "slug": "how-do-berth-windows-actually-work",
+  "title": "How do berth windows actually work?",
+  "answerSummary": "A berth window reserves a quay slot for an arriving vessel...",
+  "questionHeading": "How do berth windows work?"   // optional, falls back to the title
+}
+```
+
+`answerSummary` is editor-authored in the CMS, which is why the template
+treats it as an authored answer and emits `FAQPage` markup for it. When the
+fields are absent (an older backend) the template derives a block instead.
+
+## Editing the site
+
+- **Your copy** lives in `src/pages/index.astro` (the hero and its answer
+  blocks) and `src/pages/about.astro`. These are yours to rewrite; they are not
+  fetched from the CMS.
+- **Your content** lives in the CMS: posts, authors, and the CTA on each post.
+- **Your fixtures** live in `src/lib/fixtures.ts`. Replace or delete them once
+  you have a real backend.
+- **Your routes** are the `SECTIONS` map in `src/lib/data.ts`. Change a value
+  and rename the matching folder under `src/pages` together. The CMS's own
+  `contentPaths` are advisory here; this template will not link to a page it
+  does not render.
+- **Your styling** is one plain CSS file, `src/styles/global.css`: tokens, then
+  elements, then a handful of components, with a dark scheme via
+  `prefers-color-scheme`. No framework, no build step. Replacing it with
+  something else touches no other file.
+
+## The contact form
+
+`<We8Form>` renders a real `<form>` and upgrades it with a submit handler. The
+markup is labelled and accessible without JS; the fallback for a visitor with
+JS off is the mailto address on the page, not a promise the form cannot keep.
+
+The form posts to the CMS form with the key `contact`. Create one with that key
+in your admin, or change `FORM_KEY` in `src/pages/contact.astro`. The hidden
+`website` field is a honeypot: bots fill it, the API drops those submissions.
+
+## Consent and analytics
+
+The banner asks once. The visit beacon does not fire until analytics consent
+exists, and it fires the moment it does, without a reload. A decline is a
+decision: the banner does not come back, and the site behaves identically.
+
+Both come from `@we8/astro`. The banner ships markup only; its styling lives in
+`global.css` under the `[data-we8-consent]` selectors.
+
+## Scripts
+
+| Command             | What it does                            |
+| ------------------- | --------------------------------------- |
+| `npm run dev`       | Dev server                              |
+| `npm run build`     | Static build into `dist/`               |
+| `npm run preview`   | Serve the built site                    |
+| `npm run typecheck` | `astro check`                           |
+| `npm run test`      | The data-layer and SEO tests            |
+
+## Dependencies
+
+`astro`, `@we8/astro`, and `marked`. That is the whole list. `marked` renders
+post bodies and has no dependencies of its own. Post content comes from your own
+CMS and is treated as trusted; if you ever accept markdown from anyone else,
+sanitize it before rendering.
+
+## More
+
+The we8 package documentation covers the rest. `quick-start.md` has the
+full-stack path from an empty directory to this site built against a live CMS,
+`frontend.md` covers the client, the integration, and this data-layer contract,
+and `api.md` is the `/v1` contract the we8 adapter speaks. Your own CMS also
+serves the machine-readable version at `GET /v1/openapi.json`.

package/template/astro.config.mjs

@@ -0,0 +1,23 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import { we8 } from '@we8/astro';
+
+// SITE is your public origin. It drives canonical URLs and the sitemap, and it
+// is separate from the CMS's own siteUrl: you can point this template at a
+// staging origin without touching the CMS.
+const site = process.env.SITE ?? 'https://northgatetools.example';
+
+export default defineConfig({
+  site,
+  // `optional: true` keeps a no-backend build quiet. This template is designed
+  // to build from fixtures when we8 is not configured, so a missing key is a
+  // choice, not a misconfiguration.
+  integrations: [we8({ optional: true })],
+  vite: {
+    // Astro exposes only PUBLIC_-prefixed variables on import.meta.env. Both
+    // we8 variables are public by design (a publishable key is meant to ship,
+    // and the API URL is not a secret), so widening the prefix means one
+    // variable serves the build and the browser instead of two.
+    envPrefix: ['PUBLIC_', 'WE8_'],
+  },
+});

package/template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "we8-template-astro",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "private": true,
+  "description": "The we8 Astro starter template: blog, content pages, resources, consent, forms, SEO and AEO, wired to the CMS by default and buildable from fixtures with no backend at all.",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "typecheck": "astro check",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@we8/astro": "^0.1.0",
+    "astro": "^7.2.7",
+    "marked": "^15.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.4",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/template/public/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-label="Site icon">
+  <rect width="32" height="32" rx="7" fill="#1f5c4c" />
+  <path d="M8 21.5 13 10h2.4l5 11.5h-2.6l-1-2.5h-5.2l-1 2.5H8Zm4.5-4.6h3.6l-1.8-4.4-1.8 4.4Z" fill="#ffffff" />
+  <circle cx="23" cy="11" r="2.2" fill="#7fc9b2" />
+</svg>

package/template/src/components/AnswerBlock.astro

@@ -0,0 +1,31 @@
+---
+/**
+ * The answer-first block: the question this page answers, and an answer short
+ * enough to be quoted whole.
+ *
+ * This is the visible half of AEO. It sits directly under the heading, before
+ * any preamble, so a reader gets the answer in one glance and an answer engine
+ * finds a self-contained paragraph next to the question it matches.
+ *
+ * A `derived` block is the site paraphrasing its own excerpt because no editor
+ * wrote an answer yet. It still helps the reader, so it renders; it is simply
+ * not offered to crawlers as FAQ markup (see `faqJsonLd`).
+ */
+import type { AnswerBlock } from '../lib/data.js';
+
+interface Props {
+  answer: AnswerBlock | null;
+  /** Render the question as a heading. Off on a post page, where the title is already the question. */
+  showQuestion?: boolean;
+}
+const { answer, showQuestion = true } = Astro.props;
+---
+
+{
+  answer && (
+    <div class="answer">
+      {showQuestion && <h2>{answer.question}</h2>}
+      <p>{answer.summary}</p>
+    </div>
+  )
+}

package/template/src/components/JsonLd.astro

@@ -0,0 +1,8 @@
+---
+/** One JSON-LD graph node. Pass `null` to render nothing. */
+interface Props {
+  data: Record<string, unknown> | null;
+}
+const { data } = Astro.props;
+---
+{data && <script is:inline type="application/ld+json" set:html={JSON.stringify(data)} />}

package/template/src/components/PostCard.astro

@@ -0,0 +1,24 @@
+---
+/** One post in a listing. Answer-first: the summary is the card's body. */
+import { answerFor, postPath, type Post } from '../lib/data.js';
+
+interface Props {
+  post: Post;
+}
+const { post } = Astro.props;
+const href = postPath(post);
+const answer = answerFor(post);
+const published = new Date(post.publishedAt);
+---
+
+<li class="card">
+  {post.category && <span class="tag">{post.category}</span>}
+  <h2><a href={href}>{post.title}</a></h2>
+  {answer && <p>{answer.summary}</p>}
+  <p class="meta">
+    <time datetime={post.publishedAt}>
+      {published.toLocaleDateString('en', { year: 'numeric', month: 'long', day: 'numeric' })}
+    </time>
+    {post.readingMinutes && <span> &middot; {post.readingMinutes} min read</span>}
+  </p>
+</li>

package/template/src/components/PostCta.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * The call to action attached to a post.
+ *
+ * A `link` CTA is a button. A `gated-download` CTA asks for an email through
+ * the site's form and then reveals the asset, which needs a live backend: with
+ * no backend configured the asset link is offered directly instead of putting
+ * a form in front of a submission that would go nowhere.
+ */
+import We8Form from '@we8/astro/We8Form.astro';
+import type { CallToAction, RuntimeConfig } from '../lib/data.js';
+
+interface Props {
+  cta: CallToAction | null;
+  runtime: RuntimeConfig;
+}
+const { cta, runtime } = Astro.props;
+const gated = cta?.style === 'gated-download' && cta.formKey !== null;
+const live = runtime.enabled && runtime.key !== null;
+---
+
+{
+  cta && (
+    <section class="answer" aria-label="Next step">
+      {cta.heading && <h2>{cta.heading}</h2>}
+
+      {cta.style === 'link' && cta.url && (
+        <p>
+          <a class="button" href={cta.url}>
+            {cta.buttonLabel}
+          </a>
+        </p>
+      )}
+
+      {gated && live && (
+        <We8Form
+          formKey={cta.formKey!}
+          key={runtime.key ?? undefined}
+          apiUrl={runtime.apiUrl ?? undefined}
+          successMessage="Check your inbox. The download link is on its way."
+        >
+          <div class="field">
+            <label for="cta-email">Work email</label>
+            <input id="cta-email" name="email" type="email" required autocomplete="email" />
+          </div>
+          <input type="hidden" name="asset" value={cta.assetUrl ?? ''} />
+          <button type="submit">{cta.buttonLabel}</button>
+        </We8Form>
+      )}
+
+      {gated && !live && cta.assetUrl && (
+        <p>
+          <a class="button" href={cta.assetUrl}>
+            {cta.buttonLabel}
+          </a>
+          <span class="meta"> (ungated: this build has no backend to collect an email)</span>
+        </p>
+      )}
+    </section>
+  )
+}

package/template/src/components/ResourceCard.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * One resource: a whitepaper, case study, or research note, with its download
+ * or link CTA surfaced on the card so the page reads as a shelf of things you
+ * can take away rather than another article list.
+ */
+import { answerFor, postPath, type Post } from '../lib/data.js';
+
+interface Props {
+  post: Post;
+}
+const { post } = Astro.props;
+const href = postPath(post);
+const answer = answerFor(post);
+
+const LABELS: Record<string, string> = {
+  whitepaper: 'Toolkit',
+  'case-study': 'Case study',
+  research: 'Research',
+};
+const label = LABELS[post.type] ?? 'Resource';
+const gated = post.cta?.style === 'gated-download';
+---
+
+<li class="card">
+  <span class="tag">{label}</span>
+  <h2><a href={href}>{post.title}</a></h2>
+  {answer && <p>{answer.summary}</p>}
+  <p class="meta">
+    {
+      post.cta
+        ? gated
+          ? 'Free download, email required'
+          : 'Free to read'
+        : 'Free to read'
+    }
+    {post.readingMinutes && <span> &middot; {post.readingMinutes} min read</span>}
+  </p>
+  <p><a class="button secondary" href={href}>{post.cta?.buttonLabel ?? 'Read it'}</a></p>
+</li>

package/template/src/components/SiteFooter.astro

@@ -0,0 +1,19 @@
+---
+interface Props {
+  siteName: string;
+  /** Which data source this build read from. Handy while you are wiring a backend. */
+  source: string;
+}
+const { siteName, source } = Astro.props;
+const year = new Date().getFullYear();
+---
+
+<footer class="site-footer">
+  <div class="shell">
+    <p>{year} {siteName}. Built with we8.</p>
+    <p>
+      <a href="/llms.txt">llms.txt</a> &middot; <a href="/sitemap.xml">Sitemap</a> &middot; content
+      source: {source}
+    </p>
+  </div>
+</footer>

package/template/src/components/SiteHead.astro

@@ -0,0 +1,36 @@
+---
+/**
+ * Everything that goes in <head> for one page: the resolved title and
+ * description, canonical, Open Graph, Twitter, and the robots directive.
+ *
+ * The values come from `resolveSeo`, which merges the page's own declarations
+ * over the site identity. This component never reads the backend.
+ */
+import type { ResolvedSeo } from '../lib/seo.js';
+
+interface Props {
+  seo: ResolvedSeo;
+  siteName: string;
+}
+const { seo, siteName } = Astro.props;
+---
+
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>{seo.title}</title>
+{seo.description && <meta name="description" content={seo.description} />}
+{seo.canonical && <link rel="canonical" href={seo.canonical} />}
+{seo.noindex && <meta name="robots" content="noindex, nofollow" />}
+
+<meta property="og:type" content="website" />
+<meta property="og:site_name" content={siteName} />
+<meta property="og:title" content={seo.ogTitle} />
+{seo.ogDescription && <meta property="og:description" content={seo.ogDescription} />}
+{seo.ogImageUrl && <meta property="og:image" content={seo.ogImageUrl} />}
+{seo.canonical && <meta property="og:url" content={seo.canonical} />}
+
+<meta name="twitter:card" content={seo.ogImageUrl ? 'summary_large_image' : 'summary'} />
+{seo.twitterHandle && <meta name="twitter:site" content={seo.twitterHandle} />}
+
+<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+<link rel="alternate" type="text/plain" href="/llms.txt" title="Site summary for answer engines" />

package/template/src/components/SiteHeader.astro

@@ -0,0 +1,34 @@
+---
+interface Props {
+  siteName: string;
+  path: string;
+}
+const { siteName, path } = Astro.props;
+
+const links = [
+  { href: '/', label: 'Home' },
+  { href: '/blog', label: 'Blog' },
+  { href: '/resources', label: 'Resources' },
+  { href: '/about', label: 'About' },
+  { href: '/contact', label: 'Contact' },
+];
+
+function isCurrent(href: string): boolean {
+  return href === '/' ? path === '/' : path === href || path.startsWith(`${href}/`);
+}
+---
+
+<header class="site-header">
+  <div class="shell">
+    <a class="wordmark" href="/">{siteName}</a>
+    <nav class="site-nav" aria-label="Main">
+      {
+        links.map((link) => (
+          <a href={link.href} aria-current={isCurrent(link.href) ? 'page' : undefined}>
+            {link.label}
+          </a>
+        ))
+      }
+    </nav>
+  </div>
+</header>

package/template/src/layouts/BaseLayout.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * The one layout. Every page renders through it.
+ *
+ * It takes the site identity and a `PageSeo` declaration, resolves the head,
+ * and wires the two browser-side pieces: the consent banner and the
+ * consent-gated visit beacon. Both come from `@we8/astro` and both are skipped
+ * entirely when `runtime.enabled` is false, so a fixtures build ships no dead
+ * analytics markup.
+ *
+ * A page may add its own JSON-LD through the `jsonLd` slot; the site-level
+ * Organization and WebSite nodes are emitted here so every page carries them.
+ */
+import ConsentBanner from '@we8/astro/ConsentBanner.astro';
+import VisitBeacon from '@we8/astro/VisitBeacon.astro';
+import JsonLd from '../components/JsonLd.astro';
+import SiteFooter from '../components/SiteFooter.astro';
+import SiteHead from '../components/SiteHead.astro';
+import SiteHeader from '../components/SiteHeader.astro';
+import { backend, runtime, type SiteIdentity } from '../lib/data.js';
+import { organizationJsonLd, resolveSeo, websiteJsonLd, type PageSeo } from '../lib/seo.js';
+import '../styles/global.css';
+
+interface Props {
+  identity: SiteIdentity;
+  seo: PageSeo;
+}
+const { identity, seo: pageSeo } = Astro.props;
+const seo = resolveSeo({ path: Astro.url.pathname, ...pageSeo }, identity);
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <SiteHead seo={seo} siteName={identity.name} />
+    <JsonLd data={organizationJsonLd(identity)} />
+    <JsonLd data={websiteJsonLd(identity)} />
+    <slot name="jsonLd" />
+  </head>
+  <body>
+    <a class="skip-link" href="#main">Skip to content</a>
+    <SiteHeader siteName={identity.name} path={Astro.url.pathname} />
+
+    <main id="main">
+      <div class="shell">
+        <slot />
+      </div>
+    </main>
+
+    <SiteFooter siteName={identity.name} source={backend.name} />
+
+    {
+      runtime.enabled && (
+        <>
+          <ConsentBanner key={runtime.key ?? undefined} apiUrl={runtime.apiUrl ?? undefined} />
+          <VisitBeacon key={runtime.key ?? undefined} apiUrl={runtime.apiUrl ?? undefined} />
+        </>
+      )
+    }
+  </body>
+</html>