Stoa

A documentation theme for Bridgetown, inspired by just-the-docs.

Pre-alpha. Stoa is structural scaffolding only — gemspec, one minimal layout, a test harness. None of just-the-docs' features (sidebar nav, search, callouts, dark mode, anchor links) have been ported yet.

If you need a working docs theme for Bridgetown today, this isn't it yet.

Add to your Bridgetown site's Gemfile:

gem "bridgetown-stoa"

Then bundle install and add to config/initializers.rb:

init :"bridgetown-stoa"

Stoa ships its styles as a Tailwind v4 source partial in a companion npm package (bridgetown-stoa), so they compose with your site's Tailwind pipeline (tree-shaken, token-overrideable).

npm install bridgetown-stoa

Then in frontend/styles/index.css, after @import "tailwindcss";, add two lines:

@import "tailwindcss";
@import "bridgetown-stoa";
@source "../../node_modules/bridgetown-stoa/layouts/**/*.serb";

• @import "bridgetown-stoa" pulls in the @theme tokens (--color-stoa-*, --font-stoa-*) and a small @layer base that styles html with the theme colors. Keep it directly after the Tailwind import: CSS requires all @import rules to come before any other rule, and an @import placed after @source is silently dropped.
• @source tells Tailwind to scan Stoa's layouts for utility-class usage.

Override any token by redeclaring it in your own @theme block after the import.

Stoa uses Tailwind's class-strategy dark mode (html.dark). Toggle the dark class on <html> to switch themes; a default JS toggle that follows prefers-color-scheme will ship in a later release.

One layout is registered: bridgetown-stoa/layout. Apply it via front matter:

---
layout: bridgetown-stoa/layout
title: My Page
---

The layout is self-contained: it renders a full HTML document (doctype, <head> with title and asset tags, semantic <header>/<main>/<footer> regions) and yields the page body into <main>. You do not need a default layout in your site to use Stoa.

The document title is {page title} | {site metadata title} when a page sets title: in front matter, and just the site title otherwise. The layout also injects asset_path :css / :js so your site's esbuild bundle loads automatically.

The sidebar chrome is built from components that a host site can shadow one at a time, without copying the whole layout. Drop a template with the matching path into your site's src/_components directory and Stoa renders yours instead of its own:

For example, to add a line to the footer:

<!-- src/_components/bridgetown_stoa/sidebar_footer.serb -->
<footer class="stoa-sidebar-footer">
  <small>
    A <a href="https://example.com">My Org</a> project.
    Built with <a href="https://www.bridgetownrb.com">Bridgetown</a>
    <span>+</span>
    <a href="https://github.com/Guided-Rails/bridgetown-stoa">Stoa</a>.
  </small>
</footer>

Only the template is replaced; the component's Ruby class still comes from the gem, so you keep any behavior it gains in later releases. Any template extension Bridgetown's components support (.serb, .erb, .slim, .haml) works.

To replace the chrome entirely, shadow the layout itself:

src/_layouts/bridgetown-stoa/layout.serb

Bridgetown's layout resolution picks the host site's file over the gem's, so you can replace the entire layout or copy ours and edit it. Prefer shadowing a component when you only need to change one region, since a copied layout won't pick up later changes to the gem's chrome.

Requires Ruby ≥ 3.2 and Bridgetown ≥ 2.0.

bundle install
script/cibuild   # rubocop + minitest
bin/dev          # preview the theme at http://localhost:4000

bin/dev serves the site in test/fixtures with the theme applied, using a standard Bridgetown esbuild + Tailwind pipeline (it runs bundle install and npm install for you when needed). Edits to layouts/ and frontend/styles/ rebuild and live-reload. Extra arguments go to bridgetown start, e.g. bin/dev -P 4001.

Templates use Serbea, Bridgetown's ERB-with-Liquid-like-sugar engine. Stoa is inspired by just-the-docs, not a port of it — layouts are written idiomatically for Bridgetown rather than translated from upstream.

MIT. See LICENSE.txt.