kiln 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ba761c39b8d2ffe60d03a4cdf48fdbb6ab1a7d4717b9716ab7107423dd2b2f1
-  data.tar.gz: 29f9eb12df579857663e8a44b1713928c7b7bbd4106da3cd6b52e645b2791a0f
+  metadata.gz: 2108cdc748f14c10c06ab2edbf346622c13887cac5ec16bc2fe6823dfb3d4b53
+  data.tar.gz: f5aabfc64b54bd944d8d2bb3de6a57d980204e4f4070dd23f3340376980b8326
 SHA512:
-  metadata.gz: 6597f99b761b60cdc3dcae600c18ebd8beab61e8ab82cd4fec4c57d797ba7f03213669ba5aa458338f68e508d7bf67a6dd582fb0d97e45ec7ac3b7c1b3725aac
-  data.tar.gz: c2036e9a40ba3458de6ecedb40da6a84b2e4a36775ef003e711d2a198fa1f566a5574660913df4fc5f168b553c03d04b46f32bd73df801c4b5d4895f0d2e8875
+  metadata.gz: 6ec17dee2f07143628dbd3892c50ee258bde2aa1a2e0c4e5306b7ecd9d30856e2d0df0d50b78da273f658b7d0607e3ec4a4bd00fc5f8834c4aa7002e7938d814
+  data.tar.gz: 9eafdc861711a6f733e9bc376a6c4f0c3519c104451fbaed5140c37642ea0d21edd6649793309ec64fb02e26b8b60ec8892398b5e0bc20f7e2c21a725940a943

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.1.2 (2026-11-07)
+
+Breaking:
+
+- `Kiln.build_cache.fetch` caches only while `Kiln.building?`. Outside a build it runs the block
+  every time. `read`, `write` and `delete` are removed.
+- `assert_repeatable_build` is removed. Use `kiln_build(repeatable: true) { |output| ... }`.
+- In collections, `SLUG.LOCALE.md` (such as `2026-08.es.md`) is a translation of `SLUG.md` instead
+  of its own entry. Translations stay out of `all`, `find` and `each`, and a translation without
+  its entry fails when the collection loads.
+- A collection filename that is only a date, such as `2026-08-01.md`, now sets `published_at`.
+- Removed options: `config.verify` (every build verifies), `config.absolute_urls`,
+  `config.external_links`, `config.processors`, `config.before_build`, `config.after_build`,
+  `config.strip_source_maps` (source maps are always stripped), `config.sitemap` (written whenever
+  `url` is set), `config.host=` (the host comes from `url`, else `localhost`), `config.assets`
+  (only referenced assets are exported), `config.redirects` (always `_redirects`; the
+  `:meta_refresh`, `:both` and `false` modes are gone) and `config.copy_public` (`public/` is always
+  copied).
+- Removed `Kiln::Processors.apply`, `Kiln::Processors::Context`, `Kiln::Build::Context`, and the
+  `AbsoluteUrls` and `ExternalLinks` processors.
+- The content layer drops preview tokens: `Collection#find` takes only a slug, and
+  `Entry#preview_token` and `Kiln::Content.preview_secret` are removed. Drafts and scheduled
+  entries still show in development when Kiln is not building.
+
+Added:
+
+- `params :page, locale: [ nil, "es", "ja" ]` builds every combination of value lists. `nil`
+  leaves the key out, for optional segments. A list may be a lambda, called at build time.
+- `kiln_build(repeatable: true)` builds twice, fails with the diff when the outputs differ, and
+  yields the first output.
+- `entry.translation(:es)` and `entry.locale` in the content layer.
+- Collection filenames may start with a `YYYY-MM` date, which means the 1st of that month.
+- `Kiln::Content::Markdown.render_inline(text)` renders a single paragraph without its `<p>`.
+- `config.cname = true` writes `CNAME` with the host from `config.url`.
+
+Fixed:
+
+- A production build precompiles assets into a temporary directory instead of `public/assets`, so
+  a development server that boots during the build no longer loads the production manifest.
+  Compiled assets are exported from that directory, and the build no longer needs
+  `config.public_file_server.enabled`.
+- When `app/assets/builds` is created after boot (a fresh checkout without
+  `app/assets/builds/.keep`), the build stops with one error that says to track the `.keep` file,
+  instead of one missing-asset error per page.
+
 ## 0.1.1 (2026-11-07)
 
 - Kiln has two tasks, `kiln:build` and `kiln:serve`. `kiln:verify`, `kiln:routes` and `kiln:check` are removed: every build verifies and reports uncovered routes, and committed output can be checked with `git status --porcelain` after a build.

data/README.md

@@ -53,12 +53,15 @@ A GET route with no required params is built automatically. A route with params
 ```ruby
 Kiln.pages do
   params :post, -> { Post.published.map { { slug: it.slug } } }
-  params :page, -> { %w[en es ja].map { { locale: it } } + [ {} ] }  # scope "(:locale)"
+  params :page, locale: [ nil, "es", "ja" ]                         # scope "(:locale)"
+  params :archive, year: -> { Post.years }, locale: [ nil, "es" ]   # every combination
   paginate :blog_page, per: 10, total: -> { Post.count }, start: 2  # /blog/page/2, /blog/page/3, ...
   skip :search, reason: "dynamic"
 end
 ```
 
+A hash of value lists builds every combination of the values. A `nil` value leaves the key out, which fills an optional segment such as `(:locale)` with nothing. A list may be a lambda, called at build time.
+
 A route that needs params and has neither a param source nor a skip fails the build, and the error names the line to add. Rails internals, the health check, mounted engines and turbo-rails' native navigation routes are skipped by default. Redirect routes become redirects, and mounted Rack apps are built like any other route.
 
 Feeds, `robots.txt`, `llms.txt` and JSON files are ordinary routes with views. The content type picks the extension, so `get "api"` rendering JSON is written as `api.json`.
@@ -81,39 +84,23 @@ bin/rails kiln:serve                       # look at the output as a static host
 | Option | Default | |
 |---|---|---|
 | `output` | `"dist"` | Relative to `Rails.root`, or absolute. Wiped at the start of every build. |
-| `url` | `nil` | Public base URL, for the sitemap and absolute URLs. |
-| `host` | from `url`, else `"localhost"` | Host header sent with every request. |
+| `url` | `nil` | Public base URL. Its host is sent with every request (`localhost` without it), and `sitemap.xml` is written only when it is set. |
 | `paths` | `:directory` | `/now` becomes `now/index.html`. `:file` writes `now.html`. |
-| `assets` | `:referenced` | Assets the output references (HTML, importmap, CSS `url()`). `:all` exports everything. |
-| `cname` | `nil` | Writes a `CNAME` file. |
+| `cname` | `nil` | Writes a `CNAME` file with this host. `true` takes the host from `url`. |
 | `not_found` | `nil` | Path rendered to `404.html`. It may respond with 200 or 404. |
-| `redirects` | `:file` | `:file` (`_redirects`), `:meta_refresh` (HTML pages for GitHub Pages), `:both`, or `false`. |
-| `sitemap` | `true` | Writes `sitemap.xml` when `url` is set. Pages marked `noindex` stay out. |
 | `files` | `{}` | Files that aren't routes: `{ "octicons-license.txt" => "vendor/octicons/LICENSE" }`. |
-| `strip_source_maps` | `true` | Removes `sourceMappingURL` comments from JS and CSS. |
-| `absolute_urls` | `false` | Makes image URLs absolute (img, srcset, og: and twitter: images). |
-| `external_links` | `false` | Adds `target="_blank" rel="noopener"` to links to other hosts. |
-| `processors` | `[]` | Your HTML processors: `call(html, context)` returning a String. |
-| `verify` | `true` | Runs the verifier after every build. |
 | `verify_skip` | `[]` | CSS selectors for sample markup whose links aren't checked, such as `"[data-example-preview]"`. |
-| `copy_public` | `true` | Copies `public/` (minus `public/assets`) into the output. |
 
-Hooks receive a context with `output`, `env`, `manifest` and `report`:
-
-```ruby
-Kiln.configure do |config|
-  config.before_build { |context| SearchIndex.generate! }
-  config.after_build { |context| puts "#{context.manifest.entries.size} pages" }
-end
-```
+Every build exports the assets the output references (HTML, importmap, CSS `url()`), removes `sourceMappingURL` comments from JS and CSS, copies `public/` (minus `public/assets`), writes `_redirects` when a route redirects, and runs the verifier. The sitemap leaves out pages marked `noindex`.
 
 CSRF tokens and meta tags are always stripped. The rest of the HTML stays byte for byte as the app rendered it.
 
 ## Write views for a build
 
 - `Kiln.building?` is true while a build renders pages. Use it to hide development-only markup.
-- `Kiln.build_cache.fetch(key) { ... }` memoizes for one build and is cleared before and after it.
-- Builds fetch assets through the app, so keep `config.public_file_server.enabled = true` for the build environment.
+- `Kiln.build_cache.fetch(key) { ... }` memoizes for one build and is cleared before and after it. Outside a build it runs the block every time, so a development server never serves stale data.
+- A production build precompiles assets into a temporary directory and exports them from there. `public/assets` is left alone, so a development server of the same app can run at the same time.
+- Propshaft only serves asset folders that exist when the app boots. Track `app/assets/builds/.keep`, as a new Rails app does, or the build stops with an error on a fresh checkout.
 - A build in development skips the precompile but still runs the steps hooked into `assets:precompile`, such as `tailwindcss:build`.
 - Development middleware that injects markup (Hotwire Spark, web-console, rack-mini-profiler) fails the build. Load it only under `bin/rails server`.
 - Root-absolute asset paths keep every page's `<head>` identical, so Turbo visits never force a full reload.
@@ -133,6 +120,8 @@ require "kiln/content"
 
 `app/views/pages/about.html.md` renders through the layout like any view, and `.md.erb` runs ERB first. commonmarker renders GitHub Flavored Markdown with tables, strikethrough, autolinks and heading ids; raw HTML passes through. Code blocks get Rouge CSS classes.
 
+`Kiln::Content::Markdown.render(text)` returns HTML. `Kiln::Content::Markdown.render_inline(text)` drops the `<p>` around text that is a single paragraph, for titles and captions; other text renders as with `render`.
+
 With `Kiln::Content.source_positions` on, each rendered block of a `.md` view or collection entry carries `data-tensaku-md="path:startLine:startCol-endLine:endCol"` for the Tensaku editor. The format is a draft. `.md.erb` views get none, because ERB shifts the line numbers. The setting defaults to on in development when Tensaku is loaded, and is always off while Kiln is building.
 
 Collections read Markdown files with YAML frontmatter, such as `content/blog/2024-05-01-hello.md`:
@@ -144,7 +133,18 @@ posts.find("hello") # raises Kiln::Content::NotFound, which Rails maps to a 404
 post.title, post.published_at, post.html, post[:tags]
 ```
 
-Entries with `draft: true` or a future `published_at` are hidden, except in development when Kiln is not building. A server-rendered app can share a hidden entry with `posts.find(slug, preview_token: params[:token])`.
+A filename date may be `YYYY-MM-DD` or `YYYY-MM`. A month-only date sets `published_at` to the 1st of that month, and a filename that is only a date, such as `2026-08.md`, keeps the date as its slug.
+
+`SLUG.LOCALE.md` is a translation of the entry with that slug, such as `2026-08.es.md` for `2026-08.md`. A locale is two lowercase letters, optionally followed by a dash and two uppercase letters (`es`, `pt-BR`). Translations stay out of `all`, `find` and `each`:
+
+```ruby
+post.locale            # nil for SLUG.md, "es" for SLUG.es.md
+post.translation(:es)  # the visible SLUG.es.md entry, or nil
+```
+
+A translation whose entry does not exist fails when the collection loads.
+
+Entries with `draft: true` or a future `published_at` are hidden, except in development when Kiln is not building.
 
 ## Test the build
 
@@ -154,16 +154,20 @@ require "kiln/test_helper"
 class StaticSiteTest < ActiveSupport::TestCase
   include Kiln::TestHelper
 
-  test("builds the same output twice") { assert_repeatable_build }
+  test "the site builds repeatably" do
+    kiln_build(repeatable: true) { |output| assert output.join("index.html").file? }
+  end
+
   test("home page") { assert_page "/", selector: "h1", text: "Welcome" }
 end
 ```
 
-`kiln_build { |output| ... }` builds into a temp dir, fails with the report on any error, and yields the output path.
+`kiln_build { |output| ... }` builds into a temp dir, fails with the report on any error, and yields the output path. With `repeatable: true` it builds twice, fails with the list of differing files when the outputs differ, and yields the first output.
 
 ## Known limits
 
 - Pages render one at a time.
+- Redirects are written only as `_redirects`, which Cloudflare Pages and Netlify read. GitHub Pages ignores the file, so redirect routes do not redirect there.
 - Wildcard rules in your own `public/_redirects` are written out, but the verifier and `kiln:serve` only follow exact rules.
 - JS modules are found through the importmap. Relative `import "./x.js"` between files is not followed.
 - Collections read `*.md` files. `.md.erb` works for views only.

data/lib/kiln/assets.rb

@@ -4,25 +4,37 @@ require "nokogiri"
 require "set"
 
 module Kiln
-  # Finds the /assets/* files the output uses and fetches them through the app, so the same code works
-  # with dynamic Propshaft (development, test) and with precompiled assets served from public/assets.
+  # Finds the /assets/* files the output uses and exports them. Compiled assets are read from the
+  # compile directory; dynamic Propshaft (development, test) serves them through the app.
   class Assets
     CSS_REFERENCE = /url\(\s*["']?([^"')]+?)["']?\s*\)|@import\s+["']([^"']+)["']/
     EXTERNAL = %r{\A(?:[a-z][a-z0-9+.-]*:|//|#)}i
 
     class << self
-      # Compiles assets in-process when the app does not serve them dynamically. Returns a callable that
-      # removes what the precompile created, or nil when nothing was compiled. When assets are served
+      # Compiles assets in-process when the app does not serve them dynamically. The compile goes to a
+      # temporary directory, never public/assets, so a development server of the same app that boots
+      # meanwhile never sees a production manifest. Returns a callable that restores the asset config
+      # and removes the directory, or nil when nothing was compiled. When assets are served
       # dynamically, still runs the build steps hooked into assets:precompile (tailwindcss:build,
       # javascript:build, css:build), so a development build never ships stale bundles.
       def precompile(app)
         return build_bundles(app) unless precompile?(app)
 
-        output_path = Pathname(app.config.assets.output_path)
-        created = !output_path.exist?
-        run_precompile(app)
-
-        -> { created ? FileUtils.rm_rf(output_path) : FileUtils.rm_f(app.config.assets.manifest_path) }
+        assets = app.config.assets
+        original = assets.slice(:output_path, :manifest_path)
+        dir = Pathname(Dir.mktmpdir("kiln-assets"))
+        cleanup = -> do
+          assets.merge!(original)
+          FileUtils.rm_rf(dir)
+        end
+        assets.merge!(output_path: dir, manifest_path: dir.join(".manifest.json"))
+        begin
+          run_precompile(app)
+        rescue Kiln::Error
+          cleanup.call
+          raise
+        end
+        cleanup
       end
 
       def precompile?(app)
@@ -32,6 +44,17 @@ module Kiln
         !assets.server && !Pathname(assets.manifest_path).exist?
       end
 
+      # Propshaft only adds load paths that exist at boot. On a fresh checkout, a bundler such as
+      # tailwindcss:build creates app/assets/builds during the build, too late to be served.
+      def check_builds!(app)
+        builds = app.root.join("app/assets/builds")
+        paths = app.config.respond_to?(:assets) && app.config.assets.respond_to?(:paths) && app.config.assets.paths
+        return unless paths && builds.directory? && paths.none? { Pathname(it) == builds }
+
+        raise Kiln::Error, "app/assets/builds did not exist when the app booted, so its assets are not served. " \
+          "Track app/assets/builds/.keep in version control, as a new Rails app does, and build again."
+      end
+
       # Copies public/ into the output, minus public/assets. Files already in the output win, with a
       # warning unless they are listed in `generated` (files Kiln writes on purpose, like 404.html).
       def copy_public(from:, to:, report:, generated: [])
@@ -93,7 +116,6 @@ module Kiln
 
     def export
       queue = referenced_paths
-      queue.concat(all_paths) if @config.assets == :all
       seen = Set.new
 
       while (path = queue.shift)
@@ -105,15 +127,18 @@ module Kiln
     private
       # Writes one asset and returns the asset paths it references (CSS url() and @import).
       def fetch(path)
-        response = @renderer.get(path)
-        unless response.success?
-          @report.error(:asset, "responded with #{response.status}", path:)
-          return []
+        body = compiled(path)
+        unless body
+          response = @renderer.get(path)
+          unless response.success?
+            @report.error(:asset, "responded with #{response.status}", path:)
+            return []
+          end
+          body = response.body
         end
 
         extension = File.extname(path)
-        body = response.body
-        body = Processors::StripSourceMaps.call(body) if @config.strip_source_maps && %w[.js .css].include?(extension)
+        body = Processors::StripSourceMaps.call(body) if %w[.js .css].include?(extension)
         write(path, body)
         extension == ".css" ? css_references(path, body) : []
       rescue StandardError => error
@@ -121,6 +146,16 @@ module Kiln
         []
       end
 
+      # The file from the compile directory when assets are precompiled, or nil.
+      def compiled(path)
+        assets = @app.config.assets
+        return if assets.server
+
+        dir = Pathname(assets.manifest_path).dirname.expand_path
+        file = dir.join(path.delete_prefix("#{prefix}/")).expand_path
+        file.binread if file.to_s.start_with?("#{dir}/") && file.file?
+      end
+
       def write(path, body)
         relative = path.delete_prefix("/")
         file = @output.join(relative)
@@ -159,10 +194,6 @@ module Kiln
         end
       end
 
-      def all_paths
-        @app.assets.load_path.assets.map { "#{prefix}/#{it.digested_path}" }
-      end
-
       # Normalizes a URL to an asset path ("/assets/app-abc.css"), or nil when it isn't one of ours.
       def asset_path(url)
         uri = URI.parse(url.to_s.strip)

data/lib/kiln/build.rb

@@ -4,9 +4,6 @@ module Kiln
   # Runs the whole pipeline and returns a Report. Never raises for page-level problems: those go in
   # the report so the build can show every failure at once.
   class Build
-    # Passed to before_build / after_build hooks.
-    Context = Data.define(:output, :env, :manifest, :report)
-
     # Development middleware that injects markup into every HTML response.
     DEV_MIDDLEWARE = %w[Hotwire::Spark::Middleware WebConsole::Middleware Rack::MiniProfiler Rack::LiveReload].freeze
     # Source-position attributes from in-page editors (Herb source attribution, Tensaku).
@@ -35,10 +32,9 @@ module Kiln
         guard_output!
         guard_dev_middleware!
         ensure_secret_key_base
-        guard_static_files!
         cleanup = Assets.precompile(app)
         begin
-          run_hooks(config.before_build_hooks)
+          Assets.check_builds!(app)
           prepare_output
 
           pages = Router.new(app.routes, pages_dsl, report:).pages
@@ -46,16 +42,15 @@ module Kiln
           render_not_found if config.not_found
           report_editor_markup
 
-          Assets.new(renderer:, output:, config:, report:).export
+          Assets.new(renderer:, output:, config:, report:, app:).export
           write_files
-          Assets.copy_public(from: app.root.join("public"), to: output, report:, generated: generated_files) if config.copy_public
-          write_redirects if config.redirects && @redirects.any?
-          Sitemap.new(manifest, url: config.url).write(output) if config.sitemap && config.url
+          Assets.copy_public(from: app.root.join("public"), to: output, report:, generated: generated_files)
+          write_redirects if @redirects.any?
+          Sitemap.new(manifest, url: config.url).write(output) if config.url
           write_cname if config.cname
           write_manifest
 
-          Verifier.new(output, config:).verify(report) if config.verify
-          run_hooks(config.after_build_hooks)
+          Verifier.new(output, config:).verify(report)
         ensure
           cleanup&.call
         end
@@ -78,7 +73,7 @@ module Kiln
         if response.redirect?
           @redirects << Redirects::Entry.new(from: page.path, to: response.location, status: response.status)
         elsif response.success?
-          body = response.html? ? Processors.apply(response.body, Processors::Context.new(path: page.path, config:, response:)) : response.body
+          body = response.html? ? Processors::StripCSRF.call(response.body) : response.body
           @editor_markup << page.path if response.html? && body.match?(EDITOR_MARKUP)
           file = writer.write(page.path, response.content_type, body)
           manifest.add(page.path, file:, body:, content_type: response.content_type, noindex: Sitemap.noindex?(response, body))
@@ -104,14 +99,14 @@ module Kiln
           return report.error(:render, "404 page responded with #{response.status}", path: config.not_found)
         end
 
-        body = Processors.apply(response.body, Processors::Context.new(path: config.not_found, config:, response:))
+        body = Processors::StripCSRF.call(response.body)
         report.wrote(writer.write_file("404.html", body))
       rescue StandardError => error
         report.error(:render, describe(error), path: config.not_found)
       end
 
       def write_redirects
-        Redirects.new(@redirects, mode: config.redirects, writer:, host: config.host, url: config.url).write(output).each { report.wrote(it) }
+        report.wrote(Redirects.new(@redirects, host: config.host).write(output))
       end
 
       # The manifest is build state, not part of the site: it lives in tmp/, and only for the configured
@@ -143,17 +138,12 @@ module Kiln
         [ ("404.html" if config.not_found), ("CNAME" if config.cname), *config.files.keys.map(&:to_s) ].compact
       end
 
+      # config.cname = true takes the host from config.url.
       def write_cname
-        report.wrote(writer.write_file("CNAME", "#{config.cname}\n"))
-      end
+        host = config.cname == true ? config.url && URI(config.url).host : config.cname
+        return report.error(:write, "config.cname = true needs config.url", path: "/CNAME") unless host
 
-      def run_hooks(hooks)
-        context = Context.new(output:, env: Rails.env, manifest:, report:)
-        hooks.each do |hook|
-          hook.call(context)
-        rescue StandardError => error
-          report.error(:hook, describe(error))
-        end
+        report.wrote(writer.write_file("CNAME", "#{host}\n"))
       end
 
       def prepare_output
@@ -188,15 +178,6 @@ module Kiln
         app.config.secret_key_base = SecureRandom.hex(64)
       end
 
-      # After a precompile, assets are fetched from public/assets through ActionDispatch::Static.
-      def guard_static_files!
-        return unless app.config.respond_to?(:assets) && !app.config.assets.server
-        return if app.config.public_file_server.enabled
-
-        raise Kiln::Error, "Kiln fetches compiled assets through the public file server. " \
-          "Set config.public_file_server.enabled = true for the build environment."
-      end
-
       def describe(error)
         where = error.backtrace&.find { it.start_with?(app.root.to_s) }&.delete_prefix("#{app.root}/")
         [ "#{error.class}: #{error.message}", where && "(#{where})" ].compact.join(" ")

data/lib/kiln/build_cache.rb

@@ -1,6 +1,7 @@
 module Kiln
   # A plain in-memory store that returns the cached objects themselves (no copies), so memoized
-  # repositories and collections keep their state for the whole build.
+  # repositories and collections keep their state for the whole build. Outside a build, fetch runs
+  # the block every time, so a development server never serves stale data.
   class BuildCache
     def initialize
       @store = {}
@@ -8,6 +9,8 @@ module Kiln
     end
 
     def fetch(key)
+      return yield unless Kiln.building?
+
       @mutex.synchronize do
         return @store[key] if @store.key?(key)
 
@@ -15,9 +18,6 @@ module Kiln
       end
     end
 
-    def read(key) = @mutex.synchronize { @store[key] }
-    def write(key, value) = @mutex.synchronize { @store[key] = value }
-    def delete(key) = @mutex.synchronize { @store.delete(key) }
     def clear = @mutex.synchronize { @store.clear }
   end
 end

data/lib/kiln/configuration.rb

@@ -2,71 +2,37 @@ module Kiln
   class Configuration
     # Output directory, relative to Rails.root unless absolute.
     attr_accessor :output
-    # Public base URL ("https://davafons.com"). Used by the sitemap and absolute_urls processor.
+    # Public base URL ("https://davafons.com"). Sets the request host and enables sitemap.xml.
     attr_accessor :url
     # :directory ("/now" -> now/index.html) or :file ("/now" -> now.html).
     attr_accessor :paths
-    # :referenced (only assets the output uses) or :all (everything under /assets).
-    attr_accessor :assets
-    # Writes a CNAME file with this domain when set.
+    # Writes a CNAME file with this domain when set. true takes the host from `url`.
     attr_accessor :cname
-    # Removes `sourceMappingURL` comments from JS and CSS.
-    attr_accessor :strip_source_maps
-    # Extra HTML processors: objects responding to call(html, context) -> html.
-    attr_accessor :processors
-    # Built-in optional processors, off by default.
-    attr_accessor :absolute_urls, :external_links
     # Path rendered to 404.html (expected to respond with 404 or 200), nil to skip.
     attr_accessor :not_found
-    # :file (_redirects), :meta_refresh (HTML pages), :both, or false.
-    attr_accessor :redirects
-    # Writes sitemap.xml when true and `url` is set.
-    attr_accessor :sitemap
-    # Runs the verifier (links, anchors, importmap) after every build.
-    attr_accessor :verify
     # CSS selectors for sample markup whose links the verifier ignores (for example component demos).
     attr_accessor :verify_skip
-    # Copy public/ into the output (minus public/assets).
-    attr_accessor :copy_public
     # Extra files that aren't routes: { "octicons-license.txt" => "vendor/octicons/LICENSE" }.
     # Sources are relative to Rails.root.
     attr_accessor :files
 
-    attr_reader :before_build_hooks, :after_build_hooks
-    attr_writer :host
-
     def initialize
       @output = "dist"
       @url = nil
-      @host = nil
       @paths = :directory
-      @assets = :referenced
       @cname = nil
-      @strip_source_maps = true
-      @processors = []
-      @absolute_urls = false
-      @external_links = false
       @not_found = nil
-      @redirects = :file
-      @sitemap = true
-      @verify = true
       @verify_skip = []
-      @copy_public = true
       @files = {}
-      @before_build_hooks = []
-      @after_build_hooks = []
     end
 
-    # Host sent with every request. Derived from `url`, falls back to "localhost".
+    # Host sent with every request: the host of `url`, or "localhost".
     def host
-      @host || (url && URI(url).host) || "localhost"
+      (url && URI(url).host) || "localhost"
     end
 
     def output_path(root = Rails.root)
       Pathname(output).absolute? ? Pathname(output) : Pathname(root).join(output)
     end
-
-    def before_build(&block) = @before_build_hooks << block
-    def after_build(&block) = @after_build_hooks << block
   end
 end

data/lib/kiln/content/collection.rb

@@ -8,8 +8,9 @@ module Kiln
       def initialize(name, dir)
         @name, @dir = name.to_s, Pathname(dir)
         @stamp = stamp
-        @entries = files.map { Entry.new(@name, it) }
-          .sort_by { [ it.published_at&.in_time_zone || Time.at(0), it.slug ] }.reverse
+        translations, entries = files.map { Entry.new(@name, it) }.partition(&:locale)
+        @entries = entries.sort_by { [ it.published_at&.in_time_zone || Time.at(0), it.slug ] }.reverse
+        translations.each { attach(it) }
       end
 
       # Visible entries, newest first.
@@ -19,11 +20,7 @@ module Kiln
 
       def each(&) = all.each(&)
 
-      def find(slug, preview_token: nil)
-        entry = @entries.find { it.slug == slug.to_s }
-        return entry if entry && (Content.show_drafts || entry.published? || preview?(entry, preview_token))
-        raise NotFound, "no #{name} entry with slug #{slug.inspect}"
-      end
+      def find(slug) = find_by(slug:) || raise(NotFound, "no #{name} entry with slug #{slug.inspect}")
 
       def find_by(slug:) = all.find { it.slug == slug.to_s }
 
@@ -33,11 +30,14 @@ module Kiln
       private
         def files = Dir[@dir.join("*.md")].sort
 
-        def stamp = files.map { [ it, File.mtime(it) ] }
+        def attach(translation)
+          entry = @entries.find { it.slug == translation.slug }
+          raise ArgumentError, "#{translation.path} is a translation, but no entry has the slug #{translation.slug.inspect}" unless entry
 
-        def preview?(entry, token)
-          token.present? && ActiveSupport::SecurityUtils.secure_compare(entry.preview_token, token.to_s)
+          entry.add_translation(translation)
         end
+
+        def stamp = files.map { [ it, File.mtime(it) ] }
     end
   end
 end

data/lib/kiln/content/entry.rb

@@ -1,20 +1,36 @@
 module Kiln
   module Content
     class Entry
-      FILENAME = /\A(?:(?<date>\d{4}-\d{2}-\d{2})-)?(?<slug>.+?)\.md\z/
+      # SLUG.md, or SLUG.LOCALE.md for a translation. A locale is two lowercase letters, optionally
+      # followed by a dash and two uppercase letters: es, ja, pt-BR.
+      FILENAME = /\A(?<name>.+?)(?:\.(?<locale>[a-z]{2}(?:-[A-Z]{2})?))?\.md\z/
+      # A leading YYYY-MM-DD or YYYY-MM date. The slug is the rest of the name, or the whole name when
+      # it is only a date. A month-only date means the 1st of that month.
+      DATED = /\A(?<date>\d{4}-\d{2}(?:-\d{2})?)(?:-(?<slug>.+))?\z/
 
-      attr_reader :collection, :path, :slug, :attributes, :body, :published_at
+      attr_reader :collection, :path, :slug, :locale, :attributes, :body, :published_at
 
       def initialize(collection, path)
         @collection, @path = collection.to_s, Pathname(path)
         match = FILENAME.match(@path.basename.to_s)
-        @slug = match[:slug]
+        @locale = match[:locale]
+        dated = DATED.match(match[:name])
+        @slug = (dated && dated[:slug]) || match[:name]
         text = @path.read
         @attributes, @body = Frontmatter.parse(text)
         @frontmatter_lines = text.delete_suffix(body).count("\n")
-        @published_at = attributes["published_at"] || (Date.iso8601(match[:date]) if match[:date])
+        @published_at = attributes["published_at"] || (filename_date(dated[:date]) if dated)
+        @translations = {}
       end
 
+      # The visible translation from SLUG.LOCALE.md, or nil.
+      def translation(locale)
+        entry = @translations[locale.to_s]
+        entry if entry && (Content.show_drafts || entry.published?)
+      end
+
+      def add_translation(entry) = @translations[entry.locale] = entry
+
       def title = attributes["title"] || slug.titleize
       def draft? = attributes["draft"] == true
       def scheduled? = published_at.present? && published_at.in_time_zone.future?
@@ -29,15 +45,18 @@ module Kiln
       def [](key) = attributes[key.to_s]
       def to_h = attributes
 
-      def preview_token
-        OpenSSL::HMAC.hexdigest("SHA256", Content.preview_secret, "#{collection}/#{slug}")
-      end
-
       def respond_to_missing?(name, include_private = false) = attributes.key?(name.to_s) || super
 
       def method_missing(name, *args)
         attributes.key?(name.to_s) && args.empty? ? attributes[name.to_s] : super
       end
+
+      private
+        def filename_date(date)
+          Date.iso8601(date.length == 7 ? "#{date}-01" : date)
+        rescue Date::Error
+          raise ArgumentError, "#{path} starts with an invalid date: #{date}"
+        end
     end
   end
 end

data/lib/kiln/content/markdown.rb

@@ -20,6 +20,16 @@ module Kiln
         path ? SourcePosition.rewrite(html, path, line_offset) : html
       end
 
+      # Renders text that is a single paragraph without the wrapping <p>, for titles and captions.
+      # Text with any other block structure renders as with render.
+      def self.render_inline(text)
+        html = render(text)
+        block = Commonmarker.parse(text.to_s, options: OPTIONS).first_child
+        return html unless block&.type == :paragraph && block.next_sibling.nil?
+
+        html.delete_prefix("<p>").delete_suffix("</p>\n")
+      end
+
       # Swaps a code block for raw HTML highlighted by Rouge, with CSS classes and no inline styles.
       def self.highlight(node, sourcepos:)
         code = node.string_content

data/lib/kiln/content.rb

@@ -30,10 +30,14 @@
 #   # config/kiln.rb
 #   params :post, -> { Kiln::Content.collection("blog").map { { slug: it.slug } } }
 #
+# Filenames. A leading YYYY-MM-DD or YYYY-MM date sets published_at (a month means its 1st day); a
+# name that is only a date keeps it as the slug. SLUG.LOCALE.md is a translation of the SLUG entry,
+# where LOCALE is two lowercase letters with an optional -XX region (es, pt-BR). Translations stay out
+# of all/find/each: post.translation(:es) returns one or nil, and post.locale is nil or "es".
+#
 # Publishing. Entries with `draft: true` or a future `published_at` (frontmatter or filename date)
 # are hidden. They show in development unless Kiln is building; set Kiln::Content.show_drafts to
-# override. A server-rendered app can share a hidden entry with
-# `posts.find(params[:slug], preview_token: params[:token])`, where the token is `post.preview_token`.
+# override.
 #
 # Source positions. With Kiln::Content.source_positions on, each rendered block of a .md view or
 # collection entry carries data-tensaku-md="path:startLine:startCol-endLine:endCol" for the Tensaku
@@ -41,7 +45,7 @@
 # always off while Kiln is building.
 #
 # Settings: Kiln::Content.root (default Rails.root/content), Kiln::Content.show_drafts,
-# Kiln::Content.preview_secret (default secret_key_base), Kiln::Content.source_positions.
+# Kiln::Content.source_positions.
 begin
   require "commonmarker"
   require "rouge"
@@ -63,7 +67,7 @@ module Kiln
     class NotFound < Kiln::Error; end
 
     class << self
-      attr_writer :root, :show_drafts, :preview_secret, :source_positions
+      attr_writer :root, :show_drafts, :source_positions
 
       def root
         Pathname(@root || Rails.root.join("content"))
@@ -80,10 +84,6 @@ module Kiln
         Rails.env.development? && !defined?(::Tensaku).nil?
       end
 
-      def preview_secret
-        @preview_secret || Rails.application.secret_key_base
-      end
-
       def collection(name)
         dir = root.join(name.to_s)
         if Kiln.building?
@@ -95,7 +95,7 @@ module Kiln
       end
 
       def reset!
-        @root = @show_drafts = @preview_secret = @source_positions = nil
+        @root = @show_drafts = @source_positions = nil
         @collections = {}
       end
 

data/lib/kiln/pages.rb

@@ -9,7 +9,15 @@ module Kiln
     end
 
     # params :post, -> { Post.all.map { { slug: it.slug } } }
-    def params(route_name, source)
+    # params :health, locale: [ nil, "es", "ja" ]
+    #
+    # Value lists build every combination of their values. A nil value leaves the key out, for
+    # optional segments such as "(:locale)". A list may be a lambda, called at build time.
+    def params(route_name, source = nil, **values)
+      if values.any?
+        raise ArgumentError, "params :#{route_name} takes a source or value lists, not both" if source
+        source = -> { combinations(values) }
+      end
       raise ArgumentError, "params :#{route_name} needs a callable source" unless source.respond_to?(:call)
       @sources[route_name.to_sym] = source
     end
@@ -31,5 +39,11 @@ module Kiln
     end
 
     def declared_names = (sources.keys + skips.keys).uniq
+
+    private
+      def combinations(values)
+        lists = values.map { |key, list| (list.respond_to?(:call) ? list.call : list).to_a.map { { key => it } } }
+        lists.first.product(*lists.drop(1)).map { it.reduce(:merge).compact }
+      end
   end
 end

data/lib/kiln/processors/strip_csrf.rb

@@ -7,7 +7,7 @@ module Kiln
       # The newline csrf_meta_tags puts between its two tags goes with the first one.
       META_TAG = /<meta\b(?=[^>]*\sname="csrf-(?:param|token)")[^>]*>(?:\n(?=<meta\b[^>]*\sname="csrf-))?/
 
-      def self.call(html, _context = nil)
+      def self.call(html)
         html.gsub(TOKEN_INPUT, "").gsub(META_TAG, "")
       end
     end

data/lib/kiln/redirects.rb

@@ -1,8 +1,5 @@
-require "erb"
-
 module Kiln
-  # Writes redirect responses as a _redirects file (Cloudflare Pages, Netlify) and/or meta refresh pages
-  # (GitHub Pages).
+  # Writes redirect responses as a _redirects file (Cloudflare Pages, Netlify).
   class Redirects
     Entry = Data.define(:from, :to, :status)
 
@@ -20,52 +17,19 @@ module Kiln
       end
     end
 
-    def initialize(entries, mode:, writer:, host:, url: nil)
+    def initialize(entries, host:)
       @entries = entries.map { it.with(to: relativize(it.to, host)) }
-      @mode = mode
-      @writer = writer
-      @url = url
     end
 
+    # Rules from a copied public/_redirects come first, so hand-written rules win. Returns the filename.
     def write(output)
-      files = []
-      files << write_file(output) if %i[file both].include?(@mode)
-      files.concat(write_pages) if %i[meta_refresh both].include?(@mode)
-      files
+      file = Pathname(output).join(FILENAME)
+      existing = file.exist? ? file.read.chomp.then { it.empty? ? "" : "#{it}\n" } : ""
+      File.write(file, existing + @entries.map { "#{it.from} #{it.to} #{it.status}\n" }.join)
+      FILENAME
     end
 
     private
-      # Rules from a copied public/_redirects come first, so hand-written rules win.
-      def write_file(output)
-        file = Pathname(output).join(FILENAME)
-        existing = file.exist? ? file.read.chomp.then { it.empty? ? "" : "#{it}\n" } : ""
-        File.write(file, existing + @entries.map { "#{it.from} #{it.to} #{it.status}\n" }.join)
-        FILENAME
-      end
-
-      def write_pages
-        @entries.map do |entry|
-          @writer.write_file(@writer.file_for(entry.from, "text/html"), page(entry.to))
-        end
-      end
-
-      def page(to)
-        canonical = ERB::Util.html_escape(@url && to.start_with?("/") ? "#{@url.chomp("/")}#{to}" : to)
-        to = ERB::Util.html_escape(to)
-        <<~HTML
-          <!DOCTYPE html>
-          <html>
-          <head>
-          <meta charset="utf-8">
-          <title>Redirecting</title>
-          <meta http-equiv="refresh" content="0; url=#{to}">
-          <link rel="canonical" href="#{canonical}">
-          </head>
-          <body><a href="#{to}">#{to}</a></body>
-          </html>
-        HTML
-      end
-
       def relativize(location, host)
         uri = URI.parse(location)
         return location unless uri.is_a?(URI::HTTP) && uri.host&.casecmp?(host)

data/lib/kiln/report.rb

@@ -3,7 +3,7 @@ module Kiln
   class Report
     Entry = Data.define(:kind, :message, :path)
 
-    KINDS = %i[uncovered_route render editor_markup asset broken_link missing_anchor importmap redirect write hook other].freeze
+    KINDS = %i[uncovered_route render editor_markup asset broken_link missing_anchor importmap redirect write other].freeze
 
     attr_reader :errors, :warnings, :written
 

data/lib/kiln/test_helper.rb

@@ -10,43 +10,39 @@ module Kiln
   #   class StaticSiteTest < ActiveSupport::TestCase
   #     include Kiln::TestHelper
   #
-  #     test("builds the same output twice") { assert_repeatable_build }
+  #     test("builds repeatably") { kiln_build(repeatable: true) { assert it.join("index.html").file? } }
   #     test("home page") { assert_page "/", selector: "h1", text: "Home" }
   #   end
   module TestHelper
     # Builds into a temp dir, fails with the report on any error, and yields the output path.
     # Returns the Build when no block is given (the temp dir is then left for the caller).
-    def kiln_build(app: Rails.application, config: Kiln.config)
-      dir = Dir.mktmpdir("kiln-build")
+    # With repeatable: true it builds a second time and fails with the diff when the two outputs
+    # differ, then yields the first output.
+    def kiln_build(app: Rails.application, config: Kiln.config, repeatable: false)
+      dir = Pathname(Dir.mktmpdir("kiln-build"))
       build = Build.new(app:, config:, output: dir)
       assert build.run.success?, build.report.to_s
-      return build unless block_given?
-
-      begin
-        yield Pathname(dir)
-      ensure
-        FileUtils.rm_rf(dir)
-      end
-    end
-
-    # Builds twice and asserts both outputs are byte-identical.
-    def assert_repeatable_build(app: Rails.application, config: Kiln.config)
-      kiln_build(app:, config:) do |first|
+      if repeatable
         kiln_build(app:, config:) do |second|
-          diff = TreeDiff.call(first, second)
+          diff = TreeDiff.call(dir, second)
           assert diff.empty?, "Kiln output differs between two builds:\n#{diff}"
         end
       end
+      return build unless block_given?
+
+      yield dir
+    ensure
+      FileUtils.rm_rf(dir) if dir && block_given?
     end
 
-    # Renders one path the way a build does (processors included) and asserts it succeeds.
+    # Renders one path the way a build does (CSRF tokens stripped) and asserts it succeeds.
     # Optional `selector` must match, and contain `text` when given. Returns the processed body.
     def assert_page(path, status: 200, selector: nil, text: nil, app: Rails.application, config: Kiln.config)
       response = Kiln.building! { Renderer.new(app, host: config.host).get(path) }
       assert_equal status, response.status, "Expected #{path} to respond with #{status}"
 
       body = response.body
-      body = Processors.apply(body, Processors::Context.new(path:, config:, response:)) if response.html?
+      body = Processors::StripCSRF.call(body) if response.html?
 
       if selector
         nodes = Nokogiri::HTML5(body).css(selector)

data/lib/kiln/version.rb

@@ -1,3 +1,3 @@
 module Kiln
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiln
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - David Afonso
@@ -91,9 +91,6 @@ files:
 - lib/kiln/manifest.rb
 - lib/kiln/page.rb
 - lib/kiln/pages.rb
-- lib/kiln/processors.rb
-- lib/kiln/processors/absolute_urls.rb
-- lib/kiln/processors/external_links.rb
 - lib/kiln/processors/strip_csrf.rb
 - lib/kiln/processors/strip_source_maps.rb
 - lib/kiln/railtie.rb

data/lib/kiln/processors/absolute_urls.rb

@@ -1,26 +0,0 @@
-module Kiln
-  module Processors
-    # Prefixes root-relative image URLs with config.url: img src/srcset and og:/twitter: image meta tags.
-    # Feed readers and social previews need absolute URLs.
-    module AbsoluteUrls
-      IMG_TAG = /<img\b[^>]*>/
-      IMAGE_META = /<meta\b(?=[^>]*\s(?:property|name)="(?:og|twitter):image[^"]*")[^>]*>/
-      ROOT_RELATIVE = %r{\A/(?!/)}
-
-      def self.call(html, context)
-        base = context.config.url.to_s.chomp("/")
-        raise Kiln::Error, "config.url is required when absolute_urls is on" if base.empty?
-
-        html
-          .gsub(IMG_TAG) { |tag| tag.gsub(/(?<=\s)(src|srcset)="([^"]*)"/) { %(#{$1}="#{$1 == "src" ? absolute($2, base) : srcset($2, base)}") } }
-          .gsub(IMAGE_META) { |tag| tag.sub(/(?<=\s)content="([^"]*)"/) { %(content="#{absolute($1, base)}") } }
-      end
-
-      def self.absolute(url, base) = url.match?(ROOT_RELATIVE) ? "#{base}#{url}" : url
-
-      def self.srcset(value, base)
-        value.gsub(/(\A|,)(\s*)([^\s,]+)/) { "#{$1}#{$2}#{absolute($3, base)}" }
-      end
-    end
-  end
-end

data/lib/kiln/processors/external_links.rb

@@ -1,26 +0,0 @@
-module Kiln
-  module Processors
-    # Adds target="_blank" rel="noopener" to http(s) links that point to another host.
-    module ExternalLinks
-      LINK_TAG = /<a\b[^>]*\shref="https?:[^"]*"[^>]*>/
-
-      def self.call(html, context)
-        host = context.config.host
-        html.gsub(LINK_TAG) { |tag| external?(tag, host) ? mark(tag) : tag }
-      end
-
-      def self.external?(tag, host)
-        link_host = URI(tag[/(?<=\s)href="([^"]*)"/, 1]).host
-        link_host.present? && !link_host.casecmp?(host)
-      rescue URI::InvalidURIError
-        false
-      end
-
-      def self.mark(tag)
-        tag = tag.sub(/(?<=\s)rel="([^"]*)"/) { $1.split.include?("noopener") ? $& : %(rel="#{$1} noopener") }
-        additions = [ (' target="_blank"' unless tag.match?(/\starget=/)), (' rel="noopener"' unless tag.match?(/\srel=/)) ]
-        tag.delete_suffix(">") + additions.join + ">"
-      end
-    end
-  end
-end

data/lib/kiln/processors.rb

@@ -1,22 +0,0 @@
-module Kiln
-  # HTML transforms applied to every rendered HTML response, in order: built-ins, then config.processors.
-  # Processors edit the HTML as a string and leave everything they don't match byte-for-byte intact.
-  module Processors
-    Context = Data.define(:path, :config, :response)
-
-    def self.apply(html, context)
-      config = context.config
-      html = StripCSRF.call(html, context)
-      html = AbsoluteUrls.call(html, context) if config.absolute_urls
-      html = ExternalLinks.call(html, context) if config.external_links
-
-      config.processors.reduce(html) do |current, processor|
-        result = processor.call(current, context)
-        unless result.is_a?(String)
-          raise Kiln::Error, "Processor #{processor.inspect} returned #{result.class} for #{context.path}, expected a String"
-        end
-        result
-      end
-    end
-  end
-end