bridgetown-stoa 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd608896b8fe6337dd6f18ea4142689a7075fb8b083b2e818f8e7fb2581bef94
-  data.tar.gz: c701e091bf21dbcdfc797186baf25a8c091ff39b5396db1ca7a41a3dccecd5cf
+  metadata.gz: 83deb70eb7aadf2b8a2a8330a4bd64538130c03b57caedeab8bb522189626f67
+  data.tar.gz: 9d6414ab667d5b31df27f139a5f8c642c2885e2c7f861ba1c61f041c5aa1803e
 SHA512:
-  metadata.gz: 921ab4bca3b8dc1559db5d8bc3837a875643519925a4eed55a257c4b2c4e10444a7d7b404f1589f1d6c06c761ba83c03a10fdf180b2378a33c4275868400585b
-  data.tar.gz: bb4431c809b2eb51eb6c432d15c5a0785a0c25ea2762cba781942c97435139d31f93d60e5e68b76f6f847e685046e7e4719c3dfeb112543da8fc388ddf6b0543
+  metadata.gz: 874724dbda2bde6ed7151e0b66b48361631d691301c685e43d223582ae4892a0e285e00776dd81508e419b653508ebeb259cf6fcf7c6cb548f67a1ca5ee4ef81
+  data.tar.gz: 889ee47fb5f789c9c74c9ce2ed6d797e295c2642ac30e8402a45daa4656d7749ae7322c0ccbc82a76d48cdd1818ef032e097bff76422bcb777702bb1340ef844

data/.gitignore

@@ -38,3 +38,5 @@ test/dest
 
 /.ruby-lsp/
 /Gemfile.lock
+test/fixtures/output
+test/fixtures/tmp

data/.rubocop.yml

@@ -21,3 +21,7 @@ AllCops:
     - script/**/*
     - test/fixtures/**/*
     - vendor/**/*
+
+Metrics/BlockLength:
+  Exclude:
+    - "test/**/*"

data/CHANGELOG.md

@@ -7,7 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- ...
+- `script/release` accepts `--otp CODE` and forwards it to `gem push` via `GEM_HOST_OTP_CODE`, so a TOTP code can stand in for the WebAuthn browser handoff.
+
+## [0.4.0] - 2026-09-24
+
+### Added
+- Sidebar navigation. `bridgetown-stoa/layout` now renders a `BridgetownStoa::Sidebar` component in a left-hand `<aside>` alongside the site title and footer, with the page body in `<main class="stoa-main">`. The sidebar lists every HTML resource that has a `title`, ordered by `nav_order` (then title), and nests a page under another by setting `parent:` to the parent's title; nested sections render as `<details>` and open automatically when the current page is inside them. Set `nav_exclude: true` in front matter to hide a page. The gem's `components/` directory is now registered on the source manifest so the component can be shadowed by the host site. (#14)
+- `bin/dev` serves the `test/fixtures` site with the theme applied for browser previews. The fixture now carries a standard Bridgetown esbuild + Tailwind v4 (`@tailwindcss/postcss`) frontend, so `asset_path :css` / `:js` resolve to real bundles, and it watches the gem's `layouts/` directory so theme edits live-reload.
+
+### Fixed
+- README's Tailwind setup snippet placed `@source` between the two `@import` rules, which made Tailwind and postcss-import silently drop `@import "bridgetown-stoa"`. The imports now come first.
 
 ## [0.3.0] - 2026-05-22
 

data/Gemfile

@@ -5,6 +5,10 @@ gemspec
 
 gem "bridgetown", ENV["BRIDGETOWN_VERSION"] if ENV["BRIDGETOWN_VERSION"]
 
+group :development do
+  gem "puma" # Rack server for bin/dev
+end
+
 group :test do
   gem "minitest"
   gem "minitest-profile"

data/README.md

@@ -34,12 +34,12 @@ Then in `frontend/styles/index.css`, after `@import "tailwindcss";`, add two lin
 
 ```css
 @import "tailwindcss";
-@source "../../node_modules/bridgetown-stoa/layouts/**/*.serb";
 @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.
-- `@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.
 
@@ -77,8 +77,11 @@ Requires Ruby ≥ 3.2 and Bridgetown ≥ 2.0.
 ```shell
 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](https://www.bridgetownrb.com/docs/template-engines/erb-and-beyond), 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.
 
 ## License

data/bridgetown-stoa.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/Guided-Rails/bridgetown-stoa"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|script|spec|features|frontend)/!) }
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|script|bin|spec|features|frontend)/!) }
   spec.test_files    = spec.files.grep(%r!^test/!)
   spec.require_paths = ["lib"]
   spec.metadata      = {

data/components/bridgetown_stoa/sidebar.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+class BridgetownStoa::Sidebar < Bridgetown::Component
+  Node = Struct.new(:title, :url, :order, :parent_title, :current, :children, keyword_init: true)
+
+  def initialize(site:, current_resource:)
+    super()
+    @site = site
+    @current_resource = current_resource
+  end
+
+  def tree
+    @tree ||= build_tree
+  end
+
+  def section_open?(node)
+    return true if node.current
+
+    node.children.any? { |child| section_open?(child) }
+  end
+
+  private
+
+  def navigable_resources
+    @site.resources.select do |r|
+      next false if r.data[:nav_exclude]
+      next false unless r.data[:title]
+      next false unless r.output_ext == ".html"
+
+      true
+    end
+  end
+
+  def build_tree
+    nodes = navigable_resources.map { |r| build_node(r) }
+    by_title = nodes.to_h { |n| [n.title, n] }
+
+    roots = nodes.each_with_object([]) do |node, acc|
+      parent = node.parent_title && by_title[node.parent_title]
+      if parent && parent != node
+        parent.children << node
+      else
+        acc << node
+      end
+    end
+
+    sort_nodes!(roots)
+    roots
+  end
+
+  def build_node(resource)
+    Node.new(
+      title: resource.data[:title],
+      url: resource.relative_url,
+      order: resource.data[:nav_order],
+      parent_title: resource.data[:parent],
+      current: resource == @current_resource,
+      children: []
+    )
+  end
+
+  def sort_nodes!(nodes)
+    nodes.sort_by! { |n| [n.order || Float::INFINITY, n.title.to_s.downcase] }
+    nodes.each { |n| sort_nodes!(n.children) }
+  end
+end

data/components/bridgetown_stoa/sidebar.serb

@@ -0,0 +1,25 @@
+<nav class="stoa-sidebar" aria-label="Documentation navigation">
+  <ul>
+    {% tree.each do |node| %}
+      {% if node.children.any? %}
+        <li class="stoa-nav-parent">
+          <a href="{{ node.url }}"{% if node.current %} aria-current="page"{% end %}>{{ node.title }}</a>
+          <details{% if section_open?(node) %} open{% end %}>
+            <summary aria-label="Toggle {{ node.title }} section"></summary>
+            <ul>
+              {% node.children.each do |child| %}
+                <li>
+                  <a href="{{ child.url }}"{% if child.current %} aria-current="page"{% end %}>{{ child.title }}</a>
+                </li>
+              {% end %}
+            </ul>
+          </details>
+        </li>
+      {% else %}
+        <li>
+          <a href="{{ node.url }}"{% if node.current %} aria-current="page"{% end %}>{{ node.title }}</a>
+        </li>
+      {% end %}
+    {% end %}
+  </ul>
+</nav>

data/layouts/bridgetown-stoa/layout.serb

@@ -14,20 +14,25 @@
     {% 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>
+  <body class="stoa-shell">
+    <aside class="stoa-sidebar-shell">
+      <header class="stoa-brand">
+        <a href="/" class="stoa-site-title">{{ site.metadata.title }}</a>
+      </header>
+      {%= render BridgetownStoa::Sidebar.new(site: site, current_resource: resource) %}
+      <footer class="stoa-sidebar-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>
+    </aside>
     <main class="stoa-main">
-      {%= yield %}
+      <div class="stoa-content">
+        {%= yield %}
+      </div>
     </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.3.0"
+  VERSION = "0.4.0"
 end

data/lib/bridgetown-stoa.rb

@@ -15,6 +15,7 @@ Bridgetown.initializer :"bridgetown-stoa" do |config|
 
   config.source_manifest(
     origin: BridgetownStoa,
-    layouts: File.expand_path("../layouts", __dir__)
+    layouts: File.expand_path("../layouts", __dir__),
+    components: File.expand_path("../components", __dir__)
   )
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bridgetown-stoa",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Tailwind v4 source partial and layouts for the Stoa Bridgetown documentation theme.",
   "license": "MIT",
   "repository": {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bridgetown-stoa
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -80,6 +80,8 @@ files:
 - README.md
 - Rakefile
 - bridgetown-stoa.gemspec
+- components/bridgetown_stoa/sidebar.rb
+- components/bridgetown_stoa/sidebar.serb
 - layouts/bridgetown-stoa/layout.serb
 - lib/bridgetown-stoa.rb
 - lib/bridgetown-stoa/version.rb
@@ -88,7 +90,7 @@ homepage: https://github.com/Guided-Rails/bridgetown-stoa
 licenses:
 - MIT
 metadata:
-  yarn-add: bridgetown-stoa@0.3.0
+  yarn-add: bridgetown-stoa@0.4.0
 rdoc_options: []
 require_paths:
 - lib