@highjumpdigitalsoftware/blog-kit 0.6.0

package/templates/blogkit/blogkit.config.ts.tmpl

@@ -0,0 +1,23 @@
+import { defineConfig } from "@highjumpdigitalsoftware/blog-kit";
+
+/**
+ * blog-kit configuration for __BRAND__.
+ *
+ * SOURCE — where articles come from:
+ *   "hjd-api" : pull from High Jump Digital's content API (managed, live updates).
+ *               URL + token resolve from BLOGKIT_CONTENT_URL / BLOGKIT_SITE_TOKEN.
+ *   "local"   : read .mdx from content/posts/ in this repo (the EJECTED state).
+ *
+ * To eject later, flip mode to "local" and run `npx @highjumpdigitalsoftware/blog-kit eject`
+ * (downloads posts + images to this repo). Nothing else changes.
+ */
+export default defineConfig({
+  source: { mode: "__MODE__" },
+  brand: { name: "__BRAND__" },
+  listing: {
+    listingBasePath: "/blog",
+    articleBasePath: "/blog",
+    pageSize: 12,
+  },
+  freshness: { revalidate: 60 },
+});

package/templates/blogkit-astro/BLOGKIT_ASTRO_SETUP.md.tmpl

@@ -0,0 +1,49 @@
+# blog-kit on Astro — finish wiring (__BRAND__)
+
+`npx @highjumpdigitalsoftware/blog-kit connect` scaffolded your `/blog` routes + config. Two
+manual steps remain because they touch your `astro.config` and your host.
+
+## 1. Run Astro in SSR mode (required)
+
+The managed blog pulls content from our API at **request time** so new posts
+appear with **no redeploy**. That needs an on-demand (SSR) server, not a static
+export. In `astro.config.mjs`:
+
+```js
+import { defineConfig } from "astro/config";
+import node from "@astrojs/node"; // or @astrojs/vercel, @astrojs/netlify, etc.
+
+export default defineConfig({
+  output: "server",          // SSR — the blog renders on demand
+  adapter: node({ mode: "standalone" }),
+});
+```
+
+Install the adapter for your host:
+
+```bash
+npx astro add node      # generic Node server (Replit, Railway, a VPS)
+# or: npx astro add vercel / netlify / cloudflare
+```
+
+> The `/blog` and `/blog/[slug]` routes set `export const prerender = false`, so
+> only the blog is server-rendered — the rest of your site can stay static if
+> you prefer `output: "hybrid"`.
+
+## 2. Set the secrets on your host
+
+```
+BLOGKIT_CONTENT_URL = <your per-tenant content URL>
+BLOGKIT_SITE_TOKEN  = <your site token>          # secret — never commit
+BLOGKIT_REVALIDATE_SECRET = <optional>           # enables instant publish updates
+```
+
+On Replit use the Secrets panel; on Vercel/Netlify use Environment Variables.
+(`connect` wrote them to `.env` for local dev — your host needs its own copy.)
+
+## 3. Deploy + verify
+
+Deploy once. Visit `/blog` — your articles render, pulled live from our API.
+Publish a new article in the High Jump Digital app and it appears within
+`freshness.revalidate` seconds (or instantly if `BLOGKIT_REVALIDATE_SECRET` is
+set). No redeploy, ever.

package/templates/blogkit-astro/src/blogkit.config.ts.tmpl

@@ -0,0 +1,29 @@
+import { defineConfig } from "@highjumpdigitalsoftware/blog-kit/astro";
+
+/**
+ * blog-kit configuration for __BRAND__ (Astro).
+ *
+ * SOURCE — where articles come from:
+ *   "hjd-api" : pull from High Jump Digital's content API (managed, live updates).
+ *               URL + token resolve from BLOGKIT_CONTENT_URL / BLOGKIT_SITE_TOKEN.
+ *   "local"   : read .mdx from content/posts/ in this repo (the EJECTED state).
+ *
+ * FRESHNESS — Astro has no ISR. Run this site in SSR mode
+ * (`output: 'server'` in astro.config) so the blog is always fresh with no
+ * redeploy. `freshness.revalidate` is the in-process cache TTL (seconds) the
+ * kit uses to avoid hitting our API on every request; the scaffolded
+ * /api/blogkit/revalidate endpoint busts it instantly on publish.
+ *
+ * To eject later, flip mode to "local" and run `npx @highjumpdigitalsoftware/blog-kit eject`
+ * (downloads posts + images to this repo). Nothing else changes.
+ */
+export default defineConfig({
+  source: { mode: "__MODE__" },
+  brand: { name: "__BRAND__" },
+  listing: {
+    listingBasePath: "/blog",
+    articleBasePath: "/blog",
+    pageSize: 12,
+  },
+  freshness: { revalidate: 60 },
+});

package/templates/blogkit-astro/src/pages/api/blogkit/revalidate.ts.tmpl

@@ -0,0 +1,46 @@
+// blog-kit on-demand revalidation endpoint (Astro). Scaffolded by `npx @highjumpdigitalsoftware/blog-kit connect`.
+// High Jump Digital POSTs here on publish to bust the kit's freshness cache
+// instantly (otherwise the cache refreshes within `freshness.revalidate`
+// seconds on the next request — Astro's ISR-equivalent).
+//
+// Astro has no `revalidatePath`; in SSR the "cache" is the kit's in-process
+// freshness store, so revalidation = clearBlogkitCache(). After it clears, the
+// very next request re-fetches from the content API.
+//
+// Auth: a shared secret in BLOGKIT_REVALIDATE_SECRET, sent as the
+// `x-blogkit-secret` header. Without the secret set the endpoint refuses, so an
+// un-provisioned site can't have its cache poked.
+import type { APIRoute } from "astro";
+import { clearBlogkitCache } from "@highjumpdigitalsoftware/blog-kit/astro";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ request }) => {
+  const secret = import.meta.env.BLOGKIT_REVALIDATE_SECRET;
+  if (!secret) {
+    return new Response(
+      JSON.stringify({ ok: false, error: "not_configured" }),
+      { status: 503, headers: { "content-type": "application/json" } },
+    );
+  }
+  if (request.headers.get("x-blogkit-secret") !== secret) {
+    return new Response(
+      JSON.stringify({ ok: false, error: "unauthorized" }),
+      { status: 401, headers: { "content-type": "application/json" } },
+    );
+  }
+
+  let body: { slug?: string } = {};
+  try {
+    body = await request.json();
+  } catch {
+    /* empty body = revalidate everything */
+  }
+
+  clearBlogkitCache();
+
+  return new Response(
+    JSON.stringify({ ok: true, revalidated: body.slug ?? "all" }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
+};

package/templates/blogkit-astro/src/pages/blog/[slug].astro.tmpl

@@ -0,0 +1,39 @@
+---
+// blog-kit article route (/blog/[slug]) — Astro SSR. Scaffolded by `npx @highjumpdigitalsoftware/blog-kit connect`.
+//
+// The MDX body is fetched from the content API and COMPILED AT REQUEST TIME
+// (see @highjumpdigitalsoftware/blog-kit/astro -> renderMdxToHtml), so a freshly published
+// post renders with no redeploy. SSR + dynamic [slug] means unknown slugs
+// render on demand — no getStaticPaths needed.
+import "@highjumpdigitalsoftware/blog-kit/styles.css";
+import { resolveConfig, loadArticle } from "@highjumpdigitalsoftware/blog-kit/astro";
+import Article from "@highjumpdigitalsoftware/blog-kit/astro/Article.astro";
+import rawConfig from "../../blogkit.config";
+
+export const prerender = false; // SSR — render the post at request time
+
+const config = resolveConfig(rawConfig);
+const { slug } = Astro.params;
+const data = slug ? await loadArticle(config, slug) : null;
+
+if (!data) {
+  return new Response("Not found", { status: 404 });
+}
+
+const { post } = data;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{post.title} · {config.brand.name}</title>
+    <meta name="description" content={post.description} />
+  </head>
+  <body>
+    <main style="max-width:900px;margin:0 auto;padding:120px 20px 80px">
+      <h1 style="margin-bottom:24px">{post.title}</h1>
+      <Article data={data} config={config} />
+    </main>
+  </body>
+</html>

package/templates/blogkit-astro/src/pages/blog/index.astro.tmpl

@@ -0,0 +1,29 @@
+---
+// blog-kit listing route (/blog) — Astro SSR. Scaffolded by `npx @highjumpdigitalsoftware/blog-kit connect`.
+//
+// SSR (output:'server') = always fresh: new posts appear with NO redeploy
+// (the kit's freshness cache serves cached for `freshness.revalidate` seconds,
+// and the /api/blogkit/revalidate endpoint busts it instantly on publish).
+import "@highjumpdigitalsoftware/blog-kit/styles.css";
+import { resolveConfig, loadIndex } from "@highjumpdigitalsoftware/blog-kit/astro";
+import BlogIndex from "@highjumpdigitalsoftware/blog-kit/astro/BlogIndex.astro";
+import rawConfig from "../../blogkit.config";
+
+export const prerender = false; // SSR — pulls from the content API at request time
+
+const config = resolveConfig(rawConfig);
+const data = await loadIndex(config, 1);
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Blog · {config.brand.name}</title>
+  </head>
+  <body>
+    <main style="max-width:1100px;margin:0 auto;padding:80px 20px">
+      <BlogIndex data={data} config={config} />
+    </main>
+  </body>
+</html>