@odla-ai/blog 0.0.1

package/README.md

@@ -0,0 +1,44 @@
+# @odla-ai/blog
+
+Minimal-dependency, static-first blogging platform. A site is a directory of
+markdown plus one JSON config; `build()` emits a fully static site that works on
+GitHub Pages or Cloudflare. When [odla-db](https://github.com/odla-ai/odla-db) is
+configured, interactive features (sign-in, comments, likes) light up as a
+progressive layer — the static site never depends on it.
+
+Three runtime dependencies, each with zero dependencies of its own: `marked`
+(markdown), `yaml` (frontmatter), `highlight.js` (build-time syntax highlighting —
+no client JS ships).
+
+## Site layout
+
+```
+my-blog/
+├── blog.config.json     # the only config
+├── posts/2026/2026-07-03-hello.md
+├── pages/about.md
+├── public/              # copied verbatim
+└── theme/               # optional file-by-file overrides of the chosen theme
+```
+
+Frontmatter: `title` and `date` required; `description`, `tags`, `draft`, `image`
+optional. `draft: true` or a future `date` keeps a post out of the build.
+
+## Themes
+
+Four bundled themes, all with light + dark modes (system preference + ☾/☀ toggle):
+
+- **juniper** (default) — quiet long-form reading; Lora serif, violet/lavender
+- **salt** — warm cream editorial; Cormorant Garamond, moss/rust/teal
+- **chalk** — chalkboard on graph paper; copper/cerulean, mono chrome
+- **clay** — sand paper and terracotta; system fonts only, zero external requests
+
+Pick one with `"theme": "salt"` in `blog.config.json`. Override any theme file by
+placing a same-named file in your site's `theme/` directory. Preview all four
+against the example site with `npm run preview` (from the monorepo root).
+
+## Status
+
+Early. The build pipeline, themes, and example site work; CLI (`init`/`new`/`dev`/
+`check`), feeds, search, deploy scaffolding, and the odla-db islands are in
+progress — see `PLAN.md` at the repo root.

package/config.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "@odla-ai/blog site configuration (blog.config.json)",
+  "type": "object",
+  "required": ["title", "url"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "title": { "type": "string", "description": "Site title, shown in the header and feeds" },
+    "url": { "type": "string", "format": "uri", "description": "Canonical origin, e.g. https://cory.news" },
+    "description": { "type": "string" },
+    "author": { "type": "string" },
+    "lang": { "type": "string", "default": "en" },
+    "basePath": {
+      "type": "string",
+      "pattern": "^/([^/].*/)?$",
+      "default": "/",
+      "description": "URL prefix all links use; must start and end with '/'. Set for GitHub project pages."
+    },
+    "theme": {
+      "type": "string",
+      "enum": ["juniper", "salt", "chalk", "clay"],
+      "default": "juniper"
+    },
+    "sidebarRecentPosts": {
+      "type": "integer",
+      "default": 0,
+      "description": "Show a recent-posts sidebar column (wide viewports) with this many posts; 0 = no sidebar"
+    },
+    "indexLimit": {
+      "type": "integer",
+      "default": 20,
+      "description": "How many recent posts the home page shows with excerpts; 0 = all"
+    },
+    "nav": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["label", "href"],
+        "additionalProperties": false,
+        "properties": {
+          "label": { "type": "string" },
+          "href": { "type": "string" }
+        }
+      },
+      "description": "Explicit header navigation; omit for automatic Archive/Tags/pages"
+    },
+    "footerLinks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["label", "href"],
+        "additionalProperties": false,
+        "properties": {
+          "label": { "type": "string" },
+          "href": { "type": "string" }
+        }
+      },
+      "description": "Links shown before the copyright in the footer (e.g. a Colophon link)"
+    },
+    "copyright": {
+      "type": "string",
+      "description": "Text appended after the author in the footer, e.g. 'All rights reserved.'"
+    },
+    "postsPath": {
+      "type": "string",
+      "default": "posts",
+      "description": "URL prefix for post pages, e.g. 'updates' → /updates/<slug>/ (preserve existing URLs when migrating)"
+    },
+    "slugFormat": {
+      "type": "string",
+      "enum": ["clean", "filename"],
+      "default": "clean",
+      "description": "'clean' strips the YYYY-MM-DD- filename prefix from post URLs; 'filename' keeps it (preserve existing URLs when migrating)"
+    },
+    "extraFields": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Frontmatter keys beyond the core set that `blog check` should accept without warning"
+    },
+    "odla": {
+      "type": "object",
+      "description": "Optional odla-db integration (not yet active in this version)",
+      "additionalProperties": false,
+      "properties": {
+        "endpoint": { "type": "string", "format": "uri" },
+        "appId": { "type": "string" },
+        "auth": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "provider": { "type": "string", "enum": ["clerk", "oidc"] },
+            "publishableKey": { "type": "string" },
+            "issuer": { "type": "string", "format": "uri" }
+          }
+        },
+        "features": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "comments": { "type": "boolean", "default": false },
+            "likes": { "type": "boolean", "default": false }
+          }
+        }
+      }
+    }
+  }
+}

package/llms.txt

@@ -0,0 +1,161 @@
+# @odla-ai/blog — agent reference (llms.txt)
+
+This file ships in the npm package so an agent working in a *site* repo can
+operate the platform from `node_modules/@odla-ai/blog/llms.txt` alone. The
+source in `src/` is small and dependency-light — read it when in doubt; it is
+the authority.
+
+## Site anatomy
+
+```
+my-blog/
+├── blog.config.json          # the only config (schema: ./config.schema.json)
+├── posts/<year>/<YYYY-MM-DD-slug>.md
+├── pages/<slug>.md           # standalone pages; auto-added to nav
+├── public/                   # copied verbatim into the output root
+└── theme/                    # optional overrides (see Theming)
+```
+
+## Frontmatter
+
+```yaml
+---
+title: Required             # string, required
+date: 2026-07-03            # required; parseable date
+description: One-liner      # optional; used on index, meta description, RSS
+tags: [a, b]                # optional list of strings
+draft: true                 # optional; excluded from builds
+image: /images/x.png        # optional
+---
+```
+
+Publication rules (both enforced in `src/content.js`):
+- `draft: true` → excluded.
+- `date` in the future → excluded ("scheduled") until that date passes.
+- Slugs come from the filename with the `YYYY-MM-DD-` prefix stripped
+  (config `"slugFormat": "filename"` keeps the prefix — use when migrating a
+  site whose existing URLs include it) and must be unique across ALL years —
+  collisions are a build error, so check before naming a new post.
+
+Pages support one extra frontmatter key: `listTag: Sea Stories` appends the
+excerpted list of posts carrying that tag after the page body — the pattern
+for curated collections.
+
+## Collections (build-time data)
+
+Every directory under `<site>/collections/` loads at build time as
+`collections.<name>` — an array of `{ slug, file, data, body }` with raw
+frontmatter (schema-free) and the unrendered markdown body. Collections are
+data, not pages: templates and JS pages decide what to render from them.
+This is how a site carries an entity dataset (companies, books, resources…)
+while staying fully static.
+
+## JS pages (bespoke pages and static endpoints)
+
+A page can be a `.js` module instead of markdown:
+
+```js
+// pages/map.js → /map/
+export const title = "Map";                       // optional; joins nav
+export function render({ config, posts, pages, collections, excerpts }) {
+  return "<h1>…</h1>";                            // wrapped in the site shell
+}
+```
+
+If the filename keeps a real extension after stripping `.js`
+(`pages/api/data.json.js` → `/api/data.json`), the output is written verbatim
+with no HTML shell — a static data endpoint. Import shared helpers from the
+package (`import { escapeHtml, renderMarkdown, postList } from "@odla-ai/blog"`).
+
+## Page chrome (automatic)
+
+- Head: canonical URL, OpenGraph + Twitter meta (per-post `image` frontmatter,
+  home falls back to the newest post's image), favicon link (if
+  `public/favicon.svg|ico` exists), RSS/Atom/sitemap links.
+- Sticky nav bar with a scroll-position indicator (accent line + dot).
+- Optional recent-posts sidebar: `"sidebarRecentPosts": 30` in config shows a
+  280px column of recent post links on viewports ≥1200px.
+- Output includes `rss.xml`, `atom.xml`, `sitemap.xml`.
+
+## Markdown extras
+
+- **Footnotes** (GFM `[^1]` / `[^1]: text`) render as numbered superscript
+  links plus a `<section class="footnotes">` appended to the content.
+- **Smart typography**: `--`/`---` become em dashes and straight quotes curl,
+  in prose text only — code spans and blocks are never touched.
+- **Excerpts**: the home page (`indexLimit` most recent, default 20) and
+  `listTag` pages show each post's content truncated at a block boundary
+  after ~200 words with a `[continue reading]` link (`src/excerpt.js`).
+
+## Footer
+
+`config.footerLinks` (e.g. `[{"label": "Colophon", "href": "about/"}]`) render
+first, then `© <year links into the archive> <author>` plus optional
+`config.copyright` text. Years come from the posts automatically.
+
+## Build API
+
+```js
+import { build } from "@odla-ai/blog";
+const result = await build({
+  siteDir: ".",            // directory containing blog.config.json
+  outDir: "dist",
+  now: new Date(),          // optional; drives date-gating
+  includeDrafts: false,     // optional; true = render drafts + scheduled
+  configOverrides: {},      // optional; shallow-merged over blog.config.json
+});
+// → { posts, pages, theme }
+```
+
+Output: `index.html`, `posts/<slug>/index.html`, `<page>/index.html`,
+`archive/`, `tags/`, `tags/<tag>/`, `rss.xml`, `sitemap.xml`,
+`assets/styles.css`, plus everything from `public/`. All URLs are prefixed
+with `config.basePath` (default `/`) — set it when deploying under a subpath
+(e.g. GitHub project pages).
+
+Also exported: `loadPosts`, `loadPages`, `parseFrontmatter`, `slugFromFilename`,
+`renderMarkdown`, `slugify`, `escapeHtml`, `resolveThemeFile`.
+
+## Markdown
+
+GitHub-flavored, rendered by `marked`. Fenced code blocks are highlighted at
+build time by highlight.js (`lib/common` language set) into `hljs-*` classes —
+no client-side JS. Headings get slugified `id` anchors.
+
+## Theming
+
+Bundled themes: `juniper` (default), `salt`, `chalk`, `clay` — pick with
+`"theme": "<name>"` in config. Each theme is a single self-contained
+`src/themes/<name>/styles.css` plus `theme.json` metadata.
+
+Invariants every theme upholds (keep them when editing or adding one):
+- Light tokens on `:root`; dark tokens duplicated on BOTH `[data-theme="dark"]`
+  and `@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) }`.
+  The two dark blocks must stay identical (tested in `test/themes.test.js`).
+- Common token names: `--bg`, `--text`, `--accent`, `--border`, `--code-bg`,
+  and the highlight set `--hl-keyword`, `--hl-string`, `--hl-comment`,
+  `--hl-number`, `--hl-title`, `--hl-attr`, `--hl-type`, `--hl-meta`,
+  `--hl-addition`, `--hl-deletion`.
+- Selector contract (emitted by `src/templates/*.js`): `.site-header`,
+  `.site-title`, `.site-nav`, `.theme-toggle`, `.post-list`, `.post-item`,
+  `.post-title`, `.post-meta`, `.post-tag`, `.prose`, `.page-title`,
+  `.archive-year`, `.archive-list`, `.archive-item`, `.tag-cloud`, `.hljs-*`.
+
+**Site-local overrides:** any file placed in the site's `theme/` directory
+shadows the packaged theme file of the same name (`styles.css`, or any
+template like `post.js` or `index.js`). Copy the packaged file out, edit,
+done. Templates are plain JS functions returning template-literal HTML
+strings; they may import shared helpers from the package
+(`import { postList } from "@odla-ai/blog"`). To ADD styles without forking
+the whole stylesheet, put them in `theme/custom.css` — the build appends it
+to the theme's CSS. Post URLs live under `config.postsPath` (default
+"posts").
+
+## Gotchas
+
+- `blog.config.json` is plain JSON — no comments, no trailing commas.
+- `basePath` must start and end with `/`.
+- Posts render markdown; changing shared HTML structure means editing
+  `src/templates/` (or shadowing them), never the emitted HTML.
+- The odla-db interactive layer (sign-in, comments, likes) is planned but not
+  yet in this package version; an `odla` config block is currently inert.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@odla-ai/blog",
+  "version": "0.0.1",
+  "description": "Minimal-dependency, static-first blogging platform. Files in, site out; odla-db lights up interactivity when configured.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "llms.txt",
+    "config.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "preview": "node scripts/preview.mjs",
+    "test": "node --test --test-reporter=spec"
+  },
+  "dependencies": {
+    "highlight.js": "^11.11.0",
+    "marked": "^16.0.0",
+    "yaml": "^2.8.0"
+  }
+}

package/src/build.js

@@ -0,0 +1,206 @@
+// Static build: content + theme → dist/. Pure pipeline, top to bottom.
+//
+// Theme resolution (file-by-file shadowing):
+//   1. <site>/theme/<file>          — site-local override
+//   2. src/themes/<name>/<file>     — the chosen packaged theme
+//   3. src/templates/<file>         — shared default templates
+// Themes usually only provide styles.css; templates come from the shared set.
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadPosts, loadPages, loadJsPages, loadCollections } from "./content.js";
+import { renderMarkdown, slugify } from "./markdown.js";
+import { excerpt } from "./excerpt.js";
+import { atom, rss, sitemap } from "./feeds.js";
+
+const SRC = dirname(fileURLToPath(import.meta.url));
+
+export function resolveThemeFile(siteDir, themeName, file) {
+  const candidates = [
+    join(siteDir, "theme", file),
+    join(SRC, "themes", themeName, file),
+    join(SRC, "templates", file),
+  ];
+  return candidates.find((c) => existsSync(c)) ?? null;
+}
+
+async function loadTemplates(siteDir, themeName) {
+  const templates = {};
+  for (const name of ["base", "index", "post", "page", "archive", "tags"]) {
+    const file = resolveThemeFile(siteDir, themeName, `${name}.js`);
+    templates[name] = await import(pathToFileURL(file).href);
+  }
+  return templates;
+}
+
+export async function build({
+  siteDir,
+  outDir,
+  now = new Date(),
+  includeDrafts = false,
+  configOverrides = {},
+}) {
+  const config = {
+    ...JSON.parse(await readFile(join(siteDir, "blog.config.json"), "utf8")),
+    ...configOverrides,
+  };
+  config.basePath ??= "/";
+  const themeName = config.theme ?? "juniper";
+
+  const postsPath = config.postsPath ?? "posts";
+  const posts = await loadPosts(join(siteDir, "posts"), {
+    now,
+    includeDrafts,
+    slugFormat: config.slugFormat,
+    postsPath,
+  });
+  const pages = await loadPages(join(siteDir, "pages"));
+  const jsPages = await loadJsPages(join(siteDir, "pages"));
+  const collections = await loadCollections(join(siteDir, "collections"));
+  for (const jp of jsPages) {
+    if (!jp.raw && pages.some((p) => p.slug === jp.slug)) {
+      throw new Error(`Page collision: "${jp.slug}" exists as both markdown and JS page`);
+    }
+  }
+  // Markdown pages and titled JS pages join the automatic nav.
+  config.pages = [
+    ...pages.map((p) => ({ title: p.title, url: p.url })),
+    ...jsPages.filter((p) => !p.raw && p.title).map((p) => ({ title: p.title, url: p.url })),
+  ];
+  config.years = [...new Set(posts.map((p) => p.date.getUTCFullYear()))].sort((a, b) => b - a);
+  const sidebarCount = config.sidebarRecentPosts ?? 0;
+  config.recentPosts = sidebarCount > 0
+    ? posts.slice(0, sidebarCount).map((p) => ({ title: p.title, url: p.url, date: p.date }))
+    : [];
+  config.defaultImage = posts.find((p) => p.image)?.image ?? null;
+  config.favicon = ["favicon.svg", "favicon.ico"].find((f) =>
+    existsSync(join(siteDir, "public", f))
+  ) ?? null;
+
+  // Clean output so renamed/deleted content can't leave stale pages behind.
+  // Guard: never wipe a directory that looks like a site source.
+  if (existsSync(join(outDir, "blog.config.json"))) {
+    throw new Error(`outDir ${outDir} contains blog.config.json — refusing to clean it`);
+  }
+  await rm(outDir, { recursive: true, force: true });
+
+  const t = await loadTemplates(siteDir, themeName);
+  const shell = (opts) => t.base.base({ config, ...opts });
+  const write = async (relPath, content) => {
+    const file = join(outDir, relPath);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, content);
+  };
+
+  // Render every post once; excerpts (for index and listTag pages) come
+  // from the same rendered HTML.
+  const excerpts = new Map();
+  for (const post of posts) {
+    const html = renderMarkdown(post.body);
+    excerpts.set(
+      post.slug,
+      excerpt(html, { minWords: 200, moreUrl: `${config.basePath}${post.url}` }).html
+    );
+    await write(
+      join(postsPath, post.slug, "index.html"),
+      shell({
+        title: post.title,
+        description: post.description,
+        path: post.url,
+        image: post.image,
+        content: t.post.post({ config, post, html, collections, now }),
+      })
+    );
+  }
+
+  await write(
+    "index.html",
+    shell({
+      description: config.description,
+      path: "",
+      image: config.defaultImage,
+      content: t.index.index({ config, posts, excerpts, collections, now }),
+    })
+  );
+
+  for (const page of pages) {
+    await write(
+      join(page.slug, "index.html"),
+      shell({
+        title: page.title,
+        description: page.description,
+        path: page.url,
+        content: t.page.page({ config, page, html: renderMarkdown(page.body), posts, excerpts, collections, now }),
+      })
+    );
+  }
+
+  // JS pages render with full build context; raw ones (e.g. api/data.json)
+  // skip the HTML shell.
+  for (const jp of jsPages) {
+    const body = await jp.module.render({ config, posts, pages, collections, excerpts, now });
+    if (jp.raw) {
+      await write(jp.outPath, body);
+    } else {
+      await write(
+        jp.outPath,
+        shell({
+          title: jp.title ?? undefined,
+          description: jp.description ?? undefined,
+          path: jp.url,
+          content: body,
+        })
+      );
+    }
+  }
+
+  await write(
+    join("archive", "index.html"),
+    shell({ title: "Archive", path: "archive/", content: t.archive.archive({ config, posts, collections, now }) })
+  );
+
+  await write(
+    join("tags", "index.html"),
+    shell({ title: "Tags", path: "tags/", content: t.tags.tagIndex({ config, posts }) })
+  );
+  // Tag pages are keyed by slug so case variants merge into one page.
+  const tagGroups = new Map();
+  for (const post of posts) {
+    for (const tag of post.tags) {
+      const slug = slugify(tag);
+      if (!tagGroups.has(slug)) tagGroups.set(slug, { label: tag, posts: [] });
+      tagGroups.get(slug).posts.push(post);
+    }
+  }
+  for (const [slug, group] of tagGroups) {
+    await write(
+      join("tags", slug, "index.html"),
+      shell({
+        title: group.label,
+        path: `tags/${slug}/`,
+        content: t.tags.tagPage({ config, tag: group.label, posts: group.posts }),
+      })
+    );
+  }
+
+  await write("rss.xml", rss({ config, posts }));
+  await write("atom.xml", atom({ config, posts }));
+  await write("sitemap.xml", sitemap({ config, posts, pages }));
+
+  // theme/custom.css is appended to the theme stylesheet — additions without
+  // forking the whole file (full replacement: shadow styles.css itself).
+  const styles = resolveThemeFile(siteDir, themeName, "styles.css");
+  if (!styles) throw new Error(`Theme "${themeName}" has no styles.css`);
+  let css = await readFile(styles, "utf8");
+  const customCss = join(siteDir, "theme", "custom.css");
+  if (existsSync(customCss)) {
+    css += `\n/* ─── site custom.css ─── */\n${await readFile(customCss, "utf8")}`;
+  }
+  await write(join("assets", "styles.css"), css);
+
+  const publicDir = join(siteDir, "public");
+  if (existsSync(publicDir)) await cp(publicDir, outDir, { recursive: true });
+
+  return { posts: posts.length, pages: pages.length, theme: themeName };
+}