Open Blog

An agentic blog engine for Rails. Markdown and rich-text articles, responsive reader pages, immutable revision history, and publishing through Ruby, a JSON API, or MCP tools.

Documentation · Installation · API reference · MCP · Changelog

Every publish, edit, approval, and removal leaves an immutable record. A reader can trust the dates and notices on the page, and an agent can publish without inventing a review.

Every combination of Ruby, Rails, and database above runs in CI.

bundle add open_blog
bin/rails generate open_blog:install

To run the latest unreleased source instead, use bundle add open_blog --github techwright-lab/open-blog.

Start bin/dev (or bin/rails server) and open /blog. The generator installs tables, mounts the engine at /blog, copies the reader views and browser controllers, writes config/initializers/open_blog.rb, and publishes a sample article. If it prints an API token, save it: the secret is shown once.

Set your site name, publisher, and public origin in the initializer, then run bin/rails open_blog:doctor to check the setup. The installation guide lists every generator option, and the configuration reference lists every setting with its default.

From Ruby:

result = OpenBlog::Publish.call(
  { title: "Garden notes", body: "Today in the garden.", provenance: "human_written" },
  actor: "Editor"
)
result.success?   # => true
result.post.path  # => "/blog/garden-notes"
result.records    # => { revision: "new", publication: "first", approval: nil }

From the JSON API, with a token from bin/rails open_blog:token:

curl -s -X POST https://example.com/blog/api/v1/posts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Garden notes","body":"Today in the garden.","publish":true}'

From an agent, point an MCP client at https://example.com/blog/mcp with the same token. The blog_save_draft tool returns a preview link, and blog_publish_post records the release. Agents must show the exact text to a person and record only the approval they actually give; the publishing instructions spell this out.

A later edit of a public post must carry change: "substantive", "correction", or "maintenance". Without it the write is refused and nothing changes. Normal model saves and the operations keep this history; bulk SQL writes bypass it.

The gem tests run through a dummy host application. Set DB to sqlite or postgres:

bundle install
DB=sqlite RAILS_ENV=test bundle exec ruby bin/test
bundle exec rubocop

CI runs the matrix of Ruby 3.2 to 4.0, Rails 8.0 and 8.1, and both databases, plus browser tests and a fresh-application installer check with the built gem.

The documentation is Markdown in docs/, built with Jekyll and Just the Docs from a separate bundle. See working on the documentation for local preview and validation commands.

The Prepare Release workflow updates the version and changelog in a pull request. After review, merge, and successful checks, Publish publishes the verified package to RubyGems and creates or updates the GitHub Release. Merging ordinary changes does not publish a gem. See the release guide for the first-time Trusted Publishing setup.

Licensed under the MIT License.