create-volt 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `create-volt` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.31.0] - 2026-06-29
+
+### Added
+- **`posts` add-on — a blog (the WordPress content model).** Markdown in `posts/`
+  becomes a paginated index at `/blog`, single posts at `/blog/<slug>`, plus
+  `/category/<name>`, `/tag/<name>`, and an RSS feed at `/feed.xml`. Posts carry
+  date/author/category/tags front-matter (date can also come from a
+  `YYYY-MM-DD-` filename prefix); drafts (`draft: true`) are skipped. Renders in
+  the site theme and reuses pages' SEO — single posts get an auto Article
+  JSON-LD + `og:type=article`. Depends on the `pages` add-on. New `/docs/posts`.
+
 ## [0.30.0] - 2026-06-29
 
 ### Fixed
@@ -413,6 +424,7 @@ All notable changes to `create-volt` are documented here. The format follows
   watching and full-page hot reload. Supports `--skip-install` and `--force`,
   and auto-detects npm / pnpm / yarn / bun for the install step.
 
+[0.31.0]: https://github.com/MIR-2025/volt/releases/tag/v0.31.0
 [0.30.0]: https://github.com/MIR-2025/volt/releases/tag/v0.30.0
 [0.29.0]: https://github.com/MIR-2025/volt/releases/tag/v0.29.0
 [0.28.0]: https://github.com/MIR-2025/volt/releases/tag/v0.28.0

package/addons/pages/files/lib/pages.js

@@ -52,7 +52,7 @@ export function parseFrontMatter(src) {
 export const isSafeSlug = (s) => /^[a-z0-9][a-z0-9-]*$/i.test(s);
 
 // SEO/social head from front-matter: description, image, type, canonical, jsonld.
-function metaHead(meta) {
+export function metaHead(meta) {
   const t = [];
   const title = meta.title || "";
   const desc = meta.description || "";
@@ -117,7 +117,7 @@ function themeCss(dir) {
 // local pages/_theme.js; else the built-in default. A theme may `export const css`
 // (served at /_theme.css, shared with the editor); otherwise pages/_theme.css or
 // the default CSS is used.
-async function loadTheme(dir, env) {
+export async function loadTheme(dir, env) {
   const wrap = (m) => {
     const layout = m && (m.layout || m.default);
     return layout ? { layout, css: m.css || themeCss(dir) } : null;

package/addons/posts/files/lib/posts.js

@@ -0,0 +1,168 @@
+// posts.js — a blog content type. Markdown files in posts/ become a paginated
+// index at /blog, single posts at /blog/<slug>, plus /category/<name>,
+// /tag/<name>, and an RSS feed at /feed.xml. Renders in the site theme and
+// reuses pages' front-matter + SEO helpers (OG, Twitter, JSON-LD).
+import fs from "node:fs";
+import path from "node:path";
+// express + marked are imported lazily in postsRouter() so the pure helpers load
+// without those deps. Theme + SEO come from the pages add-on (a dependency).
+import { parseFrontMatter, isSafeSlug, metaHead, loadTheme } from "../../../pages/files/lib/pages.js";
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const slugify = (s) => String(s).toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+const postLink = (slug) => "/blog/" + slug;
+const catLink = (c) => `<a href="/category/${slugify(c)}">${esc(c)}</a>`;
+const tagLink = (t) => `<a class="post-tag" href="/tag/${slugify(t)}">${esc(t)}</a>`;
+const tagsOf = (meta) => String(meta.tags || "").split(",").map((s) => s.trim()).filter(Boolean);
+
+function fmtDate(d) {
+  if (!d) return "";
+  const t = new Date(d);
+  return isNaN(t.getTime()) ? esc(d) : t.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" });
+}
+
+function excerpt(p) {
+  if (p.meta.description) return p.meta.description;
+  const text = String(p.body).replace(/<[^>]+>/g, " ").replace(/[#>*_`[\]()!]+/g, " ").replace(/\s+/g, " ").trim();
+  return text.slice(0, 160) + (text.length > 160 ? "…" : "");
+}
+
+// Read + parse every post, newest first. Date comes from front-matter `date:` or
+// a YYYY-MM-DD- filename prefix; slug from front-matter `slug:` or the filename
+// (prefix stripped). Drafts (draft: true) are skipped.
+export function readPosts(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".md")) continue;
+    const { meta, body } = parseFrontMatter(fs.readFileSync(path.join(dir, f), "utf8"));
+    if (String(meta.draft).toLowerCase() === "true") continue;
+    let name = f.replace(/\.md$/, "");
+    let date = meta.date || "";
+    const m = name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
+    if (m) {
+      if (!date) date = m[1];
+      name = m[2];
+    }
+    const slug = slugify(meta.slug || name);
+    if (!isSafeSlug(slug)) continue;
+    out.push({ slug, date, meta, body });
+  }
+  return out.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+}
+
+function renderList(posts, { heading, page = 1, totalPages = 1, baseUrl }) {
+  const items = posts.length
+    ? posts
+        .map(
+          (p) => `<li class="post-item" style="margin:0 0 1.5rem">
+    <a href="${postLink(p.slug)}" style="font-size:1.2rem;font-weight:600">${esc(p.meta.title || p.slug)}</a>
+    <div class="post-meta" style="opacity:.7;font-size:.9rem">${fmtDate(p.date)}${p.meta.category ? " &middot; " + catLink(p.meta.category) : ""}</div>
+    <p style="margin:.3rem 0 0">${esc(excerpt(p))}</p>
+  </li>`,
+        )
+        .join("\n")
+    : "<li>No posts yet.</li>";
+  let nav = "";
+  if (totalPages > 1) {
+    const prev = page > 1 ? `<a href="${baseUrl}?page=${page - 1}">&larr; Newer</a>` : "<span></span>";
+    const next = page < totalPages ? `<a href="${baseUrl}?page=${page + 1}" style="margin-left:auto">Older &rarr;</a>` : "";
+    nav = `<nav class="post-pager" style="display:flex;margin-top:1.5rem">${prev}${next}</nav>`;
+  }
+  return `<h1>${esc(heading)}</h1><ul class="post-list" style="list-style:none;padding:0">${items}</ul>${nav}`;
+}
+
+function renderPost(p, marked) {
+  const title = p.meta.title || p.slug;
+  const body = p.meta.format === "html" ? p.body : marked.parse(p.body);
+  const tags = tagsOf(p.meta);
+  const meta = `<div class="post-meta" style="opacity:.7;font-size:.9rem;margin-bottom:1rem">${fmtDate(p.date)}${p.meta.author ? " &middot; " + esc(p.meta.author) : ""}${p.meta.category ? " &middot; " + catLink(p.meta.category) : ""}</div>`;
+  const tagHtml = tags.length ? `<div class="post-tags" style="margin-top:1.5rem">Tags: ${tags.map(tagLink).join(" ")}</div>` : "";
+  return `<article><h1>${esc(title)}</h1>${meta}${body}${tagHtml}</article>`;
+}
+
+function feedXml(posts) {
+  const base = (process.env.SITE_URL || "").replace(/\/+$/, "");
+  const name = process.env.SITE_NAME || "Blog";
+  const items = posts
+    .slice(0, 20)
+    .map(
+      (p) => `  <item>
+    <title>${esc(p.meta.title || p.slug)}</title>
+    <link>${esc(base + postLink(p.slug))}</link>
+    <guid isPermaLink="${base ? "true" : "false"}">${esc(base + postLink(p.slug))}</guid>${p.date && !isNaN(new Date(p.date).getTime()) ? `\n    <pubDate>${new Date(p.date).toUTCString()}</pubDate>` : ""}
+    <description>${esc(excerpt(p))}</description>
+  </item>`,
+    )
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0"><channel>
+  <title>${esc(name)}</title>
+  <link>${esc(base + "/blog")}</link>
+  <description>${esc(name)} — posts</description>
+${items}
+</channel></rss>`;
+}
+
+export async function postsRouter({ dir, themeDir }) {
+  const express = (await import("express")).default;
+  const { marked } = await import("marked");
+  fs.mkdirSync(dir, { recursive: true });
+  const { layout } = await loadTheme(themeDir || dir, process.env); // same theme as pages
+  const PER = Math.max(1, Number(process.env.POSTS_PER_PAGE) || 10);
+  const render = ({ title, content, meta = {} }) => {
+    const m = { ...meta, title };
+    return layout({ title, head: metaHead(m), content, meta: m });
+  };
+  const r = express.Router();
+
+  r.get("/blog", (req, res) => {
+    const all = readPosts(dir);
+    const page = Math.max(1, parseInt(req.query.page, 10) || 1);
+    const totalPages = Math.max(1, Math.ceil(all.length / PER));
+    const slice = all.slice((page - 1) * PER, page * PER);
+    const heading = process.env.SITE_NAME || "Blog";
+    res.type("html").send(render({ title: heading, meta: { description: heading + " — latest posts" }, content: renderList(slice, { heading, page, totalPages, baseUrl: "/blog" }) }));
+  });
+
+  r.get("/blog/:slug", (req, res, next) => {
+    if (!isSafeSlug(req.params.slug)) return next();
+    const post = readPosts(dir).find((p) => p.slug === req.params.slug);
+    if (!post) return next();
+    const title = post.meta.title || post.slug;
+    const autoLd = JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "Article",
+      headline: title,
+      ...(post.date ? { datePublished: post.date } : {}),
+      ...(post.meta.author ? { author: { "@type": "Person", name: post.meta.author } } : {}),
+    });
+    res.type("html").send(
+      render({
+        title,
+        meta: { ...post.meta, title, type: "article", jsonld: post.meta.jsonld || autoLd },
+        content: renderPost(post, marked),
+      }),
+    );
+  });
+
+  r.get("/category/:name", (req, res, next) => {
+    if (!isSafeSlug(req.params.name)) return next();
+    const list = readPosts(dir).filter((p) => slugify(p.meta.category) === req.params.name);
+    if (!list.length) return next();
+    res.type("html").send(render({ title: "Category: " + req.params.name, content: renderList(list, { heading: "Category: " + req.params.name, baseUrl: "/category/" + req.params.name }) }));
+  });
+
+  r.get("/tag/:name", (req, res, next) => {
+    if (!isSafeSlug(req.params.name)) return next();
+    const list = readPosts(dir).filter((p) => tagsOf(p.meta).some((t) => slugify(t) === req.params.name));
+    if (!list.length) return next();
+    res.type("html").send(render({ title: "Tag: " + req.params.name, content: renderList(list, { heading: "Tag: " + req.params.name, baseUrl: "/tag/" + req.params.name }) }));
+  });
+
+  r.get("/feed.xml", (_req, res) => {
+    res.type("application/rss+xml").send(feedXml(readPosts(dir)));
+  });
+
+  return r;
+}

package/addons/posts/meta.json

@@ -0,0 +1,8 @@
+{
+  "description": "Blog posts with dates, authors, tags + categories. Drop markdown in posts/ → a paginated index at /blog, single posts at /blog/<slug>, /category/<name>, /tag/<name>, and an RSS feed at /feed.xml. Renders in your site theme and reuses pages' SEO (OG + JSON-LD).",
+  "dependsOn": ["pages"],
+  "sentinel": "lib/posts.js",
+  "install": ["marked"],
+  "optional": {},
+  "wiring": "Add markdown files to posts/ (created on first run), e.g. posts/2026-06-29-hello.md with front-matter: title, date, author, category, tags (comma-separated), description. The date can also come from a YYYY-MM-DD- filename prefix. Set SITE_URL in .env for absolute links in the RSS feed; POSTS_PER_PAGE (default 10) controls pagination."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {

package/templates/default/server.js

@@ -1,9 +1,9 @@
-// server.js — dev server with a built-in first-run setup wizard.
+// server.js — dev server with a built-in first-run setup wizard.
 //
 // First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
 // config page: tick add-ons, fill settings, Apply. Apply writes .env (a
 // VOLT_ADDONS list + settings) and adds any needed packages to package.json,
-// runs npm install, then starts the app — which wires whatever .env enables.
+// runs npm install, then starts the app — which wires whatever .env enables.
 // Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
@@ -22,7 +22,7 @@ const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", media: "media.js" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", posts: "posts.js", media: "media.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -67,7 +67,7 @@ const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
 // Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
-// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
 // npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
 const BUILTINS = new Set(Object.keys(LIB_FILE));
 async function loadAddon(name) {
@@ -91,7 +91,7 @@ function openBrowser(url) {
   const args = plat === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -134,14 +134,16 @@ async function startApp() {
     app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
   }
 
-  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
+  if (enabled.has("posts")) app.use(await (await addonMod("posts")).postsRouter({ dir: path.join(__dirname, "posts"), themeDir: path.join(__dirname, "pages") }));
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
   const server = http.createServer(app);
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
+  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
   // are provided so add-ons can gate routes by login.
   let requireAuth = null;
   let sessionFromReq = null;
@@ -157,7 +159,7 @@ async function startApp() {
     if (typeof register === "function") {
       await register({ app, express, io, store, mailer, env: process.env, requireAuth, sessionFromReq, log: (...a) => console.log(`[${name}]`, ...a) });
     } else {
-      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
     }
   }
 
@@ -165,7 +167,7 @@ async function startApp() {
   const onChange = (file) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
-      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
       io.emit("volt:reload");
     }, 80);
   };
@@ -189,7 +191,7 @@ async function startApp() {
   for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
 
   const on = [...enabled];
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
 // Packages an .env's selections need, beyond what package.json already has.
@@ -202,7 +204,7 @@ function neededPackages(env) {
   if (driver === "mysql") want.push("mysql2");
   if (driver === "postgres") want.push("pg");
   if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
-  if (/^\s*VOLT_ADDONS\s*=.*\bpages\b/m.test(env)) want.push("marked");
+  if (/^\s*VOLT_ADDONS\s*=.*\b(pages|posts)\b/m.test(env)) want.push("marked");
   if (/^\s*VOLT_ADDONS\s*=.*\bmedia\b/m.test(env)) want.push("busboy");
   if (/^\s*MEDIA_DRIVER\s*=\s*s3\b/m.test(env)) want.push("@aws-sdk/client-s3");
   return want.filter((p) => !deps[p]);
@@ -213,7 +215,7 @@ function neededPackages(env) {
 function ensureDriverInstalled(driver) {
   const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
   if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
-  console.log(`[volt] installing ${pkg} for the connection test…`);
+  console.log(`[volt] installing ${pkg} for the connection test…`);
   spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
 }
 
@@ -314,15 +316,15 @@ function startSetup() {
               server.closeIdleConnections?.();
             };
             if (added.length) {
-              console.log(`[volt] installing ${added.join(", ")}…`);
+              console.log(`[volt] installing ${added.join(", ")}…`);
               const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
               npm.on("error", () => handoff());
               npm.on("close", () => {
-                console.log("[volt] saved .env — starting the app…");
+                console.log("[volt] saved .env — starting the app…");
                 handoff();
               });
             } else {
-              console.log("[volt] saved .env — starting the app…");
+              console.log("[volt] saved .env — starting the app…");
               handoff();
             }
           });
@@ -339,18 +341,18 @@ function startSetup() {
 
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log(`\n⚡ Volt setup → ${url}`);
     console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
     }
     console.log("");
-    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
   });
 }
 
@@ -358,8 +360,8 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
-// Not a route in the running app — it only exists while you run `--studio`, on
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
 // loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
 const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
 async function startStudio() {
@@ -372,7 +374,7 @@ async function startStudio() {
   try {
     store = await (await addonMod("db")).createStore();
   } catch (e) {
-    console.error("Studio: couldn't connect the store — " + e.message);
+    console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
   const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
@@ -427,15 +429,15 @@ async function startStudio() {
 
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
-    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — from your LOCAL machine:");
+      console.log("  Remote box — from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url}.`);
+      console.log(`  …then open ${url}.`);
     }
     console.log("");
     openBrowser(url);

package/templates/starter/server.js

@@ -1,9 +1,9 @@
-// server.js — dev server with a built-in first-run setup wizard.
+// server.js — dev server with a built-in first-run setup wizard.
 //
 // First run (no .env) or `node server.js --edit` (-e) opens a disposable, local
 // config page: tick add-ons, fill settings, Apply. Apply writes .env (a
 // VOLT_ADDONS list + settings) and adds any needed packages to package.json,
-// runs npm install, then starts the app — which wires whatever .env enables.
+// runs npm install, then starts the app — which wires whatever .env enables.
 // Add-on code is bundled under .volt/addons; nothing is copied into your code.
 //
 // No build step, no env-file flag: .env is auto-loaded below.
@@ -23,7 +23,7 @@ const PKG_PATH = path.join(__dirname, "package.json");
 const ADDONS_DIR = path.join(__dirname, ".volt", "addons"); // bundled add-on sources
 const DEFAULT_PORT = 26628; // create-volt stamps this with the project's date-port
 const PKG_VERSIONS = { mongodb: "^6.21.0", mysql2: "^3.22.5", pg: "^8.22.0", nodemailer: "^6.10.1", marked: "^18.0.5", busboy: "^1.6.0", "@aws-sdk/client-s3": "^3.1075.0" };
-const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", media: "media.js" };
+const LIB_FILE = { db: "store.js", mailer: "mailer.js", auth: "auth.js", realtime: "realtime.js", pages: "pages.js", posts: "posts.js", media: "media.js" };
 
 // --- tiny .env loader (no dependency); never overrides an existing env var ---
 function readEnvFile() {
@@ -68,7 +68,7 @@ const imp = (rel) => import(pathToFileURL(path.join(__dirname, rel)).href);
 const addonMod = (n) => imp(path.join(".volt", "addons", n, "files", "lib", LIB_FILE[n]));
 
 // Built-in add-ons are wired explicitly below; everything else in VOLT_ADDONS is
-// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
+// a third-party add-on — a local .volt/addons/<name>/index.js or an installed
 // npm package "volt-addon-<name>" exporting register(ctx). See /docs/plugins.
 const BUILTINS = new Set(Object.keys(LIB_FILE));
 async function loadAddon(name) {
@@ -92,7 +92,7 @@ function openBrowser(url) {
   const args = plat === "win32" ? ["/c", "start", "", url] : [url];
   try {
     const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {}); // launcher missing — emits async, don't crash
+    child.on("error", () => {}); // launcher missing — emits async, don't crash
     child.unref();
     return true;
   } catch {
@@ -120,7 +120,7 @@ async function startApp() {
   if (enabled.has("mailer")) mailer = await (await addonMod("mailer")).createMailer();
   if (enabled.has("auth") && store && mailer) app.use((await addonMod("auth")).authRouter({ store, mailer }));
 
-  // notes — a per-user CRUD example (auth-gated, owner-scoped, db-backed)
+  // notes — a per-user CRUD example (auth-gated, owner-scoped, db-backed)
   if (enabled.has("db") && enabled.has("auth") && store) {
     const guard = (await addonMod("auth")).requireAuth(store);
     const notes = store.collection("notes");
@@ -160,14 +160,16 @@ async function startApp() {
     app.use(await (await addonMod("media")).mediaRouter({ requireAuth, dir: path.join(__dirname, "media") }));
   }
 
-  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // markdown pages (/<slug> ← pages/<slug>.md) — mounted last, so app routes win
+  // blog posts (/blog, /blog/<slug>, /category, /tag, /feed.xml) — before pages so /blog wins; renders in the same theme.
+  if (enabled.has("posts")) app.use(await (await addonMod("posts")).postsRouter({ dir: path.join(__dirname, "posts"), themeDir: path.join(__dirname, "pages") }));
   if (enabled.has("pages")) app.use(await (await addonMod("pages")).pagesRouter({ dir: path.join(__dirname, "pages") }));
 
   const server = http.createServer(app);
   const io = new SocketServer(server);
   if (enabled.has("realtime") && store) (await addonMod("realtime")).attachRealtime(io, { store });
 
-  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
+  // third-party add-ons — register(ctx). When auth is on, requireAuth/sessionFromReq
   // are provided so add-ons can gate routes by login.
   let requireAuth = null;
   let sessionFromReq = null;
@@ -183,7 +185,7 @@ async function startApp() {
     if (typeof register === "function") {
       await register({ app, express, io, store, mailer, env: process.env, requireAuth, sessionFromReq, log: (...a) => console.log(`[${name}]`, ...a) });
     } else {
-      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
+      console.warn(`[volt] add-on "${name}" not found or missing a register() export — skipped`);
     }
   }
 
@@ -191,7 +193,7 @@ async function startApp() {
   const onChange = (file) => {
     clearTimeout(timer);
     timer = setTimeout(() => {
-      console.log(`[volt] change: ${file ?? "?"} → reload`);
+      console.log(`[volt] change: ${file ?? "?"} → reload`);
       io.emit("volt:reload");
     }, 80);
   };
@@ -215,7 +217,7 @@ async function startApp() {
   for (const d of ["views", "public"]) watchRecursive(path.join(__dirname, d));
 
   const on = [...enabled];
-  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
+  server.listen(PORT, () => console.log(`⚡ Volt → http://localhost:${PORT}${on.length ? "  (add-ons: " + on.join(", ") + ")" : ""}`));
 }
 
 // Packages an .env's selections need, beyond what package.json already has.
@@ -228,7 +230,7 @@ function neededPackages(env) {
   if (driver === "mysql") want.push("mysql2");
   if (driver === "postgres") want.push("pg");
   if (/^\s*SMTP_URL\s*=\s*\S/m.test(env)) want.push("nodemailer");
-  if (/^\s*VOLT_ADDONS\s*=.*\bpages\b/m.test(env)) want.push("marked");
+  if (/^\s*VOLT_ADDONS\s*=.*\b(pages|posts)\b/m.test(env)) want.push("marked");
   if (/^\s*VOLT_ADDONS\s*=.*\bmedia\b/m.test(env)) want.push("busboy");
   if (/^\s*MEDIA_DRIVER\s*=\s*s3\b/m.test(env)) want.push("@aws-sdk/client-s3");
   return want.filter((p) => !deps[p]);
@@ -239,7 +241,7 @@ function neededPackages(env) {
 function ensureDriverInstalled(driver) {
   const pkg = { mongodb: "mongodb", mongo: "mongodb", mysql: "mysql2", postgres: "pg", postgresql: "pg", pg: "pg" }[String(driver || "").toLowerCase()];
   if (!pkg || fs.existsSync(path.join(__dirname, "node_modules", pkg))) return;
-  console.log(`[volt] installing ${pkg} for the connection test…`);
+  console.log(`[volt] installing ${pkg} for the connection test…`);
   spawnSync("npm", ["install", `${pkg}@${PKG_VERSIONS[pkg] || "latest"}`], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
 }
 
@@ -340,15 +342,15 @@ function startSetup() {
               server.closeIdleConnections?.();
             };
             if (added.length) {
-              console.log(`[volt] installing ${added.join(", ")}…`);
+              console.log(`[volt] installing ${added.join(", ")}…`);
               const npm = spawn("npm", ["install"], { cwd: __dirname, stdio: "inherit", shell: process.platform === "win32" });
               npm.on("error", () => handoff());
               npm.on("close", () => {
-                console.log("[volt] saved .env — starting the app…");
+                console.log("[volt] saved .env — starting the app…");
                 handoff();
               });
             } else {
-              console.log("[volt] saved .env — starting the app…");
+              console.log("[volt] saved .env — starting the app…");
               handoff();
             }
           });
@@ -365,18 +367,18 @@ function startSetup() {
 
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt setup → ${url}`);
+    console.log(`\n⚡ Volt setup → ${url}`);
     console.log("  Configure your app; it starts automatically on Apply. (reopen later: npm run dev -- --edit)");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
+      console.log("  Remote box — the server is up here; bridge it from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
+      console.log(`  …then open ${url} on your machine (the tunnel points it here).`);
     }
     console.log("");
-    if (openBrowser(url)) console.log("  (opening your browser…)\n");
+    if (openBrowser(url)) console.log("  (opening your browser…)\n");
   });
 }
 
@@ -384,8 +386,8 @@ function readEnvFileLines() {
   return fs.existsSync(ENV_PATH) ? fs.readFileSync(ENV_PATH, "utf8").split("\n") : [];
 }
 
-// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
-// Not a route in the running app — it only exists while you run `--studio`, on
+// --- Studio: an ephemeral, localhost-only data browser (à la Prisma Studio).
+// Not a route in the running app — it only exists while you run `--studio`, on
 // loopback, and disappears on Ctrl-C. Shell/SSH access is the auth. ---
 const HIDDEN_COLLECTIONS = new Set(["auth_tokens", "auth_sessions", "__voltcheck"]);
 async function startStudio() {
@@ -398,7 +400,7 @@ async function startStudio() {
   try {
     store = await (await addonMod("db")).createStore();
   } catch (e) {
-    console.error("Studio: couldn't connect the store — " + e.message);
+    console.error("Studio: couldn't connect the store — " + e.message);
     process.exit(1);
   }
   const PORT = Number(process.env.PORT) || Number(readEnvFile().PORT) || DEFAULT_PORT;
@@ -453,15 +455,15 @@ async function startStudio() {
 
   server.listen(PORT, "127.0.0.1", () => {
     const url = `http://localhost:${PORT}`;
-    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
-    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
+    console.log(`\n⚡ Volt Studio → ${url}   (${store.name})`);
+    console.log("  Browse your data. localhost-only, disposable — Ctrl-C when done.");
     const ssh = process.env.SSH_CONNECTION;
     if (ssh) {
       const host = ssh.split(" ")[2];
       const user = process.env.USER || process.env.USERNAME || "you";
-      console.log("  Remote box — from your LOCAL machine:");
+      console.log("  Remote box — from your LOCAL machine:");
       console.log(`    ssh -N -L 127.0.0.1:${PORT}:localhost:${PORT} ${user}@${host}`);
-      console.log(`  …then open ${url}.`);
+      console.log(`  …then open ${url}.`);
     }
     console.log("");
     openBrowser(url);