ratatui_ruby-devtools 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c53c42478cc7f26dd91cca19b18ae8335e36b4a9fd2ed2a3c3a023023f6643ff
-  data.tar.gz: 66c09dcf4036b8188fd848d1cee92a2ff9da3e2b385511956af6ec58e09cb657
+  metadata.gz: 13d0c21c772a1be88c23b0345200140bc7d8befcbaf1c20d25a88230847188be
+  data.tar.gz: 54de2f06a6849dbe99f182967834c5f3ca6a24963fc98ee929cd5fc59529fbb2
 SHA512:
-  metadata.gz: 9f731aac290da1c200cd116d846d2b019dfa2bd496abb79ce90f3a826d49a57536b70db930249967eeacf7e94a5c824b955022d0b85ad585087a0d6e0af51585
-  data.tar.gz: 665b96fdaa99996adb47b9d95af710472cf364159d3b3268c3e76f2260f398cba61ba974143b18b1ad61ce82f36343e629ce6c35f5dcbfa9da8ddd183f292e80
+  metadata.gz: 28ce8dacd601f0fc068c34665d5e455523ff78fb5d43db7601341304d35c825d21fdb528ff1af09db13e35137894a3d9c0742f45b728672dce44e6da084f359f
+  data.tar.gz: 8dbf94f55d3259e14735e7b55bb57d3d4ad57d7d0423699a012b73ce820393622220a15f9fab02eb0fea47fb1db2d3a290ceda2a51cce5a696aab6bd5e7ca9b5

data/CHANGELOG.md

@@ -15,9 +15,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.1.1] - 2026-01-26
+
+### Added
+
+- Multi-version documentation website builder: `install_website_tasks!` generates
+  documentation portals with version dropdown menus. Discovers versions from git
+  tags, builds RDoc for each in isolation, and creates a landing page with
+  branding support.
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.1.0] - 2026-01-08
+
+### Added
+
 - Initial release of `ratatui_ruby-devtools`
 - Rake tasks: `lint`, `lint:fix`, `reuse`, `license`, `bump`
 - Executables: `agent_rake`, `consolidate_md`, `hbs`, `announce`
 - Templates for scaffolding new ecosystem gems
 - Auto-discovery of gem configuration from `*.gemspec`
-- Conditional Cargo/Rust task support for gems with native extensions
+- Conditional Cargo/Rust task support for gems with native extensions
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby-devtools/refs/HEAD
+[0.1.1]: https://git.sr.ht/~kerrick/ratatui_ruby-devtools/refs/v0.1.1
+[0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby-devtools/refs/v0.1.0

data/README.md

@@ -17,6 +17,23 @@ Mailing List: Development](https://img.shields.io/badge/mailing_list-development
 
 This is a **non-runtime** gem. It provides build tooling—not application features. Add it to your `:development` group only.
 
+---
+
+## Quick Links
+
+### The Ecosystem
+
+**RatatuiRuby:** [Core engine](https://git.sr.ht/~kerrick/ratatui_ruby) • **Tea:** [MVU architecture](https://git.sr.ht/~kerrick/ratatui_ruby-tea) • **Kit:** [Component architecture](https://git.sr.ht/~kerrick/ratatui_ruby-kit) (Planned) • **DSL:** [Glimmer syntax](https://sr.ht/~kerrick/ratatui_ruby/#chapter-4-the-syntax) (Planned) • **Framework:** [Omakase framework](https://git.sr.ht/~kerrick/ratatui_ruby-framework) (Planned) • **UI:** [Polished widgets](https://git.sr.ht/~kerrick/ratatui_ruby-ui) (Planned) • **UI Pro:** [More polished widgets](https://sr.ht/~kerrick/ratatui_ruby#chapter-6-licensing) (Planned)
+
+### For App Developers
+
+**Get Started:** [Quickstart](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/doc/getting_started/quickstart.md) • [Examples](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/examples) ⸺ **Stay Informed:** [Announce List](https://lists.sr.ht/~kerrick/ratatui_ruby-announce) • [FAQ](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting.md) ⸺ **Reach Out:** [Discuss List](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) • [Bug Tracker](https://todo.sr.ht/~kerrick/ratatui_ruby)
+
+### For Contributors
+
+**Get Started:** [Contributing Guide](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md) • [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md) ⸺ **Stay Informed:** [Announce List](https://lists.sr.ht/~kerrick/ratatui_ruby-announce) • [Project History](https://man.sr.ht/~kerrick/ratatui_ruby/history/index.md) ⸺ **Reach Out:** [Development List](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) • [Bug Tracker](https://todo.sr.ht/~kerrick/ratatui_ruby)
+
+---
 
 ## Installation
 

data/lib/ratatui_ruby/devtools/site_tasks/build.rake

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "fileutils"
+require "digest/md5"
+
+# Website build tasks for ecosystem documentation sites.
+#
+# These tasks sync documentation from a source gem repository, update
+# HTML metadata, and manage deployments.
+
+SOURCE_GEM_DIR = RatatuiRuby::Devtools.source_gem_dir
+PUBLIC_DOCS_DIR = File.expand_path("public/docs", Dir.pwd)
+INDEX_HTML = File.expand_path("public/index.html", Dir.pwd)
+BUILT_SHA_FILE = File.join(PUBLIC_DOCS_DIR, ".built_sha")
+
+# Shared helper to load version metadata from source gem
+def load_source_gem_metadata
+  # Find the version.rb file dynamically
+  version_files = Dir.glob(File.join(SOURCE_GEM_DIR, "lib/**/version.rb"))
+  raise "No version.rb found in #{SOURCE_GEM_DIR}" if version_files.empty?
+
+  version_file = version_files.first
+  load version_file
+
+  # Find the module that defines VERSION
+  # Convention: the namespace matches the gem name
+  gemspec_files = Dir.glob(File.join(SOURCE_GEM_DIR, "*.gemspec"))
+  raise "No gemspec found in #{SOURCE_GEM_DIR}" if gemspec_files.empty?
+
+  gem_name = File.basename(gemspec_files.first, ".gemspec")
+
+  # Convert gem_name to module name (e.g., ratatui_ruby -> RatatuiRuby)
+  module_name = gem_name.split("_").map(&:capitalize).join
+    .split("-").map(&:capitalize).join("::")
+
+  full_version = Object.const_get(module_name)::VERSION
+  raise "Could not load VERSION from #{version_file}" unless full_version
+
+  # Compute docs version (major.minor only) using Gem::Version
+  segments = Gem::Version.new(full_version).segments
+  docs_version = segments.first(2).join(".")
+
+  # Read summary from gemspec
+  gemspec_file = gemspec_files.first
+  gemspec_content = File.read(gemspec_file)
+  summary = gemspec_content[/spec\.summary\s*=\s*"([^"]+)"/, 1]
+  raise "Could not parse summary from #{gemspec_file}" unless summary
+
+  # Get datePublished from git tag's tagger date
+  tag_date = Dir.chdir(SOURCE_GEM_DIR) do
+    `git tag -l --format='%(creatordate:short)' v#{full_version} 2>/dev/null`.strip
+  end
+  tag_date = nil if tag_date.empty?
+
+  # Get copyrightYear from this version's release (each version is its own work)
+  copyright_year = tag_date&.split("-")&.first
+
+  { full_version:, docs_version:, summary:, tag_date:, copyright_year:, gem_name: }
+end
+
+def current_source_sha
+  Dir.chdir(SOURCE_GEM_DIR) { `git rev-parse trunk`.strip }
+end
+
+def docs_content_hash
+  return nil unless File.directory?(PUBLIC_DOCS_DIR)
+
+  trunk_dir = File.join(PUBLIC_DOCS_DIR, "trunk")
+  return nil unless File.directory?(trunk_dir)
+
+  digest = Digest::MD5.new
+  Dir.glob("#{PUBLIC_DOCS_DIR}/**/*", File::FNM_DOTMATCH).sort.each do |path|
+    next if File.directory?(path)
+    next if path == BUILT_SHA_FILE
+    digest.update(path)
+    digest.update(File.binread(path))
+  end
+  digest.hexdigest
+end
+
+def docs_up_to_date?
+  return false unless File.exist?(BUILT_SHA_FILE)
+
+  stored = File.read(BUILT_SHA_FILE).strip.split("\n")
+  stored_sha = stored[0]
+  stored_hash = stored[1]
+
+  return false unless stored_sha == current_source_sha
+  return false unless stored_hash == docs_content_hash
+
+  true
+end
+
+def write_build_stamp
+  File.write(BUILT_SHA_FILE, "#{current_source_sha}\n#{docs_content_hash}")
+end
+
+namespace :build do
+  desc "Build RDoc from source gem and copy to public/docs/ (FORCE=1 to rebuild)"
+  task :docs do
+    if docs_up_to_date? && !ENV["FORCE"]
+      puts "Docs already built for #{current_source_sha[0, 8]}, skipping (use FORCE=1 to rebuild)"
+      next
+    end
+
+    Bundler.with_unbundled_env do
+      Dir.chdir(SOURCE_GEM_DIR) do
+        sh "bundle install --quiet"
+        sh "bundle exec rake website:build"
+      end
+    end
+
+    www_source = File.join(SOURCE_GEM_DIR, "www")
+
+    FileUtils.rm_rf(PUBLIC_DOCS_DIR)
+    FileUtils.mkdir_p(PUBLIC_DOCS_DIR)
+
+    # Copy contents, not the directory itself, to avoid cp_r's quirky behavior
+    Dir.glob("#{www_source}/*", File::FNM_DOTMATCH).each do |entry|
+      next if entry.end_with?("/.", "/..")
+      FileUtils.cp_r(entry, PUBLIC_DOCS_DIR)
+    end
+
+    # Failsafe: if files ended up in public/docs/www/, move them up
+    nested_www = File.join(PUBLIC_DOCS_DIR, "www")
+    if File.directory?(nested_www)
+      warn "WARNING: Detected nested www/ directory, moving contents up..."
+      Dir.glob("#{nested_www}/*", File::FNM_DOTMATCH).each do |entry|
+        next if entry.end_with?("/.", "/..")
+        FileUtils.mv(entry, PUBLIC_DOCS_DIR)
+      end
+      FileUtils.rmdir(nested_www)
+    end
+
+    # Write SHA + content hash after successful build
+    write_build_stamp
+
+    puts "Copied docs to #{PUBLIC_DOCS_DIR} (#{current_source_sha[0, 8]})"
+  end
+
+  desc "Update index.html with version metadata from source gem"
+  task :html do
+    meta = load_source_gem_metadata
+
+    html = File.read(INDEX_HTML)
+
+    if html =~ /"softwareVersion":\s*"([^"]+)"/
+      old_version = $1
+      old_docs = old_version.split(".").first(2).join(".")
+
+      # Plain string replacement for all occurrences
+      # Bare version catches both "v1.1.0" and "gem_name-1.1.0.gem"
+      html.gsub!(old_version, meta[:full_version])
+      html.gsub!("v#{old_docs}/", "v#{meta[:docs_version]}/")
+
+      # Update description from gemspec summary
+      html.gsub!(/"description":\s*"[^"]+"/, %{"description": "#{meta[:summary]}"})
+
+      # Update datePublished from git tag date
+      if meta[:tag_date]
+        html.gsub!(/"datePublished":\s*"[^"]+"/, %{"datePublished": "#{meta[:tag_date]}"})
+      end
+
+      # Update copyrightYear from first release
+      if meta[:copyright_year]
+        html.gsub!(/"copyrightYear":\s*\d+/, %{"copyrightYear": #{meta[:copyright_year]}})
+      end
+
+      File.write(INDEX_HTML, html)
+    else
+      warn "WARNING: No softwareVersion found in index.html JSON-LD, skipping version update"
+    end
+
+    puts "Updated index.html to version v#{meta[:full_version]} (docs: v#{meta[:docs_version]})"
+  end
+end
+
+desc "Build docs and update index.html"
+task build: ["build:docs", "build:html"]

data/lib/ratatui_ruby/devtools/site_tasks/deploy.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Uses PUBLIC_DOCS_DIR from build.rake
+
+desc "Deploy to production (builds first, validates docs)"
+task deploy: :build do
+  trunk_dir = File.join(PUBLIC_DOCS_DIR, "trunk")
+  unless File.directory?(trunk_dir)
+    abort "ERROR: #{trunk_dir} does not exist. Run `rake build:docs` first."
+  end
+
+  sh "kamal deploy"
+end

data/lib/ratatui_ruby/devtools/site_tasks/serve.rake

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+desc "Serve public/ locally on http://localhost:8000"
+task :serve do
+  require "webrick"
+  server = WEBrick::HTTPServer.new(Port: 8000, DocumentRoot: File.expand_path("public", Dir.pwd))
+  trap("INT") { server.shutdown }
+  server.start
+end

data/lib/ratatui_ruby/devtools/tasks/resources/index.html.erb

@@ -0,0 +1,129 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+<%
+  # Branding configuration with sensible defaults
+  logo_small = branding[:logo_small] || "../logo-small.png"
+  wordmark = branding[:wordmark] || project_name
+  tagline = branding[:tagline] || "API documentation and guides"
+  
+  # Navigation links (array of {text:, href:} hashes)
+  nav_links = branding[:nav_links] || []
+  
+  # Footer columns (array of {heading:, links: [{text:, href:, tag:, tag_muted:}]} hashes)
+  footer_columns = branding[:footer_columns] || []
+  
+  # Footer bottom bar
+  footer_meta_links = branding[:footer_meta_links] || []
+  copyright = branding[:copyright] || "© #{Time.now.year}"
+  license_text = branding[:license_text] || ""
+  
+  # CSS/font customization
+  stylesheet = branding[:stylesheet] || "../styles.css"
+  google_fonts_url = branding[:google_fonts_url]
+  
+  # Find latest version for default links
+  latest = versions.find { |v| v.respond_to?(:latest?) && v.latest? }
+  latest_slug = latest&.slug || "trunk"
+%>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title><%= project_name %> documentation</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="<%= tagline %> for <%= project_name %>, organized by version.">
+  <link rel="stylesheet" href="<%= stylesheet %>">
+  <% if google_fonts_url %>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="<%= google_fonts_url %>" rel="stylesheet">
+  <% end %>
+</head>
+<body>
+  <header class="header">
+    <div class="header__inner">
+      <a href="/" class="header__brand">
+        <img src="<%= logo_small %>" alt="<%= project_name %> Logo" class="header__logo" width="48" height="48">
+        <span class="header__wordmark"><%= wordmark %></span>
+      </a>
+      <% unless nav_links.empty? %>
+      <nav class="header__nav" aria-label="Primary">
+        <% nav_links.each do |link| %>
+        <a href="<%= link[:href] %>"<%= ' class="header__nav-external"' if link[:external] %>><%= link[:text] %></a>
+        <% end %>
+      </nav>
+      <% end %>
+    </div>
+  </header>
+
+  <main>
+    <section class="section">
+      <div class="section__inner">
+        <header class="section__header">
+          <span class="section__eyebrow">Reference</span>
+          <h1 class="section__title">Documentation</h1>
+          <p class="section__intro"><%= tagline %> for current and past versions of <%= project_name %>.</p>
+        </header>
+
+        <ul class="version-list">
+          <% versions.each do |version| %>
+            <li class="version-list__item<%= ' version-list__item--latest' if version.latest? %>">
+              <a href="<%= version.slug %>/index.html" class="version-list__link">
+                <span class="version-list__name"><%= version.name %></span>
+                <span class="version-list__meta">
+                  <% if version.latest? %>
+                    Latest release via RubyGems
+                  <% elsif version.edge? %>
+                    Pre-release via git
+                  <% else %>
+                    Historical
+                  <% end %>
+                </span>
+              </a>
+            </li>
+          <% end %>
+        </ul>
+      </div>
+    </section>
+  </main>
+
+  <footer class="footer">
+    <div class="footer__inner">
+      <% unless footer_columns.empty? %>
+      <!-- Megafooter columns -->
+      <div class="footer__columns">
+        <% footer_columns.each do |column| %>
+        <div class="footer__column">
+          <h3 class="footer__heading"><%= column[:heading] %></h3>
+          <ul class="footer__list">
+            <% column[:links].each do |link| %>
+            <li><a href="<%= link[:href] %>"><%= link[:text] %><% if link[:tag] %> <span class="footer__tag<%= ' footer__tag--muted' if link[:tag_muted] %>"><%= link[:tag] %></span><% end %></a></li>
+            <% end %>
+          </ul>
+        </div>
+        <% end %>
+      </div>
+      <% end %>
+
+      <!-- Bottom bar -->
+      <div class="footer__bottom">
+        <div class="footer__brand">
+          <img src="<%= logo_small %>" alt="" class="footer__logo" width="32" height="32" aria-hidden="true">
+          <span class="footer__wordmark"><%= wordmark %></span>
+        </div>
+        <% unless footer_meta_links.empty? %>
+        <nav class="footer__meta" aria-label="Meta links">
+          <% footer_meta_links.each do |link| %>
+          <a href="<%= link[:href] %>"><%= link[:text] %></a>
+          <% end %>
+        </nav>
+        <% end %>
+        <p class="footer__copy"><%= copyright %><% if license_text && !license_text.empty? %> · <%= license_text %><% end %></p>
+      </div>
+    </div>
+  </footer>
+</body>
+</html>

data/lib/ratatui_ruby/devtools/tasks/website/index_page.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "erb"
+
+# Landing page for multi-version documentation portals.
+#
+# Documentation websites need a version picker. Users land on the portal
+# and choose their version. Without a landing page, they'd need to guess
+# the URL.
+#
+# This class generates an index page with version links and optional
+# branding. It marks the newest tagged release as "(latest)".
+#
+# Use it to build the root <tt>index.html</tt> for documentation portals.
+class IndexPage
+  # Creates an IndexPage.
+  #
+  # Marks the newest Tagged version as latest for display.
+  #
+  # [versions] Array of Version objects.
+  # [branding] Optional hash of branding overrides for the template.
+  def initialize(versions, branding: {})
+    @versions = versions
+    @branding = branding
+
+    latest_version = @versions.find { |v| v.is_a?(Tagged) }
+    latest_version.is_latest = true if latest_version
+  end
+
+  # Renders the landing page HTML to a file.
+  #
+  # Uses an ERB template with version links and branding.
+  #
+  # [path] Output file path.
+  # [project_name] Project name for page title.
+  def publish_to(path, project_name:)
+    puts "Generating index page..."
+
+    template_path = File.expand_path("../resources/index.html.erb", __dir__)
+    template = File.read(template_path)
+
+    versions = @versions
+    branding = @branding
+    # project_name is used in the ERB
+    html_content = ERB.new(template).result(binding)
+
+    File.write(path, html_content)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website/version.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rubygems"
+require "fileutils"
+
+# A documentation version for multi-version websites.
+#
+# Documentation websites need to serve multiple versions. Users browse docs
+# for their installed release. Maintainers preview trunk changes. Manually
+# tracking git tags and branches is tedious.
+#
+# This class discovers versions from git tags. It extracts source files at
+# each ref. It provides metadata for version menus.
+#
+# Use it to build multi-version documentation portals.
+class Version
+  # Discovers all available versions.
+  #
+  # Returns Edge (trunk) plus the latest patch for each minor version,
+  # sorted newest first.
+  def self.all
+    tags = `git tag`.split.grep(/^v\d/)
+    sorted_versions = tags.map { |t| Tagged.new(t) }
+      .sort_by(&:semver)
+      .reverse
+
+    # Keep only the latest patch for each minor version
+    # e.g., if we have v0.6.0, v0.6.1, v0.6.2, only keep v0.6.2
+    latest_per_minor = sorted_versions
+      .group_by { |v| v.semver.segments[0..1] } # group by [major, minor]
+      .values
+      .map(&:first) # take the first (highest patch) from each group
+
+    [Edge.new] + latest_per_minor
+  end
+
+  # URL-safe identifier for this version.
+  def slug
+    raise NotImplementedError
+  end
+
+  # Human-readable name for version menus.
+  def name
+    raise NotImplementedError
+  end
+
+  # Version type: <tt>:edge</tt> or <tt>:version</tt>.
+  def type
+    raise NotImplementedError
+  end
+
+  # Git ref (branch or tag) for checkout.
+  def ref
+    raise NotImplementedError
+  end
+
+  # Yields a temporary directory containing this version's source.
+  #
+  # Exports the git archive at the specified ref. Removes the native
+  # extension directory to avoid compilation issues.
+  #
+  # [globs] File patterns (unused, for API compatibility).
+  def checkout(globs:, &block)
+    Dir.mktmpdir do |path|
+      # Use git archive to export the version at the specified ref
+      # Pipe to tar to extract into the temporary directory
+      system("git archive #{ref} | tar -x -C #{path}")
+
+      # Remove the native extension directory as we don't need it for builds
+      # and it can cause issues if not meant to be compiled in this context
+      FileUtils.rm_rf("#{path}/ext")
+
+      yield path
+    end
+  end
+
+  # Returns <tt>true</tt> if this is the latest stable release.
+  def latest?
+    false
+  end
+
+  # Returns <tt>true</tt> if this is the edge (trunk) version.
+  def edge?
+    false
+  end
+end
+
+# The trunk branch version for unreleased changes.
+#
+# Developers preview upcoming features before release. The edge version
+# builds documentation from trunk.
+class Edge < Version
+  # Stable URL path for bookmarks. Trunk docs live at <tt>/trunk/</tt>.
+  def slug
+    "trunk"
+  end
+
+  # Appears in version menus as-is, without version numbering.
+  def name
+    "trunk"
+  end
+
+  # Distinguishes unreleased docs from tagged releases in conditionals.
+  def type
+    :edge
+  end
+
+  # Git branch name for archive extraction.
+  def ref
+    "trunk"
+  end
+
+  # Identifies this as unreleased for "(dev)" labels in menus.
+  def edge?
+    true
+  end
+end
+
+# A Git release tag version.
+#
+# Each release gets a tag like <tt>v0.6.0</tt>. The documentation website
+# shows only the latest patch for each minor version.
+class Tagged < Version
+  # The raw Git tag for archive extraction.
+  attr_reader :tag
+
+  # Creates a Tagged version.
+  #
+  # [tag] Git tag string.
+  def initialize(tag)
+    @tag = tag
+  end
+
+  # Groups patch releases under one URL. Docs for <tt>v0.6.0</tt> and
+  # <tt>v0.6.1</tt> both live at <tt>/v0.6/</tt>.
+  def slug
+    segments = semver.segments
+    "v#{segments[0]}.#{segments[1]}"
+  end
+
+  # Shows exact version in menus. Users know which patch they're viewing.
+  def name
+    @tag
+  end
+
+  # Distinguishes released docs from trunk in conditionals.
+  def type
+    :version
+  end
+
+  # Git tag for archive extraction.
+  def ref
+    @tag
+  end
+
+  # Enables sorting and grouping by semantic version rules.
+  def semver
+    Gem::Version.new(@tag.sub(/^v/, ""))
+  end
+
+  # Set by IndexPage to enable "(latest)" label in menus.
+  attr_accessor :is_latest
+
+  # Identifies this for "(latest)" labels in menus.
+  def latest?
+    @is_latest
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website/version_menu.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Version switcher for generated documentation pages.
+#
+# Multi-version docs need navigation between versions. Users viewing
+# <tt>v0.5</tt> docs want to switch to <tt>v0.6</tt>. Without a switcher,
+# they'd need to navigate back to the portal.
+#
+# This class injects a dropdown menu into every generated HTML page.
+# It calculates relative paths so links work from any nesting depth.
+#
+# Use it after generating all version documentation.
+class VersionMenu
+  # Creates a VersionMenu.
+  #
+  # [root] Root directory of the generated site.
+  # [versions] Array of Version objects for the dropdown.
+  def initialize(root:, versions:)
+    @root = root
+    @versions = versions
+  end
+
+  # Injects the version dropdown into all HTML files.
+  #
+  # Finds the theme toggle button and inserts the menu before it.
+  def run
+    puts "Injecting version menu into generated HTML..."
+
+    # Process all HTML files in the output directory
+    Dir.glob(File.join(@root, "**/*.html")).each do |file|
+      inject_menu(file)
+    end
+  end
+
+  private def inject_menu(file)
+    content = File.read(file)
+
+    # Find the injection point (before the theme toggle button)
+    pattern = /(<button[^>]*id="theme-toggle"[^>]*>)/mi
+
+    unless content.match?(pattern)
+      # warn "Could not find theme-toggle in #{file}"
+      return
+    end
+
+    # Calculate relative path to root from this file
+    file_dir = File.dirname(file)
+    relative_path_to_root = Pathname.new(@root).relative_path_from(Pathname.new(file_dir)).to_s
+    relative_path_to_root += "/" unless relative_path_to_root.end_with?("/")
+
+    # Determine current version from file path
+    relative_path_from_root = Pathname.new(file).relative_path_from(Pathname.new(@root)).to_s
+    current_version_slug = relative_path_from_root.split("/").first
+
+    # Build options
+    options = @versions.map do |version|
+      value = "#{relative_path_to_root}#{version.slug}/index.html"
+      selected = (version.slug == current_version_slug) ? "selected" : ""
+      display_name = version.name
+      display_name += " (latest)" if version.respond_to?(:latest?) && version.latest?
+      display_name += " (dev)" if version.edge?
+
+      %Q{<option value="#{value}" #{selected}>#{display_name}</option>}
+    end.join("\n")
+
+    # margin-left: auto pushes it to the right
+    # margin-right: 1rem spacing from the theme toggle
+    switcher_html = <<~HTML
+      <select class="version-menu" onchange="window.location.href=this.value" style="margin-left: auto; padding: 0.25rem; border-radius: 4px; border: 1px solid #ccc; margin-right: 1rem;">
+        #{options}
+        <option value="#{relative_path_to_root}index.html">All Versions</option>
+      </select>
+    HTML
+
+    # Inject before the button
+    new_content = content.sub(pattern, "#{switcher_html}\n\\1")
+
+    File.write(file, new_content)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website/versioned_documentation.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "../rdoc_config"
+
+# Builds documentation for a single version.
+#
+# Multi-version sites need docs generated from each git ref. Building
+# locally would pollute the working directory. Using git checkout would
+# disrupt work in progress.
+#
+# This class extracts source files to a temp directory and runs RDoc.
+# It copies the output to the target path. It preserves the current
+# working directory.
+#
+# Use it to build one version's documentation within a multi-version site.
+class VersionedDocumentation
+  # Creates a VersionedDocumentation builder.
+  #
+  # [version] Version object to build docs for.
+  def initialize(version)
+    @version = version
+  end
+
+  # Generates and publishes documentation for this version.
+  #
+  # Extracts source to a temp directory, runs RDoc, and copies output.
+  # Falls back to direct RDoc if rake fails.
+  #
+  # [path] Output directory for generated docs.
+  # [project_name] Project name for RDoc title.
+  # [globs] File patterns to document.
+  # [assets] Optional directories to copy into output.
+  def publish_to(path, project_name:, globs:, assets: [])
+    puts "Building documentation for #{@version.name}..."
+
+    absolute_path = File.absolute_path(path)
+    gemfile_path = File.absolute_path("Gemfile")
+    custom_css_path = File.absolute_path("doc/custom.css")
+    rakefile_path = File.absolute_path("Rakefile")
+    tasks_dir_path = File.absolute_path("tasks")
+
+    @version.checkout(globs:) do |source_path|
+      # Copy current Rakefile and tasks into the temp directory
+      # This ensures all versions use the latest example generation logic
+      FileUtils.cp(rakefile_path, File.join(source_path, "Rakefile"))
+      FileUtils.cp_r(tasks_dir_path, File.join(source_path, "tasks"))
+
+      Dir.chdir(source_path) do
+        title = "#{project_name} #{@version.name}"
+        title = "#{project_name} (trunk)" if @version.edge?
+
+        # Use rake rerdoc to ensure copy_examples runs
+        # Set environment variables to override rdoc settings
+        success = system(
+          {
+            "BUNDLE_GEMFILE" => gemfile_path,
+            "RDOC_OUTPUT" => absolute_path,
+            "RDOC_TITLE" => title,
+            "RDOC_CUSTOM_CSS" => custom_css_path,
+          },
+          "bundle exec rake rerdoc"
+        )
+
+        # Fall back to direct rdoc call if rake fails for any reason
+        unless success
+          puts "  Rake task failed, falling back to direct rdoc call..."
+          files = globs.flat_map { |glob| Dir[glob] }.uniq
+          system(
+            { "BUNDLE_GEMFILE" => gemfile_path },
+            "bundle exec rdoc -o #{absolute_path} --main #{RDocConfig::MAIN} --title '#{title}' --template-stylesheets \"#{custom_css_path}\" #{files.join(' ')}"
+          )
+        end
+
+        # Copy generated documentation to target path if it was generated elsewhere
+        # This handles cases where RDOC_OUTPUT wasn't respected (evaluated at load time)
+        temp_output_paths = ["tmp/rdoc", "doc"]
+        temp_output_paths.each do |temp_path|
+          # Check if this looks like generated rdoc (has index.html)
+          if Dir.exist?(temp_path) && !Dir.empty?(temp_path) && File.exist?(File.join(temp_path, "index.html"))
+            puts "  Copying generated docs from #{temp_path} to #{absolute_path}..."
+            FileUtils.mkdir_p(absolute_path)
+            FileUtils.cp_r Dir["#{temp_path}/*"], absolute_path
+            break
+          end
+        end
+
+        copy_assets_to(absolute_path, assets)
+      end
+    end
+  end
+
+  private def copy_assets_to(path, assets)
+    assets.each do |asset_dir|
+      if Dir.exist?(asset_dir)
+        destination = File.join(path, asset_dir)
+        FileUtils.mkdir_p(destination)
+        FileUtils.cp_r Dir["#{asset_dir}/*"], destination
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website/website.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "version"
+require_relative "versioned_documentation"
+require_relative "index_page"
+require_relative "version_menu"
+require "fileutils"
+
+# Multi-version documentation website builder.
+#
+# Projects need documentation for multiple versions. Users on v0.5 read
+# v0.5 docs. Users on trunk preview upcoming changes. Building this
+# manually is tedious and error-prone.
+#
+# This class orchestrates the entire build: discovers versions, generates
+# docs for each, creates the landing page, and injects version menus.
+#
+# Use it to build a complete documentation portal.
+class Website
+  # Creates a Website builder.
+  #
+  # [at] Output directory (default: <tt>www</tt>).
+  # [project_name] Project name for page titles.
+  # [globs] File patterns to document.
+  # [assets] Optional directories to copy into each version's output.
+  # [branding] Optional hash of branding overrides for the index template.
+  def initialize(at: "www", project_name:, globs:, assets: [], branding: {})
+    @destination = at
+    @project_name = project_name
+    @globs = globs
+    @assets = assets
+    @branding = branding
+  end
+
+  # Builds the complete documentation website.
+  #
+  # Cleans the output directory, generates docs for all versions,
+  # creates the landing page, and injects version menus.
+  def build
+    clean
+
+    versions.each do |version|
+      VersionedDocumentation.new(version).publish_to(
+        join(version.slug),
+        project_name: @project_name,
+        globs: @globs,
+        assets: @assets
+      )
+    end
+
+    IndexPage.new(versions, branding: @branding).publish_to(join("index.html"), project_name: @project_name)
+
+    VersionMenu.new(root: @destination, versions:).run
+
+    puts "Website built in #{@destination}/"
+  end
+
+  # Discovered versions for this build.
+  #
+  # Cached after first call. Includes Edge plus latest patch per minor.
+  def versions
+    @versions ||= Version.all
+  end
+
+  private def join(path)
+    File.join(@destination, path)
+  end
+
+  private def clean
+    FileUtils.rm_rf(@destination)
+    FileUtils.mkdir_p(@destination)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/website.rake

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "erb"
+require "fileutils"
+require "tmpdir"
+require_relative "rdoc_config"
+
+namespace :website do
+  desc "Build documentation for trunk (current dir) and all git tags"
+  task :build do
+    require_relative "website/website"
+
+    spec = Gem::Specification.load(Dir["*.gemspec"].first)
+    globs = RDocConfig::RDOC_FILES + ["*.gemspec", "doc/images/**/*", "examples/**/*"]
+
+    # Allow projects to customize via website_config.rb in their tasks/ directory
+    config = if File.exist?("tasks/website_config.rb")
+      load File.expand_path("tasks/website_config.rb", Dir.pwd)
+      WebsiteConfig::CONFIG
+    else
+      {}
+    end
+
+    Website.new(
+      at: config[:output_dir] || "www",
+      project_name: spec.name,
+      globs:,
+      assets: config[:assets] || ["doc/images"],
+      branding: config[:branding] || {}
+    ).build
+  end
+end

data/lib/ratatui_ruby/devtools/version.rb

@@ -8,6 +8,6 @@
 module RatatuiRuby
   module Devtools
     # Current version of the ratatui_ruby-devtools gem.
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/ratatui_ruby/devtools.rb

@@ -40,19 +40,48 @@ module RatatuiRuby
       # Configuration accessors - auto-discovered if not set
       attr_writer :gem_name, :gemspec_file, :version_file
 
-      # Loads all devtools Rake tasks into the current application.
+      # Loads gem development Rake tasks (test, lint, bump, license, etc.)
       #
-      # Consumer gems need shared tasks for linting, testing, and licensing.
-      # Manually copying rake files is tedious and leads to drift. Call this
-      # once in your Rakefile to import all devtools tasks.
+      # Use this in gem/library Rakefiles. These tasks help with version
+      # management, testing, linting, and releasing gems.
       #
       # === Example
       #
       #   require "ratatui_ruby/devtools"
-      #   RatatuiRuby::Devtools.install!
+      #   RatatuiRuby::Devtools.install_gem_tasks!
       #
-      def install!
-        tasks_dir = File.expand_path("devtools/tasks", __dir__)
+      def install_gem_tasks!
+        load_tasks_from("tasks")
+      end
+
+      # Loads website hosting Rake tasks (build, serve, deploy).
+      #
+      # Use this in website repository Rakefiles. These tasks help sync docs
+      # from a source gem, update HTML metadata, and deploy.
+      #
+      # @param source_gem_dir [String] Path to the source gem directory
+      #   (e.g., "~/Developer/ratatui_ruby")
+      #
+      # === Example
+      #
+      #   require "ratatui_ruby/devtools"
+      #   RatatuiRuby::Devtools.install_website_tasks!(
+      #     source_gem_dir: "~/Developer/ratatui_ruby"
+      #   )
+      #
+      def install_website_tasks!(source_gem_dir:)
+        @source_gem_dir = File.expand_path(source_gem_dir)
+        load_tasks_from("site_tasks")
+      end
+
+      # Returns the source gem directory for website tasks.
+      attr_reader :source_gem_dir
+
+      # Backwards-compatible alias for install_gem_tasks!
+      alias install! install_gem_tasks!
+
+      private def load_tasks_from(subdir)
+        tasks_dir = File.expand_path("devtools/#{subdir}", __dir__)
         Dir.glob("#{tasks_dir}/*.rake").each do |task_file|
           Rake.application.add_import(task_file)
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby-devtools
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kerrick Long
@@ -162,6 +162,9 @@ files:
 - exe/hbs
 - exe/scaffold
 - lib/ratatui_ruby/devtools.rb
+- lib/ratatui_ruby/devtools/site_tasks/build.rake
+- lib/ratatui_ruby/devtools/site_tasks/deploy.rake
+- lib/ratatui_ruby/devtools/site_tasks/serve.rake
 - lib/ratatui_ruby/devtools/tasks/autodoc.rake
 - lib/ratatui_ruby/devtools/tasks/autodoc/examples.rb
 - lib/ratatui_ruby/devtools/tasks/autodoc/member.rb
@@ -188,10 +191,17 @@ files:
 - lib/ratatui_ruby/devtools/tasks/lint.rake
 - lib/ratatui_ruby/devtools/tasks/rdoc_config.rb
 - lib/ratatui_ruby/devtools/tasks/resources/build.yml.erb
+- lib/ratatui_ruby/devtools/tasks/resources/index.html.erb
 - lib/ratatui_ruby/devtools/tasks/resources/rubies.yml
 - lib/ratatui_ruby/devtools/tasks/reuse.rake
 - lib/ratatui_ruby/devtools/tasks/sourcehut.rake
 - lib/ratatui_ruby/devtools/tasks/test.rake
+- lib/ratatui_ruby/devtools/tasks/website.rake
+- lib/ratatui_ruby/devtools/tasks/website/index_page.rb
+- lib/ratatui_ruby/devtools/tasks/website/version.rb
+- lib/ratatui_ruby/devtools/tasks/website/version_menu.rb
+- lib/ratatui_ruby/devtools/tasks/website/versioned_documentation.rb
+- lib/ratatui_ruby/devtools/tasks/website/website.rb
 - lib/ratatui_ruby/devtools/templates/.builds/ruby.yml.erb
 - lib/ratatui_ruby/devtools/templates/.gitignore.erb
 - lib/ratatui_ruby/devtools/templates/.pre-commit-config.yaml.erb