sitepress-rails 5.0.0.beta2 → 5.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d647985fa6763a9361d1af2906f6a1c22cc1cfd4e0e9cb010c010d088ab143eb
-  data.tar.gz: facf3d69378e4abb6c8d32aa8b27e68ee413105df011990584df7241b9624c18
+  metadata.gz: 443c3d5ccdfa98e1b995ae899d3d8e20dd7ffb4c98a8d5700be29384847e838d
+  data.tar.gz: a7664658ced9775dbbde217f0247933851edbbbebb6c2cd5ca8d1e893163f2fd
 SHA512:
-  metadata.gz: fa6aa939414cc4ddf067c01153b8488e7d224d5dcf0af9831f071e407f5e71de19f57770b48144fc491aec2ecb2a40d4efa0d0887bb10f80f28f282f86446331
-  data.tar.gz: a0f9a313a88e42902d0388196dc9541368d1e88fcc6fffb0fb92e8df4d56dbc707f465d7578fecb5dc1847527bd41766d67af0c9b1b302c30ab8a7ce02a899c9
+  metadata.gz: e092de737d65d1e5eca7eefedcdf1f1129af9872e1fdca7418c5bf0b9192fe9fd71c885698779fe120f958c1e525f734a1fd919b3e457646354bbc3eb78e8e25
+  data.tar.gz: 3eab694d5c52e70410f9f2dde9421e31f5a329aed6f83bd5d447df29df2b9b870cef72a128627810fc7552277f071d88b59aae3b0803a9436826ced73e16fab0

data/README.md

@@ -25,6 +25,77 @@ sitepress_root # Delete if you don't want your app's root page to be a content p
 
 Restart the Rails application server and point your browser to `http://127.0.0.1:3000/` and if all went well you should see a sitepress page.
 
+## Multiple sites in a single Rails app
+
+You can serve any number of Sitepress sites from one Rails app — for example a marketing site at `/` and an admin docs site at `/admin/docs`. Three pieces, plain Ruby:
+
+```ruby
+# 1. config/initializers/sitepress.rb — register the site at boot
+Sitepress.sites << Sitepress::Site.new(root_path: "app/sitepress/admin_docs")
+```
+
+```ruby
+# 2. app/controllers/admin/docs_controller.rb — bind it to a controller
+class Admin::DocsController < Sitepress::SiteController
+  self.site = Sitepress.sites.fetch("app/sitepress/admin_docs")
+
+  layout "admin"
+  before_action :require_admin
+end
+```
+
+```ruby
+# 3. config/routes.rb — mount the controller
+Rails.application.routes.draw do
+  sitepress_pages   # default site at /
+
+  namespace :admin do
+    scope :docs do
+      sitepress_pages controller: "admin/docs", as: :admin_doc
+    end
+  end
+end
+```
+
+The whole multi-site API is two methods on `Sitepress`: `Sitepress.site` (the configured default, unchanged) and `Sitepress.sites` (the registry). The registry has three operations — `<<` to add, `fetch` to look up by `root_path` (raises `NotFoundError` listing registered paths on miss), and `each` plus the rest of `Enumerable` for iteration.
+
+A typo in the path string fails loud at controller class load:
+
+```
+NotFoundError: No Sitepress site registered at "app/contnet".
+Registered: ["app/sitepress/admin_docs"]
+```
+
+**Why three pieces and not one?** Boot ordering forces it. Zeitwerk needs helper / model paths registered before its eager-load pass, which happens before the first request — that's what `Sitepress.sites <<` does and it's the only piece that *has* to live in an initializer. The controller binding (`self.site = ...`) is just `class_attribute` plus a writer that `prepend_view_path`s the site's view directories onto *this controller's* lookup chain (so multi-site view lookups stay local — no global ActionView pollution). Routes own the URL → controller binding, with the mount path read from the surrounding `scope`/`namespace`.
+
+The same site can be referenced by more than one controller — a public reader and an admin editor can both `Sitepress.sites.fetch("...")` and bind to the same content tree. The Site itself is registered once.
+
+### Generator
+
+```bash
+bin/rails generate sitepress:site app/sitepress/admin_docs
+```
+
+Scaffolds the content directory tree (`pages/`, `helpers/`, `models/`, `assets/`), a stub index template, a controller subclass with `self.site = Sitepress.sites.fetch(...)` already filled in, and either creates or appends to `config/initializers/sitepress.rb` with the registration line. Pass `--mount-at=/admin/docs` to also inject a `scope` block into `config/routes.rb`; without the flag, the generator just prints the routes line for you to paste.
+
+### Rake tasks
+
+Compilation is split into single-site and multi-site forms so single-site users don't get a behavior change when they add a registered site:
+
+- `rake sitepress:compile` — compiles the configured default site only.
+- `rake sitepress:sites:compile` — compiles every registered site (default + `Sitepress.sites`) to `tmp/sitepress/<basename>`. Each site lives in its own subdirectory so two sites never collide on output.
+- `rake "sitepress:sites:compile[app/sitepress/admin_docs]"` — compiles a single registered site by `root_path`. Raises `Sitepress::NotFoundError` listing registered paths if no match.
+- `rake sitepress:sites` — lists the configured default site and everything in `Sitepress.sites`.
+
+Two env vars adjust the compile tasks:
+
+- `OUTPUT_PATH=build rake sitepress:sites:compile` — overrides the default `tmp/sitepress` build root.
+- `FAIL_ON_ERROR=true rake sitepress:sites:compile` — raises on the first resource that fails to render. Default (`false`) collects all failures and prints a summary at the end.
+
+After every compile run, the tasks print a `Compilation Summary` block listing how many sites were built, how many resources succeeded/failed, and (if any failed) the path of every failing resource paired with the site it lives in.
+
+These tasks only handle content compilation. Run your asset bundler (Propshaft, esbuild, Tailwind, etc.) separately if you have static assets to build.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/sitepress/compilers.rb

@@ -0,0 +1,57 @@
+module Sitepress
+  # A dumb collection of compiler instances. Holds anything that
+  # responds to `#compile` (typically `Sitepress::Compiler::Files`),
+  # and runs them in order when you call `#compile`. The collection
+  # has no opinion about how its members were constructed, where they
+  # write, or what sites they're bound to — that's all the caller's
+  # job.
+  #
+  #   compilers = Sitepress::Compilers.new
+  #   compilers << Sitepress::Compiler::Files.new(site: foo, root_path: "build/foo")
+  #   compilers << Sitepress::Compiler::Files.new(site: bar, root_path: "build/bar")
+  #   compilers.compile
+  #
+  # `Enumerable` is mixed in, so `compilers.flat_map(&:succeeded)`
+  # and `compilers.flat_map(&:failed)` work for aggregating across
+  # the underlying compilers.
+  class Compilers
+    include Enumerable
+
+    def initialize(compilers = [])
+      @compilers = compilers.to_a
+    end
+
+    # Add a single compiler to the collection. Returns self per Ruby's
+    # `<<` convention so additions chain.
+    def <<(compiler)
+      @compilers << compiler
+      self
+    end
+
+    # Merge an iterable of compilers into the collection. Mirrors
+    # `Array#concat` — accepts anything responding to `#to_a` (Array,
+    # another Compilers, lazy enumerator, etc.) and adds each element
+    # individually.
+    #
+    #   compilers.concat([c1, c2, c3])
+    #   compilers.concat(other_compilers)
+    #   compilers.concat(sites.map { |s| Compiler::Files.new(...) })
+    #
+    # Returns self for chaining.
+    def concat(other)
+      @compilers.concat(other.to_a)
+      self
+    end
+
+    # Run `#compile` on every compiler in the collection in order.
+    # Returns self for chaining.
+    def compile
+      @compilers.each(&:compile)
+      self
+    end
+
+    def each(&block)
+      @compilers.each(&block)
+    end
+  end
+end

data/lib/sitepress/engine.rb

@@ -24,22 +24,27 @@ module Sitepress
       "app/markdown"                      # When Sitepress is launched embedded in Rails project.
     ], autoload: true
 
-    # Load paths from `Sitepress#site` into Rails.
+    # Load paths from Sitepress sites into Rails.
     #
-    # We configure two separate systems:
+    # The work is split across two initializers because of Rails' boot
+    # ordering: the *default* site is set up before `:set_autoload_paths`
+    # (so its paths land in `config.autoload_paths` the normal way),
+    # but *registered* sites have to wait until after
+    # `:load_config_initializers` runs — that's where the user's
+    # `config/initializers/sitepress.rb` (with `Sitepress.sites << ...`)
+    # populates the registry. By the time we iterate the registry,
+    # `:set_autoload_paths` has already frozen `config.autoload_paths`,
+    # so we push paths directly to `Rails.autoloaders.main` (which
+    # accepts additions any time before eager loading).
     #
-    # 1. app.paths["app/*"] - Rails component path registry
-    #    Tells ActionView where to find templates, ActionController where to find helpers, etc.
-    #
-    # 2. config.autoload_paths - Zeitwerk autoloader configuration
-    #    Tells Zeitwerk what to autoload. Rails automatically includes these in
-    #    config.eager_load_paths for production environments.
-    #
-    initializer "sitepress.set_paths", before: :set_autoload_paths do |app|
+    # The default site gets views added to `app/views` globally; the
+    # default `Sitepress::SiteController` reads from there. Registered
+    # sites' views live on the controller via `prepend_view_path` so
+    # multi-site view lookups stay local to the controller.
+
+    initializer "sitepress.set_default_site_paths", before: :set_autoload_paths do |app|
       site = Sitepress.configuration.site
 
-      # Helpers: autoloadable and available to controllers
-      # Collapsed so app/content/helpers/sample_helper.rb defines SampleHelper (not Helpers::SampleHelper)
       site.helpers_path.expand_path.tap do |path|
         if path.exist?
           app.paths["app/helpers"].push path
@@ -50,8 +55,6 @@ module Sitepress
         end
       end
 
-      # Models: autoloadable
-      # Collapsed so models don't require namespace prefixes
       site.models_path.expand_path.tap do |path|
         if path.exist?
           app.paths["app/models"].push path
@@ -62,21 +65,43 @@ module Sitepress
         end
       end
 
-      # Assets: available to Sprockets (no autoloading needed)
       app.paths["app/assets"].push site.assets_path.expand_path
+      app.paths["app/views"].push  site.root_path.expand_path
+      app.paths["app/views"].push  site.pages_path.expand_path
+    end
 
-      # Views: available to ActionView (no autoloading needed - these are templates)
-      app.paths["app/views"].push site.root_path.expand_path
-      app.paths["app/views"].push site.pages_path.expand_path
+    initializer "sitepress.set_registered_site_paths", after: :load_config_initializers do |app|
+      # `config.autoload_paths` and `config.eager_load_paths` are frozen
+      # by the time `:load_config_initializers` finishes, but
+      # `Rails.autoloaders.main.push_dir` accepts new directories any
+      # time before eager loading. Registered sites' helpers/models
+      # become lazy-autoloadable through that path. They're not added
+      # to `eager_load_paths`, so in production they're loaded on first
+      # access rather than at boot — fine for the multi-site case
+      # where the secondary site's helpers are scoped to one controller.
+      register_helpers_late = ->(path) {
+        if path.exist?
+          Rails.autoloaders.main.push_dir(path)
+          Rails.autoloaders.main.collapse(path)
+        end
+      }
 
-      # Components: autoloadable for view_components
-      app.config.autoload_paths << File.expand_path("./components")
-    end
+      register_assets_late = ->(path) {
+        # Propshaft reads config.assets.paths lazily, so adding here
+        # works for both dev and production precompile.
+        app.config.assets.paths << path.to_s if app.config.respond_to?(:assets)
+      }
+
+      Sitepress.configuration.sites.each do |site|
+        register_helpers_late.call site.helpers_path.expand_path
+        register_helpers_late.call site.models_path.expand_path
+        register_assets_late.call  site.assets_path.expand_path
+      end
 
-    # Configure sprockets paths for the site.
-    initializer "sitepress.set_manifest_file_path", before: :append_assets_path do |app|
-      manifest_file = Sitepress.configuration.manifest_file_path.expand_path
-      app.config.assets.precompile << manifest_file.to_s if manifest_file.exist?
+      # Mark that boot-time path registration has finished. Sites#<<
+      # checks this and warns if a site is registered after this point,
+      # since its helpers/models/assets won't be picked up by Zeitwerk.
+      Sitepress.configuration.instance_variable_set(:@boot_paths_registered, true)
     end
 
     # Configure Sitepress with Rails settings.

data/lib/sitepress/rails.rb

@@ -2,11 +2,13 @@ require "sitepress-core"
 
 module Sitepress
   autoload :Compiler,                 "sitepress/compiler"
+  autoload :Compilers,                "sitepress/compilers"
   autoload :Model,                    "sitepress/model"
   module Models
     autoload :Collection,             "sitepress/models/collection"
   end
   autoload :RailsConfiguration,       "sitepress/rails_configuration"
+  autoload :Sites,                    "sitepress/sites"
   module Renderers
     autoload :Controller,             "sitepress/renderers/controller"
     autoload :Server,                 "sitepress/renderers/server"
@@ -30,11 +32,24 @@ module Sitepress
   # Raised when any of the Render subclasses can't render a page.
   RenderingError = Class.new(RuntimeError)
 
-  # Make site available via Sitepress.site from Rails app.
+  # The configured default site (single-site case). For multi-site
+  # apps, additional sites live in `Sitepress.sites`.
   def self.site
     configuration.site
   end
 
+  # Registry of additional `Sitepress::Site` instances for multi-site
+  # apps. See `Sitepress::Sites` for the full API; the common usage is:
+  #
+  #   # config/initializers/sitepress.rb
+  #   Sitepress.sites << Sitepress::Site.new(root_path: "app/sitepress/admin_docs")
+  #
+  #   # somewhere later (e.g. a controller class body)
+  #   Sitepress.sites.fetch("app/sitepress/admin_docs")
+  def self.sites
+    configuration.sites
+  end
+
   # Default configuration object for Sitepress Rails integration.
   def self.configuration
     @configuration ||= RailsConfiguration.new

data/lib/sitepress/rails_configuration.rb

@@ -14,6 +14,14 @@ module Sitepress
       self.cache_resources = true
     end
 
+    # Registry of additional `Sitepress::Site` instances for multi-site
+    # apps. Lives on the configuration object so its lifecycle is tied
+    # to the Rails app and tests can reset it via
+    # `Sitepress.reset_configuration`.
+    def sites
+      @sites ||= Sites.new
+    end
+
     def parent_engine
       @parent_engine ||= Rails.application
     end
@@ -22,11 +30,6 @@ module Sitepress
       @site ||= pending_site || Site.new(root_path: default_root)
     end
 
-    # Location of Sprockets manifest file
-    def manifest_file_path
-      site.assets_path.join("config/manifest.js")
-    end
-
     private
 
     def pending_site

data/lib/sitepress/route_constraint.rb

@@ -1,14 +1,58 @@
 module Sitepress
-  # Route constraint for rails routes.rb file.
+  # Route constraint for the Rails routes file. Two ways to construct it:
+  #
+  #   - Pass `site:` directly — used by the default `sitepress_pages` route
+  #     for the single-site case.
+  #
+  #   - Pass `controller:` (a string like `"admin/docs"`) — the controller
+  #     class is resolved lazily and its class-level `.site` method is called
+  #     per request. This is what lets a controller bind itself to a site
+  #     via `class_attribute :site` and have routing pick it up:
+  #
+  #       class Admin::DocsController < Sitepress::SiteController
+  #         self.site = Sitepress.sites.fetch("app/sitepress/admin_docs")
+  #       end
+  #
+  # `path_prefix` is the URL prefix the route is mounted under (e.g.
+  # `/admin/docs`), stripped from `request.path` before the resource lookup.
+  # `sitepress_pages` fills this in from `@scope[:path]` automatically.
   class RouteConstraint
-    attr_reader :site
+    attr_reader :path_prefix
 
-    def initialize(site: Sitepress.site)
-      @site = site
+    def initialize(site: nil, controller: nil, path_prefix: nil)
+      @explicit_site = site
+      @controller_name = controller
+      @path_prefix = path_prefix.presence
     end
 
     def matches?(request)
-      !!site.resources.get(request.path)
+      !!site.resources.get(resource_path(request))
+    end
+
+    # Resolves the site this constraint guards. If a site was passed in
+    # explicitly we use it; otherwise we resolve the controller class and
+    # ask it. Resolution is lazy because controllers may not be loaded
+    # when routes are drawn.
+    def site
+      @explicit_site || controller_class.site
+    end
+
+    private
+
+    def controller_class
+      @controller_class ||= begin
+        raise ArgumentError, "Sitepress::RouteConstraint needs site: or controller:" if @controller_name.nil?
+        "#{@controller_name}_controller".camelize.constantize
+      end
+    end
+
+    def resource_path(request)
+      path = request.path
+      if path_prefix && path.start_with?(path_prefix)
+        path = path.delete_prefix(path_prefix)
+        path = "/" if path.empty?
+      end
+      path
     end
   end
 end

data/lib/sitepress/routing_mapper.rb

@@ -7,8 +7,32 @@ module ActionDispatch::Routing
     DEFAULT_ACTION = "show".freeze
     ROUTE_GLOB_KEY = "/*resource_path".freeze
 
-    # Hook up all the Sitepress pages
-    def sitepress_pages(controller: DEFAULT_CONTROLLER, action: DEFAULT_ACTION, root: false, constraints: Sitepress::RouteConstraint.new, as: :page)
+    # Hook up all the Sitepress pages.
+    #
+    # The mount path is read from the surrounding Rails `scope`/`namespace`,
+    # so it never has to be repeated. The site is read from the controller
+    # class's `.site` method, so a multi-site app declares the site once on
+    # the controller and the routes file just mounts it.
+    #
+    # @example Default site at the root
+    #   sitepress_pages
+    #
+    # @example A controller-owned site mounted under /admin/docs
+    #   # app/controllers/admin/docs_controller.rb
+    #   class Admin::DocsController < Sitepress::SiteController
+    #     def self.site = Sitepress.site(:admin_docs)
+    #   end
+    #
+    #   # config/routes.rb
+    #   namespace :admin do
+    #     scope :docs do
+    #       sitepress_pages controller: "admin/docs"
+    #     end
+    #   end
+    def sitepress_pages(controller: DEFAULT_CONTROLLER, action: DEFAULT_ACTION, root: false, constraints: nil, as: :page)
+      path_prefix = @scope[:path].presence
+      constraints ||= Sitepress::RouteConstraint.new(controller: controller, path_prefix: path_prefix)
+
       get ROUTE_GLOB_KEY,
         controller: controller,
         action: action,

data/lib/sitepress/sites.rb

@@ -0,0 +1,88 @@
+module Sitepress
+  # Registry of `Sitepress::Site` instances for multi-site Rails apps.
+  #
+  # The whole multi-site API lives on this collection — `<<` to register,
+  # `fetch` to look up by `root_path`, `each` (and the rest of `Enumerable`)
+  # to iterate. There's intentionally no `[]`, no `add`, no `find`-by-block,
+  # and no `delete` — three methods plus Enumerable is the entire surface,
+  # so callers don't have to choose between soft-miss and hard-miss lookup
+  # forms or between `<<` and a non-chaining `add`.
+  #
+  #   # config/initializers/sitepress.rb
+  #   Sitepress.sites << Sitepress::Site.new(root_path: "app/sitepress/admin_docs")
+  #
+  #   # somewhere later
+  #   Sitepress.sites.fetch("app/sitepress/admin_docs")    # => Sitepress::Site
+  #   Sitepress.sites.fetch("nope")                        # => raises NotFoundError
+  #   Sitepress.sites.each { |site| ... }
+  #
+  # The collection holds Sites directly — there's no derived key stored
+  # alongside, so the "key drift" failure mode (registry key disagreeing
+  # with the value's actual root_path) is impossible by construction.
+  # Lookup is a linear scan over `Site#root_path`, which is fine because
+  # registration is rare (boot time) and lookups happen at controller class
+  # load (also boot, in production).
+  class Sites
+    include Enumerable
+
+    def initialize
+      @sites = []
+    end
+
+    # Register a Site. Returns self per Ruby's `<<` convention so
+    # `Sitepress.sites << a << b` chains correctly.
+    #
+    # Two safety checks:
+    #
+    # - Type-checks `site` so the common mistake of pushing a path
+    #   string instead of a constructed Site fails loudly at the
+    #   call site rather than later when the engine tries to read
+    #   `.helpers_path` on a String.
+    #
+    # - If the engine's path-setup pass has already finished (i.e.
+    #   `<<` is being called from `config.after_initialize`, a
+    #   request, or anywhere else that runs after initializers), the
+    #   site is registered but its helpers/models/assets won't be on
+    #   Zeitwerk's autoload paths. We log a warning so the user can
+    #   diagnose the silent half-broken state instead of debugging
+    #   "why isn't my AdminDocsHelper resolving" three days later.
+    def <<(site)
+      unless site.is_a?(Sitepress::Site)
+        raise ArgumentError,
+          "Sitepress.sites << expects a Sitepress::Site, got #{site.class}: #{site.inspect}. " \
+          "Wrap it: Sitepress.sites << Sitepress::Site.new(root_path: #{site.inspect})"
+      end
+
+      if Sitepress.respond_to?(:configuration) &&
+         Sitepress.configuration.instance_variable_get(:@boot_paths_registered) &&
+         defined?(Rails) && Rails.logger
+        Rails.logger.warn(
+          "Sitepress.sites << #{site.root_path.inspect} called after the engine's " \
+          "path-setup pass. The site is registered, but its helpers, models, and " \
+          "assets won't be on Zeitwerk's autoload paths. Move this call into " \
+          "config/initializers/ if you want Rails to discover them."
+        )
+      end
+
+      @sites << site
+      self
+    end
+
+    # Find a registered Site by its `root_path`. Raises `NotFoundError`
+    # listing the registered paths if nothing matches — there's no nil
+    # return form, so a typo in the path string fails loud at the call
+    # site instead of propagating into a `NoMethodError on nil` later.
+    def fetch(root_path)
+      key = root_path.to_s
+      @sites.find { |site| site.root_path.to_s == key } || raise(
+        NotFoundError,
+        "No Sitepress site registered at #{root_path.inspect}. " \
+          "Registered: #{@sites.map { |s| s.root_path.to_s }.inspect}"
+      )
+    end
+
+    def each(&block)
+      @sites.each(&block)
+    end
+  end
+end

data/lib/tasks/sitepress_tasks.rake

@@ -1,4 +1,113 @@
-# desc "Explaining what the task does"
-# task :sitepress-rails do
-#   # Task goes here
-# end
+# OUTPUT_PATH overrides the default tmp/sitepress build root for both
+# `sitepress:compile` and `sitepress:sites:compile`. CI and deploy
+# flows that want a different location (`build/`, `dist/`,
+# `public/static/`) set OUTPUT_PATH on the invocation:
+#
+#   OUTPUT_PATH=build rake sitepress:sites:compile
+SITEPRESS_COMPILE_OUTPUT_ROOT = -> {
+  ENV.fetch("OUTPUT_PATH") { Rails.root.join("tmp/sitepress").to_s }
+}
+
+# FAIL_ON_ERROR=true makes the compile rake tasks raise on the first
+# resource that fails to render, aborting rake with a non-zero exit.
+# Default (false) collects all failures and prints a summary at the
+# end so a single bad page doesn't block the rest of the build —
+# preferred for local iteration. Use FAIL_ON_ERROR=true in CI to make
+# deploys notice broken pages.
+SITEPRESS_FAIL_ON_ERROR = -> { ENV["FAIL_ON_ERROR"] == "true" }
+
+# Build a Compiler::Files for `site`, writing into a subdirectory of
+# `output_root` named after the site's basename. Used by both
+# `sitepress:compile` and `sitepress:sites:compile` so they agree on
+# the on-disk layout (each site in its own directory under the build
+# root, no two sites colliding).
+SITEPRESS_BUILD_COMPILER = ->(site, output_root, fail_on_error: false) {
+  Sitepress::Compiler::Files.new(
+    site: site,
+    root_path: Pathname(output_root).join(site.root_path.expand_path.basename.to_s),
+    fail_on_error: fail_on_error
+  )
+}
+
+# Print a "Compilation Summary" block to stdout after a compile run.
+# Aggregates succeeded/failed counts across every compiler in the
+# collection and lists each failed resource with its owning site so
+# the user can see exactly what broke.
+SITEPRESS_PRINT_COMPILE_SUMMARY = ->(compilers) {
+  succeeded = compilers.flat_map(&:succeeded).size
+  failed    = compilers.flat_map(&:failed)
+
+  puts ""
+  puts "Compilation Summary"
+  puts "  Sites:      #{compilers.size}"
+  puts "  Succeeded:  #{succeeded}"
+  puts "  Failed:     #{failed.size}"
+
+  if failed.any?
+    puts ""
+    puts "Failed Resources"
+    compilers.each do |compiler|
+      compiler.failed.each do |resource|
+        puts "  #{compiler.site.root_path}: #{resource.request_path}"
+      end
+    end
+  end
+}
+
+namespace :sitepress do
+  desc "Compile the configured default Sitepress site to OUTPUT_PATH (default: tmp/sitepress/<basename>)"
+  task compile: :environment do
+    require "sitepress/compiler"
+    output_root = SITEPRESS_COMPILE_OUTPUT_ROOT.call
+    fail_on_error = SITEPRESS_FAIL_ON_ERROR.call
+
+    compilers = Sitepress::Compilers.new
+    compilers << SITEPRESS_BUILD_COMPILER.call(Sitepress.site, output_root, fail_on_error: fail_on_error)
+    compilers.compile
+
+    SITEPRESS_PRINT_COMPILE_SUMMARY.call(compilers)
+  end
+
+  desc "List the configured default site and all sites in Sitepress.sites"
+  task sites: :environment do
+    puts "Default:"
+    puts "  #{Sitepress.site.root_path}"
+
+    if Sitepress.sites.any?
+      puts ""
+      puts "Registered (#{Sitepress.sites.count}):"
+      Sitepress.sites.each do |site|
+        puts "  - #{site.root_path}"
+      end
+    else
+      puts ""
+      puts "No additional sites registered. Use Sitepress.sites << Sitepress::Site.new(root_path: ...) in an initializer."
+    end
+  end
+
+  namespace :sites do
+    desc "Compile every registered Sitepress site (default + Sitepress.sites) to OUTPUT_PATH (default: tmp/sitepress/<basename>)"
+    task :compile, [:root_path] => :environment do |_task, args|
+      require "sitepress/compiler"
+      output_root = SITEPRESS_COMPILE_OUTPUT_ROOT.call
+      fail_on_error = SITEPRESS_FAIL_ON_ERROR.call
+
+      # When invoked as `rake sitepress:sites:compile` we compile
+      # everything; when invoked as `rake "sitepress:sites:compile[path]"`
+      # we compile just the matching site (raising NotFoundError with
+      # the registered paths listed if no match).
+      sites = if args[:root_path]
+        [Sitepress.sites.fetch(args[:root_path])]
+      else
+        [Sitepress.site, *Sitepress.sites]
+      end
+
+      compilers = Sitepress::Compilers.new.concat(
+        sites.map { |site| SITEPRESS_BUILD_COMPILER.call(site, output_root, fail_on_error: fail_on_error) }
+      )
+      compilers.compile
+
+      SITEPRESS_PRINT_COMPILE_SUMMARY.call(compilers)
+    end
+  end
+end