bridgetown-stoa 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 365a0e33a6ef2322e275a9b0c6f239850738c72cd262533b15971905065850d5
-  data.tar.gz: c71acbd3b6f7e636228586f92803ec5e944475dd96d952687972a3e9503f68eb
+  metadata.gz: 0511ef53344c59a9838fed10c80f00359b0a789d415b621e7607478040ffe7cb
+  data.tar.gz: 21f47c907b9100fa4f8d869bc72f703fc184dd21e317b3940aa405017df4605e
 SHA512:
-  metadata.gz: da393ab663e6d732b1334e975a3fc557716f54078f30fb60c4f976a3bba97cad5ba255143c382d53afec750d5ad3c82727b7939766c8c6e601ba3d76206cc2fd
-  data.tar.gz: 31d44f129642fd47d018057d7eae6d0cac5798044f81edee7993537cc6d42ee9c6f4d4b7ab904e92a02bc4c48c560b4ea1bb7c3eeff6ef65048355392bab83bf
+  metadata.gz: 2c2bccceca7a78df90d4fffd4846db7201fb28d1ab661582f71c352a83e9864535e93090d86fa79921cf0e093473306ae0f08e7f7f93c242a194a5416e664f8a
+  data.tar.gz: 83755738874401da2cf61b08d56f9943517942d84376c328018eaf47c338a6118a3e751c356971e8f6a46994e53d2d88d4c0c9940d10a1f981c0856ceefd3fc2

data/CHANGELOG.md

@@ -9,6 +9,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - ...
 
+## [0.2.0] - 2026-05-22
+
+### Added
+- Tailwind v4 source partial at `frontend/styles/bridgetown-stoa.css`, shipped via a companion `bridgetown-stoa` npm package. Defines `--color-stoa-*` and `--font-stoa-*` design tokens (light + dark) in an `@theme` block, sets up class-strategy dark mode via `@custom-variant dark`, and applies a baseline `html` style. Host sites `@import "bridgetown-stoa"` and `@source` the layouts from their `frontend/styles/index.css`.
+- `script/release` now also runs `npm publish` after the gem release, and pre-flights `npm whoami` so it bails before the gem push if credentials are missing.
+
+### Fixed
+- `bridgetown-stoa/layout` no longer prepends `"Index | "` to `<title>` on the home page when `src/index.md` has no explicit `title:` front-matter. (#8)
+
+## [0.1.0] - 2026-05-22
+
+### Changed
+- `bridgetown-stoa/layout` is now a self-contained HTML document (doctype, `<head>` with title/meta/asset tags, and `<header>`/`<main>`/`<footer>` chrome). Consumers no longer need to provide their own `default` layout to use Stoa. The layout also prepends `resource.data.title` to `<title>` when set. (#5)
+
+### Notes
+- The layout wires `asset_path :css` / `:js` for the host site's esbuild bundle. Bridgetown sites created with `bridgetown new` ship esbuild by default; sites without frontend bundling will see `MISSING_FRONTEND_BUNDLING_CONFIG` in the asset URLs until they configure one (or shadow the layout to drop the tags).
+
 ## [0.0.2] - 2026-05-22
 
 ### Fixed

data/README.md

@@ -22,6 +22,29 @@ Then `bundle install` and add to `config/initializers.rb`:
 init :"bridgetown-stoa"
 ```
 
+### Styles (Tailwind v4)
+
+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).
+
+```shell
+npm install bridgetown-stoa
+```
+
+Then in `frontend/styles/index.css`, after `@import "tailwindcss";`, add two lines:
+
+```css
+@import "tailwindcss";
+@source "../../node_modules/bridgetown-stoa/layouts/**/*.serb";
+@import "bridgetown-stoa";
+```
+
+- `@source` tells Tailwind to scan Stoa's layouts for utility-class usage.
+- `@import "bridgetown-stoa"` pulls in the `@theme` tokens (`--color-stoa-*`, `--font-stoa-*`) and a small `@layer base` that styles `html` with the theme colors.
+
+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.
+
 ## Usage
 
 One layout is registered: `bridgetown-stoa/layout`. Apply it via front matter:
@@ -29,10 +52,23 @@ One layout is registered: `bridgetown-stoa/layout`. Apply it via front matter:
 ```yaml
 ---
 layout: bridgetown-stoa/layout
+title: My Page
 ---
 ```
 
-The layout chains into your site's `default` layout and yields the page content. No styling, navigation, or chrome — that's intentional for v0.1.
+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.
+
+### Overriding the layout
+
+To customize the chrome, shadow the layout in your own site:
+
+```
+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. (More granular override points — head, nav, footer partials — will land as the theme grows.)
 
 ## Development
 

data/bridgetown-stoa.gemspec

@@ -14,10 +14,11 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|script|spec|features)/!) }
   spec.test_files    = spec.files.grep(%r!^test/!)
   spec.require_paths = ["lib"]
-  # Uncomment this if you wish to supply a companion NPM package and/or command features:
+  # TODO: enable the `npm_add` metadata below once the npm companion is
+  # published. While the package is unpublished, Bridgetown's init-time
+  # registry lookup 404s loudly during every test run.
   # spec.metadata = {
   #   "npm_add" => "bridgetown-stoa@#{BridgetownStoa::VERSION}",
-  #   "bridgetown_features" => "true"
   # }
 
   spec.required_ruby_version = ">= 3.2"

data/frontend/styles/bridgetown-stoa.css

@@ -0,0 +1,34 @@
+/* bridgetown-stoa: Tailwind v4 source partial. Import after `@import "tailwindcss"`. */
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+@theme {
+  --color-stoa-bg: oklch(98% 0.002 264);
+  --color-stoa-surface: oklch(100% 0 0);
+  --color-stoa-fg: oklch(20% 0.012 264);
+  --color-stoa-muted: oklch(50% 0.012 264);
+  --color-stoa-border: oklch(92% 0.005 264);
+  --color-stoa-accent: oklch(55% 0.18 264);
+  --color-stoa-accent-fg: oklch(98% 0.002 264);
+
+  --font-stoa-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-stoa-mono: ui-monospace, "SF Mono", Menlo, "Cascadia Code", monospace;
+}
+
+@layer base {
+  .dark {
+    --color-stoa-bg: oklch(17% 0.012 264);
+    --color-stoa-surface: oklch(22% 0.012 264);
+    --color-stoa-fg: oklch(94% 0.005 264);
+    --color-stoa-muted: oklch(65% 0.012 264);
+    --color-stoa-border: oklch(28% 0.012 264);
+    --color-stoa-accent: oklch(72% 0.16 264);
+    --color-stoa-accent-fg: oklch(15% 0.012 264);
+  }
+
+  html {
+    background: var(--color-stoa-bg);
+    color: var(--color-stoa-fg);
+    font-family: var(--font-stoa-sans);
+  }
+}

data/layouts/bridgetown-stoa/layout.serb

@@ -1,4 +1,33 @@
----
-layout: default
----
-{%= yield %}
+<!doctype html>
+<html lang="{{ site.locale || 'en' }}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>
+      {% if resource.data.title != "Index" %}
+        {{ resource.data.title }} |
+      {% end %}
+      {{ site.metadata.title }}
+    </title>
+    {% if resource.data.description %}
+      <meta name="description" content="{{ resource.data.description }}">
+    {% end %}
+    <link rel="stylesheet" href="{%= asset_path :css %}">
+  </head>
+  <body>
+    <header class="stoa-header">
+      <a href="/" class="stoa-site-title">{{ site.metadata.title }}</a>
+    </header>
+    <main class="stoa-main">
+      {%= yield %}
+    </main>
+    <footer class="stoa-footer">
+      <small>
+        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>
+    <script src="{%= asset_path :js %}" defer></script>
+  </body>
+</html>

data/lib/bridgetown-stoa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BridgetownStoa
-  VERSION = "0.0.2"
+  VERSION = "0.2.0"
 end

data/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "bridgetown-stoa",
+  "version": "0.2.0",
+  "description": "Tailwind v4 source partial and layouts for the Stoa Bridgetown documentation theme.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Guided-Rails/bridgetown-stoa.git"
+  },
+  "homepage": "https://github.com/Guided-Rails/bridgetown-stoa",
+  "main": "frontend/styles/bridgetown-stoa.css",
+  "style": "frontend/styles/bridgetown-stoa.css",
+  "exports": {
+    ".": "./frontend/styles/bridgetown-stoa.css",
+    "./layouts/*": "./layouts/*"
+  },
+  "files": [
+    "frontend/styles/",
+    "layouts/",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "peerDependencies": {
+    "tailwindcss": "^4.0.0"
+  }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bridgetown-stoa
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -80,9 +80,11 @@ files:
 - README.md
 - Rakefile
 - bridgetown-stoa.gemspec
+- frontend/styles/bridgetown-stoa.css
 - layouts/bridgetown-stoa/layout.serb
 - lib/bridgetown-stoa.rb
 - lib/bridgetown-stoa/version.rb
+- package.json
 homepage: https://github.com/Guided-Rails/bridgetown-stoa
 licenses:
 - MIT