@odla-ai/blog

⚠️ Early access — pre-1.0. Agents work from bounded runbooks; humans approve credentials, production changes, releases, and merges. APIs and exact package availability can change. Review the documented guarantees and limitations; this software is MIT-licensed and provided without warranty.

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 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. Themes ship in the @odla-ai/ui dependency (the odla design system); every built site also gets ui's class-scoped component layer (assets/odla-ui.css — buttons, form fields, cards, …) theme-matched via the theme's ui.css token aliases. Override any theme file by placing a same-named file in your site's theme/ directory. Build your site with the package API and preview the emitted static directory with your usual local static server.

Input boundaries

Footnote identifiers are capped at 256 characters, and malformed [^ introducers are handled by a monotonic scanner so adversarial Markdown cannot force repeated whole-suffix regex scans. Markdown still permits authored raw HTML by design; it is not a sanitizer. JS pages and collection templates must use escapeHtml(String(value)) for every schema-free frontmatter value or filename-derived slug placed into HTML.

Deploy (Cloudflare)

build() emits a plain static directory; serve it from a Worker assets binding — { "assets": { "directory": "./dist-site" } } in wrangler.jsonc, build before every deploy. Add a main worker script only when you want /api/* routes next to the static site; the public platform manual describes how to combine the assets binding with odla-db and o11y.

Status

Early. The build pipeline and themes work; CLI (init/new/dev/check), feeds, search, deploy scaffolding, and the odla-db islands are in progress. Track supported behavior in this installed README and the public package docs at https://odla.ai/docs/packages/blog rather than relying on internal planning files.