create-we8 0.1.0

package/template/src/layouts/PostLayout.astro

@@ -0,0 +1,128 @@
+---
+/**
+ * A single piece of content, whichever section it lives in.
+ *
+ * The page order is the AEO order: title, then the answer, then the byline,
+ * then a question-shaped table of contents, then the body. A reader who wants
+ * only the answer gets it above the fold; a crawler finds a self-contained
+ * summary next to the question and an outline it can cite by anchor.
+ */
+import AnswerBlock from '../components/AnswerBlock.astro';
+import JsonLd from '../components/JsonLd.astro';
+import PostCta from '../components/PostCta.astro';
+import BaseLayout from './BaseLayout.astro';
+import {
+  answerFor,
+  authorPath,
+  postPath,
+  postUrl,
+  runtime,
+  type Author,
+  type Post,
+  type SiteIdentity,
+} from '../lib/data.js';
+import { renderBody } from '../lib/markdown.js';
+import { articleJsonLd, breadcrumbJsonLd, faqJsonLd } from '../lib/seo.js';
+
+interface Props {
+  post: Post;
+  byline: Author[];
+  identity: SiteIdentity;
+  /** The section this post is listed under, for the breadcrumb. */
+  section: { name: string; path: string };
+}
+const { post, byline, identity, section } = Astro.props;
+
+const answer = answerFor(post);
+const { html, headings } = renderBody(post.content);
+const url = postUrl(post, identity);
+const published = new Date(post.publishedAt);
+---
+
+<BaseLayout
+  identity={identity}
+  seo={{
+    title: post.title,
+    description: answer?.summary ?? post.excerpt ?? undefined,
+    ogImageUrl: post.coverImageUrl ?? undefined,
+    path: postPath(post),
+  }}
+>
+  <Fragment slot="jsonLd">
+    <JsonLd data={articleJsonLd(post, url, byline, identity)} />
+    <JsonLd data={faqJsonLd([answer])} />
+    <JsonLd
+      data={breadcrumbJsonLd(
+        [{ name: 'Home', path: '/' }, section, { name: post.title, path: postPath(post) }],
+        identity,
+      )}
+    />
+  </Fragment>
+
+  <article class="stack">
+    <header class="prose">
+      {post.category && <span class="tag">{post.category}</span>}
+      <h1>{post.title}</h1>
+    </header>
+
+    <AnswerBlock answer={answer} showQuestion={false} />
+
+    <p class="meta">
+      {
+        byline.length > 0 && (
+          <span>
+            By{' '}
+            {byline.map((author, index) => (
+              <>
+                {index > 0 && ', '}
+                <a href={authorPath(author)}>{author.name}</a>
+              </>
+            ))}
+            {' · '}
+          </span>
+        )
+      }
+      <time datetime={post.publishedAt}>
+        {published.toLocaleDateString('en', { year: 'numeric', month: 'long', day: 'numeric' })}
+      </time>
+      {post.readingMinutes && <span>{' · '}{post.readingMinutes} min read</span>}
+    </p>
+
+    {
+      post.coverImageUrl && (
+        <img src={post.coverImageUrl} alt="" width="1200" height="630" loading="eager" />
+      )
+    }
+
+    {
+      headings.length > 2 && (
+        <nav class="toc" aria-label="On this page">
+          <h2>On this page</h2>
+          <ol>
+            {headings
+              .filter((heading) => heading.depth === 2)
+              .map((heading) => (
+                <li>
+                  <a href={`#${heading.id}`}>{heading.text}</a>
+                </li>
+              ))}
+          </ol>
+        </nav>
+      )
+    }
+
+    <div class="prose" set:html={html} />
+
+    <PostCta cta={post.cta} runtime={runtime} />
+
+    {
+      post.tags.length > 0 && (
+        <p class="meta">
+          Tagged: {post.tags.join(', ')}
+        </p>
+      )
+    }
+
+    <p><a href={section.path}>Back to {section.name.toLowerCase()}</a></p>
+  </article>
+</BaseLayout>

package/template/src/lib/data.ts

@@ -0,0 +1,217 @@
+/**
+ * THE DATA LAYER.
+ *
+ * Every page and component in this template gets its content from here and
+ * from nowhere else. This module picks a backend, exposes the contract from
+ * `types.ts`, and adds the handful of derived values pages need (paths, the
+ * answer block, the resources list).
+ *
+ * It contains no we8 imports of its own: the we8 adapter lives in
+ * `we8-backend.ts`, the static one in `fixture-backend.ts`, and this file just
+ * chooses. To point the site at something else, write a third backend and add
+ * it to `selectBackend` below.
+ */
+import { createFixtureBackend } from './fixture-backend.js';
+import { resolveWe8Backend, resolveWe8Runtime } from './we8-backend.js';
+import { RESOURCE_TYPES } from './types.js';
+import type {
+  AnswerBlock,
+  Author,
+  ContentType,
+  DocumentKind,
+  Post,
+  PostPage,
+  PostQuery,
+  RuntimeConfig,
+  SiteBackend,
+  SiteIdentity,
+} from './types.js';
+
+export type {
+  AnswerBlock,
+  Author,
+  AuthorLink,
+  CallToAction,
+  ContentType,
+  DocumentKind,
+  Post,
+  PostPage,
+  PostQuery,
+  RuntimeConfig,
+  SiteBackend,
+  SiteIdentity,
+  SiteSeo,
+} from './types.js';
+export { CONTENT_TYPES, RESOURCE_TYPES } from './types.js';
+
+type EnvRecord = Record<string, string | undefined>;
+
+/**
+ * Astro exposes `PUBLIC_`-prefixed variables on `import.meta.env`; this
+ * template widens `envPrefix` in `astro.config.mjs` so `WE8_`-prefixed ones
+ * come through too. `process.env` is the fallback for plain Node, which is how
+ * the tests and any script outside Astro read the same configuration.
+ */
+function readEnv(): EnvRecord {
+  const fromAstro = import.meta.env as unknown as EnvRecord;
+  const fromNode = (globalThis as { process?: { env?: EnvRecord } }).process?.env ?? {};
+  return { ...fromNode, ...fromAstro };
+}
+
+/**
+ * Pick a backend.
+ *
+ * `WE8_DATA_SOURCE=fixtures` forces the static one even with a live API
+ * configured, which is what makes an offline build reproducible. Otherwise a
+ * complete we8 configuration wins, and an incomplete one falls back rather
+ * than failing the build: a template that cannot build without a backend is
+ * not backend-agnostic.
+ */
+export function selectBackend(env: EnvRecord): SiteBackend {
+  if (env['WE8_DATA_SOURCE'] === 'fixtures') return createFixtureBackend();
+  return resolveWe8Backend(env) ?? createFixtureBackend();
+}
+
+/** The browser-side configuration, or a disabled one when nothing is live. */
+export function selectRuntime(env: EnvRecord): RuntimeConfig {
+  if (env['WE8_DATA_SOURCE'] === 'fixtures') return { enabled: false, key: null, apiUrl: null };
+  return resolveWe8Runtime(env);
+}
+
+const env = readEnv();
+
+/** The backend this build is reading from. */
+export const backend: SiteBackend = selectBackend(env);
+
+/**
+ * How the browser talks to the backend. When `enabled` is false the form, the
+ * consent banner, and the visit beacon are not rendered at all: a dead form is
+ * worse than no form.
+ */
+export const runtime: RuntimeConfig = selectRuntime(env);
+
+/* -------------------------------------------------------------------------- */
+/* Content                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export function getIdentity(): Promise<SiteIdentity> {
+  return backend.identity();
+}
+
+export function getPosts(query?: PostQuery): Promise<PostPage> {
+  return backend.listPosts(query);
+}
+
+export function getAllPosts(): Promise<Post[]> {
+  return backend.listAllPosts();
+}
+
+/** Editorial content: what the blog lists. */
+export async function getArticles(): Promise<Post[]> {
+  const posts = await backend.listAllPosts();
+  return posts.filter((post) => !RESOURCE_TYPES.includes(post.type));
+}
+
+/** Long-form material: what the resources page lays out. */
+export async function getResources(): Promise<Post[]> {
+  const posts = await backend.listAllPosts();
+  return posts.filter((post) => RESOURCE_TYPES.includes(post.type));
+}
+
+export function getPost(slug: string): Promise<Post | null> {
+  return backend.getPost(slug);
+}
+
+export function getAuthors(): Promise<Author[]> {
+  return backend.listAuthors();
+}
+
+export function getAuthor(slug: string): Promise<Author | null> {
+  return backend.getAuthor(slug);
+}
+
+export async function getPostsByAuthor(slug: string): Promise<Post[]> {
+  const posts = await backend.listAllPosts();
+  return posts.filter((post) => post.authorSlugs.includes(slug));
+}
+
+export function getDocument(kind: DocumentKind): Promise<string> {
+  return backend.getDocument(kind);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Derived values                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The section this template serves each content type under.
+ *
+ * This is the template's own routing, and it is deliberately not read from the
+ * backend: `identity.contentPaths` is what the CMS believes the site's URLs
+ * are, which is advice, and following advice that disagrees with the pages
+ * this site actually renders would produce links to 404s. Change these values
+ * and rename the matching folders under `src/pages` together.
+ */
+export const SECTIONS: Record<ContentType, string> = {
+  blog: '/blog',
+  article: '/blog',
+  news: '/blog',
+  research: '/resources',
+  whitepaper: '/resources',
+  'case-study': '/resources',
+};
+
+/** The site-relative path a post is published at, for example `/blog/my-post`. */
+export function postPath(post: Pick<Post, 'slug' | 'type'>): string {
+  return `${SECTIONS[post.type]}/${post.slug}`;
+}
+
+/** The absolute URL a post is published at. */
+export function postUrl(post: Pick<Post, 'slug' | 'type'>, identity: SiteIdentity): string {
+  return `${identity.siteUrl}${postPath(post)}`;
+}
+
+export function authorPath(author: Pick<Author, 'slug'>): string {
+  return `/authors/${author.slug}`;
+}
+
+/**
+ * The answer-first block for a post, deriving one from the title and excerpt
+ * when the backend carries no authored answer. A derived block still leads
+ * with a short summary, which is the reader-facing half of AEO; it is marked
+ * `derived` so the JSON-LD does not present it as a curated answer.
+ */
+export function answerFor(post: Post): AnswerBlock | null {
+  if (post.answer) return post.answer;
+  if (!post.excerpt) return null;
+  return { question: post.title, summary: post.excerpt, source: 'derived' };
+}
+
+/** Resolve the byline of a post against the author roster. */
+export function bylineFor(post: Post, authors: Author[]): Author[] {
+  return post.authorSlugs
+    .map((slug) => authors.find((author) => author.slug === slug))
+    .filter((author): author is Author => author !== undefined);
+}
+
+/** The distinct content types present in a set of posts, in vocabulary order. */
+export function typesPresent(posts: Post[]): ContentType[] {
+  const present = new Set(posts.map((post) => post.type));
+  return RESOURCE_TYPES.filter((type) => present.has(type));
+}
+
+/** Every absolute URL that belongs in the sitemap, site pages plus content. */
+export async function getSitemapUrls(staticPaths: readonly string[]): Promise<string[]> {
+  const identity = await backend.identity();
+  const posts = await backend.listAllPosts();
+  const authors = await backend.listAuthors();
+  const own = [
+    ...staticPaths.map((path) => `${identity.siteUrl}${path}`),
+    ...posts.map((post) => postUrl(post, identity)),
+    ...authors.map((author) => `${identity.siteUrl}${authorPath(author)}`),
+  ];
+  // Anything the backend publishes that this site does not render. Merging it
+  // here is what keeps one sitemap authoritative instead of two partial ones.
+  const extra = await backend.extraSitemapUrls(identity.siteUrl);
+  return [...new Set([...own, ...extra])];
+}

package/template/src/lib/fixture-backend.ts

@@ -0,0 +1,84 @@
+/**
+ * The fixture backend: the data-layer contract implemented over static data.
+ *
+ * It exists for two reasons. It lets the template build and run with no CMS at
+ * all, which is what `npm run dev` does out of the box. And it is the proof
+ * that the contract in `types.ts` is real: two independent implementations,
+ * one interface, and every page written against the interface.
+ */
+import { authors, identity, llmsTxt, posts } from './fixtures.js';
+import type {
+  Author,
+  DocumentKind,
+  Post,
+  PostPage,
+  PostQuery,
+  SiteBackend,
+  SiteIdentity,
+} from './types.js';
+
+function byNewest(a: Post, b: Post): number {
+  return b.publishedAt.localeCompare(a.publishedAt);
+}
+
+function matches(post: Post, query: PostQuery): boolean {
+  if (query.type && post.type !== query.type) return false;
+  if (query.tag && !post.tags.includes(query.tag)) return false;
+  if (query.category && post.category !== query.category) return false;
+  return true;
+}
+
+export function createFixtureBackend(): SiteBackend {
+  const all = [...posts].sort(byNewest);
+
+  return {
+    name: 'fixtures',
+
+    identity(): Promise<SiteIdentity> {
+      return Promise.resolve(identity);
+    },
+
+    listPosts(query: PostQuery = {}): Promise<PostPage> {
+      const filtered = all.filter((post) => matches(post, query));
+      const page = Math.max(1, query.page ?? 1);
+      const pageSize = Math.max(1, query.pageSize ?? 10);
+      const start = (page - 1) * pageSize;
+      return Promise.resolve({
+        items: filtered.slice(start, start + pageSize),
+        page,
+        pageSize,
+        total: filtered.length,
+      });
+    },
+
+    listAllPosts(): Promise<Post[]> {
+      return Promise.resolve(all);
+    },
+
+    getPost(slug: string): Promise<Post | null> {
+      return Promise.resolve(all.find((post) => post.slug === slug) ?? null);
+    },
+
+    listAuthors(): Promise<Author[]> {
+      // Only authors with at least one published post, so the fixture set and
+      // a live CMS behave the same way: an author page with nothing on it is
+      // a dead end either way.
+      const bylined = new Set(all.flatMap((post) => post.authorSlugs));
+      return Promise.resolve(authors.filter((author) => bylined.has(author.slug)));
+    },
+
+    getAuthor(slug: string): Promise<Author | null> {
+      return Promise.resolve(authors.find((author) => author.slug === slug) ?? null);
+    },
+
+    getDocument(kind: DocumentKind): Promise<string> {
+      return Promise.resolve(kind === 'llms-txt' ? llmsTxt : '');
+    },
+
+    extraSitemapUrls(): Promise<string[]> {
+      // The fixture set is fully rendered by this site, so there is nothing to
+      // merge in.
+      return Promise.resolve([]);
+    },
+  };
+}