kiln 0.1.0

data/lib/kiln/content/entry.rb

@@ -0,0 +1,36 @@
+module Kiln
+  module Content
+    class Entry
+      FILENAME = /\A(?:(?<date>\d{4}-\d{2}-\d{2})-)?(?<slug>.+?)\.md\z/
+
+      attr_reader :collection, :path, :slug, :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]
+        @attributes, @body = Frontmatter.parse(@path.read)
+        @published_at = attributes["published_at"] || (Date.iso8601(match[:date]) if match[:date])
+      end
+
+      def title = attributes["title"] || slug.titleize
+      def draft? = attributes["draft"] == true
+      def scheduled? = published_at.present? && published_at.in_time_zone.future?
+      def published? = !draft? && !scheduled?
+      def html = @html ||= Markdown.render(body).html_safe
+      def to_param = slug
+      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
+    end
+  end
+end

data/lib/kiln/content/frontmatter.rb

@@ -0,0 +1,18 @@
+module Kiln
+  module Content
+    module Frontmatter
+      PATTERN = /\A---[ \t]*\r?\n(.*?)^---[ \t]*(?:\r?\n|\z)/m
+
+      # Returns [attributes, body]. Attributes have string keys.
+      def self.parse(text)
+        match = PATTERN.match(text)
+        return [ {}, text ] unless match
+
+        attributes = YAML.safe_load(match[1], permitted_classes: [ Date, Time, Symbol ]) || {}
+        raise ArgumentError, "frontmatter must be a YAML mapping" unless attributes.is_a?(Hash)
+
+        [ attributes.transform_keys(&:to_s), match.post_match ]
+      end
+    end
+  end
+end

data/lib/kiln/content/handlers.rb

@@ -0,0 +1,16 @@
+module Kiln
+  module Content
+    # ActionView template handlers. A handler returns Ruby source that evaluates to the output.
+    module Handlers
+      # Plain Markdown never changes between renders, so convert it once at compile time.
+      Markdown = ->(_template, source) { "#{Content::Markdown.render(source).inspect}.html_safe" }
+
+      # ERB fills a fresh output buffer, then its result goes through Markdown on every render.
+      # "begin;" keeps the ERB source on its original line numbers.
+      MarkdownERB = ->(template, source) do
+        erb = ActionView::Template.registered_template_handler(:erb).call(template, source)
+        "Kiln::Content::Markdown.render(begin;#{erb}\nend.to_s).html_safe"
+      end
+    end
+  end
+end

data/lib/kiln/content/markdown.rb

@@ -0,0 +1,19 @@
+module Kiln
+  module Content
+    module Markdown
+      EXTENSIONS = { fenced_code_blocks: true, tables: true, autolink: true, strikethrough: true }.freeze
+
+      class Renderer < Redcarpet::Render::HTML
+        def block_code(code, language)
+          lexer = Rouge::Lexer.find_fancy(language.to_s, code) || Rouge::Lexers::PlainText.new
+          %(<pre class="highlight #{lexer.tag}"><code>#{Rouge::Formatters::HTML.new.format(lexer.lex(code))}</code></pre>\n)
+        end
+      end
+
+      # A new parser per call: Redcarpet parsers aren't safe to share between threads.
+      def self.render(text)
+        Redcarpet::Markdown.new(Renderer.new(with_toc_data: true), EXTENSIONS).render(text.to_s)
+      end
+    end
+  end
+end

data/lib/kiln/content.rb

@@ -0,0 +1,103 @@
+# Kiln content layer: Markdown views and Markdown collections with YAML frontmatter.
+# Optional and independent of the exporter, so server-rendered Rails apps can use it too.
+#
+#   # Gemfile
+#   gem "redcarpet"
+#   gem "rouge"
+#
+#   # config/initializers/kiln.rb
+#   require "kiln/content"
+#
+# Markdown views. app/views/pages/about.html.md renders through the layout like any view.
+# about.html.md.erb runs ERB first, then Markdown. Code blocks are highlighted by Rouge with CSS
+# classes, so add a Rouge theme to your stylesheet (`rougify style github`).
+#
+# Collections. content/blog/2024-05-01-hello.md:
+#
+#   ---
+#   title: Hello
+#   tags: [rails]
+#   ---
+#   # Hello
+#
+#   posts = Kiln::Content.collection("blog")
+#   posts.all                     # visible entries, newest first
+#   posts.find("hello")           # raises Kiln::Content::NotFound (a 404 in Rails)
+#   posts.find_by(slug: "hello")  # or nil
+#   post.slug, post.title, post.published_at, post.draft?, post.body, post.html, post[:tags], post.tags
+#
+#   # config/kiln.rb
+#   params :post, -> { Kiln::Content.collection("blog").map { { slug: it.slug } } }
+#
+# 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`.
+#
+# Settings: Kiln::Content.root (default Rails.root/content), Kiln::Content.show_drafts,
+# Kiln::Content.preview_secret (default secret_key_base).
+begin
+  require "redcarpet"
+  require "rouge"
+rescue LoadError => error
+  raise LoadError, "kiln/content needs the redcarpet and rouge gems. " \
+    "Add `gem \"redcarpet\"` and `gem \"rouge\"` to your Gemfile. (#{error.message})"
+end
+
+require "kiln"
+require "action_dispatch"
+require_relative "content/markdown"
+require_relative "content/frontmatter"
+require_relative "content/handlers"
+require_relative "content/entry"
+require_relative "content/collection"
+
+module Kiln
+  module Content
+    class NotFound < Kiln::Error; end
+
+    class << self
+      attr_writer :root, :show_drafts, :preview_secret
+
+      def root
+        Pathname(@root || Rails.root.join("content"))
+      end
+
+      def show_drafts
+        return @show_drafts unless @show_drafts.nil?
+        Rails.env.development? && !Kiln.building?
+      end
+
+      def preview_secret
+        @preview_secret || Rails.application.secret_key_base
+      end
+
+      def collection(name)
+        dir = root.join(name.to_s)
+        if Kiln.building?
+          Kiln.build_cache.fetch("kiln/content/#{dir}") { Collection.new(name, dir) }
+        else
+          cached = collections[dir]
+          cached.nil? || cached.stale? ? collections[dir] = Collection.new(name, dir) : cached
+        end
+      end
+
+      def reset!
+        @root = @show_drafts = @preview_secret = nil
+        @collections = {}
+      end
+
+      private
+        def collections
+          @collections ||= {}
+        end
+    end
+  end
+end
+
+ActionDispatch::ExceptionWrapper.rescue_responses["Kiln::Content::NotFound"] = :not_found
+
+ActiveSupport.on_load(:action_view) do
+  ActionView::Template.register_template_handler :md, Kiln::Content::Handlers::Markdown
+  ActionView::Template.register_template_handler :"md.erb", Kiln::Content::Handlers::MarkdownERB
+end

data/lib/kiln/manifest.rb

@@ -0,0 +1,43 @@
+require "digest"
+require "json"
+
+module Kiln
+  # Every page written by a build: path => file, content digest, content type and noindex flag.
+  class Manifest
+    FILENAME = "kiln-manifest.json"
+
+    def self.load(file)
+      new(JSON.parse(File.read(file)).transform_values(&:symbolize_keys))
+    end
+
+    def initialize(entries = {})
+      @entries = entries
+      @mutex = Mutex.new
+    end
+
+    def add(path, file:, body:, content_type:, noindex: false)
+      entry = { content_type:, digest: Digest::SHA256.hexdigest(body), file: file.to_s, noindex: }
+      @mutex.synchronize { @entries[path] = entry }
+    end
+
+    def entries
+      @entries.sort.to_h { |path, entry| [ path, entry.sort.to_h ] }
+    end
+
+    def write(output)
+      File.write(Pathname(output).join(FILENAME), "#{JSON.pretty_generate(entries)}\n")
+      FILENAME
+    end
+
+    # Changes from this manifest to `other` (old.diff(new)).
+    def diff(other)
+      mine = entries
+      theirs = other.entries
+      {
+        added: theirs.keys - mine.keys,
+        removed: mine.keys - theirs.keys,
+        changed: (mine.keys & theirs.keys).reject { mine[it][:digest] == theirs[it][:digest] }
+      }
+    end
+  end
+end

data/lib/kiln/page.rb

@@ -0,0 +1,8 @@
+module Kiln
+  # One concrete path to render. `route_name` is the Rails route name (nil for unnamed routes).
+  Page = Data.define(:path, :route_name, :params) do
+    def initialize(path:, route_name: nil, params: {})
+      super
+    end
+  end
+end

data/lib/kiln/pages.rb

@@ -0,0 +1,35 @@
+module Kiln
+  # Declarations from config/kiln.rb: param sources and skips, keyed by route name.
+  class Pages
+    attr_reader :sources, :skips
+
+    def initialize
+      @sources = {}
+      @skips = {}
+    end
+
+    # params :post, -> { Post.all.map { { slug: it.slug } } }
+    def params(route_name, source)
+      raise ArgumentError, "params :#{route_name} needs a callable source" unless source.respond_to?(:call)
+      @sources[route_name.to_sym] = source
+    end
+
+    def skip(route_name, reason: nil)
+      @skips[route_name.to_sym] = reason
+    end
+
+    # paginate :posts_page, per: 10, total: -> { Post.count }
+    # Builds pages start..last, where last is ceil(total / per). The start page is always built, so an
+    # empty list still gets its first page. Use start: 2 when page 1 lives at another route.
+    def paginate(route_name, per:, total:, param: :page, start: 1)
+      raise ArgumentError, "paginate :#{route_name} needs a positive per:" unless per.is_a?(Integer) && per.positive?
+
+      params route_name, -> do
+        last = Integer(total.call).fdiv(per).ceil
+        (start..[ start, last ].max).map { { param => it } }
+      end
+    end
+
+    def declared_names = (sources.keys + skips.keys).uniq
+  end
+end

data/lib/kiln/processors/absolute_urls.rb

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,26 @@
+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/strip_csrf.rb

@@ -0,0 +1,15 @@
+module Kiln
+  module Processors
+    # Removes authenticity_token inputs and the csrf-param / csrf-token meta tags, leaving the page as
+    # Rails renders it with forgery protection off. A static page has no session to check tokens against.
+    module StripCSRF
+      TOKEN_INPUT = /<input\b(?=[^>]*\bname="authenticity_token")[^>]*>/
+      # 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)
+        html.gsub(TOKEN_INPUT, "").gsub(META_TAG, "")
+      end
+    end
+  end
+end

data/lib/kiln/processors/strip_source_maps.rb

@@ -0,0 +1,14 @@
+module Kiln
+  module Processors
+    # Removes sourceMappingURL comments from JavaScript and CSS.
+    module StripSourceMaps
+      COMMENT = %r{//[#@] sourceMappingURL=[^\r\n]*|/\*[#@] sourceMappingURL=[^*]*\*/}
+      # A comment on its own line goes with its line break; one after code leaves the line intact.
+      PATTERN = /^[ \t]*(?:#{COMMENT})[ \t]*(?:\r?\n|\z)|(?:#{COMMENT})/
+
+      def self.call(text)
+        text.gsub(PATTERN, "")
+      end
+    end
+  end
+end

data/lib/kiln/processors.rb

@@ -0,0 +1,22 @@
+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

data/lib/kiln/railtie.rb

@@ -0,0 +1,22 @@
+require "rails/railtie"
+
+module Kiln
+  class Railtie < ::Rails::Railtie
+    # config/kiln.rb holds Kiln.configure and Kiln.pages. Param sources are lambdas, so loading it
+    # early (before the app's models exist) is fine.
+    initializer "kiln.load_config", before: :load_config_initializers do |app|
+      file = app.root.join("config/kiln.rb")
+      load file if file.exist?
+    end
+
+    # Requests carry the configured host. Allow it when the app restricts hosts.
+    initializer "kiln.hosts", after: "kiln.load_config" do |app|
+      hosts = app.config.hosts
+      hosts << Kiln.config.host if hosts.any? && !hosts.include?(Kiln.config.host)
+    end
+
+    rake_tasks do
+      Dir[File.expand_path("../tasks/kiln/*.rake", __dir__)].sort.each { load it }
+    end
+  end
+end

data/lib/kiln/redirects.rb

@@ -0,0 +1,78 @@
+require "erb"
+
+module Kiln
+  # Writes redirect responses as a _redirects file (Cloudflare Pages, Netlify) and/or meta refresh pages
+  # (GitHub Pages).
+  class Redirects
+    Entry = Data.define(:from, :to, :status)
+
+    FILENAME = "_redirects"
+
+    # Reads a _redirects file. Missing file means no rules.
+    def self.load(file)
+      return [] unless File.file?(file)
+
+      File.readlines(file, chomp: true).filter_map do |line|
+        from, to, status = line.strip.split(/\s+/)
+        next if from.nil? || from.start_with?("#") || to.nil?
+
+        Entry.new(from:, to:, status: Integer(status || 302, exception: false) || 302)
+      end
+    end
+
+    def initialize(entries, mode:, writer:, host:, url: nil)
+      @entries = entries.map { it.with(to: relativize(it.to, host)) }
+      @mode = mode
+      @writer = writer
+      @url = url
+    end
+
+    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
+    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)
+
+        "#{uri.path.presence || "/"}#{"?#{uri.query}" if uri.query}#{"##{uri.fragment}" if uri.fragment}"
+      rescue URI::InvalidURIError
+        location
+      end
+  end
+end

data/lib/kiln/renderer.rb

@@ -0,0 +1,39 @@
+module Kiln
+  # Renders one path through the app's full Rack stack, the same way a browser request would.
+  class Renderer
+    TEXT_TYPE = %r{\Atext/|json|xml|javascript}
+
+    def initialize(app, host:)
+      @app = app
+      @host = host
+    end
+
+    # Never follows redirects. App exceptions raise instead of rendering an error page.
+    def get(path)
+      response = raising_exceptions { Rack::MockRequest.new(@app).get(path, "HTTP_HOST" => @host, "HTTPS" => "on", "rack.url_scheme" => "https", "REMOTE_ADDR" => "127.0.0.1") }
+      headers = response.headers.to_h.transform_keys(&:downcase)
+      Response.new(path:, status: response.status, headers:, body: encode(response.body, headers["content-type"]))
+    end
+
+    private
+      # Rails merges its env_config over the request env, so "action_dispatch.show_exceptions" can't be
+      # set per request. Switch it on the app for the duration of the call instead.
+      def raising_exceptions
+        return yield unless @app.respond_to?(:env_config)
+
+        config = @app.env_config
+        previous = config["action_dispatch.show_exceptions"]
+        config["action_dispatch.show_exceptions"] = :none
+        begin
+          yield
+        ensure
+          config["action_dispatch.show_exceptions"] = previous
+        end
+      end
+
+      def encode(body, content_type)
+        body = +body
+        content_type.to_s.match?(TEXT_TYPE) ? body.force_encoding(Encoding::UTF_8) : body.force_encoding(Encoding::BINARY)
+      end
+  end
+end

data/lib/kiln/report.rb

@@ -0,0 +1,55 @@
+module Kiln
+  # Collects every problem found during a build so they can be printed together.
+  class Report
+    Entry = Data.define(:kind, :message, :path)
+
+    KINDS = %i[uncovered_route render asset broken_link missing_anchor importmap redirect write hook other].freeze
+
+    attr_reader :errors, :warnings, :written
+
+    def initialize
+      @errors = []
+      @warnings = []
+      @written = []
+      @mutex = Mutex.new
+    end
+
+    def error(kind, message, path: nil)
+      @mutex.synchronize { @errors << Entry.new(kind:, message:, path:) }
+    end
+
+    def warn(kind, message, path: nil)
+      @mutex.synchronize { @warnings << Entry.new(kind:, message:, path:) }
+    end
+
+    # Records a file written to the output (relative path).
+    def wrote(file)
+      @mutex.synchronize { @written << file.to_s }
+    end
+
+    def success? = errors.empty?
+    def failure? = !success?
+
+    def to_s(title: "Kiln build")
+      lines = []
+      warnings.each { lines << "warning #{format_entry(it)}" }
+      if errors.any?
+        lines << "" if warnings.any?
+        lines << "#{title} failed with #{errors.size} #{"error".pluralize(errors.size)}:"
+        errors.group_by(&:kind).each do |kind, entries|
+          lines << ""
+          lines << "  #{kind.to_s.humanize} (#{entries.size})"
+          entries.each { lines << "    #{format_entry(it)}" }
+        end
+      else
+        lines << "#{title} succeeded: #{written.size} #{"file".pluralize(written.size)} written."
+      end
+      lines.join("\n")
+    end
+
+    private
+      def format_entry(entry)
+        entry.path ? "#{entry.path}: #{entry.message}" : entry.message
+      end
+  end
+end

data/lib/kiln/response.rb

@@ -0,0 +1,13 @@
+module Kiln
+  # What the app returned for one path.
+  Response = Data.define(:path, :status, :headers, :body) do
+    def content_type
+      headers["content-type"].to_s.split(";").first.to_s.strip.downcase
+    end
+
+    def html? = content_type == "text/html"
+    def success? = status.between?(200, 299)
+    def redirect? = [ 301, 302, 303, 307, 308 ].include?(status)
+    def location = headers["location"]
+  end
+end