jekyll-carve 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2fa9dda47fb228d8edba3147048e720d9ee7995a14c38b9f4cac9cf8bfe8f6e
-  data.tar.gz: 83252c17f31ccdf1f34b64785dbf928fc96619e2a35e243facef5543a71439b8
+  metadata.gz: 1fd1b876054b8355dc08cdf7569c46cafd968c9e8874c65cd4e6e2866f29d6e7
+  data.tar.gz: c4866d9b82ff1d2bf963eb8945fa4a67b70b94aaa4d3e78b300229d369cefc4d
 SHA512:
-  metadata.gz: d9230de7ea7aed19ff33d752aee2c53c8529cf622e742134e41b22d188f61460ea2813b1f34ea82c3544101281004d4e0c42c18b44c5af4f4174bfd52cc178cb
-  data.tar.gz: 4f50c860251b43b10ea16807c6f8624226c6399a3044c1d1a063020fceb70ab994aa03b9161370ec0d6d472757a0ca544360fa25f0bb6dd757c4d1de58b8435c
+  metadata.gz: b0c225c70722c0ed014f0ade97aae1b534992dd6830b02acf47a27b1914fe92208f478aefb72ec071794be0fd9e33f75be25a365fe55ef5f3b7be0b8e23b1f0a
+  data.tar.gz: 6c86ca36aec167aa996d1b01df87113e9e0ef8796f97a0cde5c4a1e4f6badc6b0edbad271886c7cd192a7e1167f7c23042952e74641907cae0e1a87f7e65f2e2

data/README.md

@@ -130,6 +130,52 @@ reaches the output.
 > front matter, from a comment system, or from anything else a visitor can
 > influence.
 
+### `carve.includes` - pulling one file into another
+
+A Carve page can pull another file in with `{{ path }}`. It stays literal until
+the site asks:
+
+```yaml
+carve:
+  includes: true
+```
+
+Includes need carve-lang 0.1.4 or later. On an older engine, a page that
+reaches them stops the build with a message naming the upgrade.
+
+Paths resolve relative to the file that wrote them, and nothing resolves outside
+the containment root. The root is Jekyll's source directory unless
+`carve.include_root` names another one, and an include that would leave it is
+not expanded.
+
+```yaml
+carve:
+  includes: true
+  include_root: /srv/shared/fragments
+```
+
+`carve.include_root` must be an **absolute** path. A relative one is refused
+rather than resolved, because resolving it lands on whatever directory the build
+ran from, which is not a root anyone chose. The page being rendered has to sit
+inside the root too.
+
+A target that cannot be read is reported against the page that asked for it, and
+the directive is left as written. The message does not say whether the file was
+missing or refused by containment: both report `include-unresolved`, so a page
+cannot be used to probe the filesystem. The class is at `--verbose`.
+
+Under `jekyll serve`, a page is rebuilt when a target it read changes, because
+every resolved target is registered with Jekyll's regeneration path.
+
+A conversion with no page behind it - the converter called directly on a String -
+leaves the directive literal, since there is no file for a relative path to
+resolve against.
+
+> [!NOTE]
+> Fragments under the source directory are pages in their own right, so Jekyll
+> will publish them. Exclude them in `_config.yml`, or keep them outside the
+> source and point `include_root` at the tree above both.
+
 ## Usage
 
 Create a page with a `.crv` extension. It MUST begin with Jekyll
@@ -193,32 +239,4 @@ has already removed the leading block by the time Carve runs.
 
 ## Development
 
-```sh
-bundle install
-bundle exec rspec   # run the converter unit tests
-```
-
-### Which engine you are testing against
-
-`bundle install` here does **not** resolve `carve-lang` from RubyGems. `Gemfile`
-pins the engine to a carve-rb revision, so a development run measures one exact
-engine build rather than whatever the registry serves that day, and
-`script/verify_engine_pin.rb` refuses when the Gemfile, the resolved bundle and
-the loaded library disagree. CI runs it before the suite:
-
-```sh
-bundle exec ruby script/verify_engine_pin.rb
-# carve-lang 0.1.2 from carve-rb b7f3a91a... (Gemfile pins b7f3a91a4192)
-```
-
-An installed copy of this gem resolves differently, through the range
-`jekyll-carve.gemspec` declares - today `>= 0.1.1, < 0.2.0`. The two are
-deliberately not the same engine, and both are checked:
-`spec/engine_floor_spec.rb` asks whether the engine under `bundle exec rspec`
-still does what the floor claims, and `script/consumer_engine_probe.rb` asks the
-same of an actual `gem install`, daily in `Engine drift` and again before every
-release.
-
-There is no committed `Gemfile.lock`, and that is deliberate - the reasoning,
-including why a lockfile would be a weaker pin here and what it would cost the
-Ruby 3.1 job, is written at the top of `Gemfile`.
+Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).

data/lib/jekyll/carve/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Carve
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/jekyll-carve.rb

@@ -59,9 +59,52 @@ module Jekyll
       #
       # Returns the rendered HTML String.
       def convert(content)
-        ::Carve.to_html(content.to_s,
-                        extensions: carve_extensions,
-                        symbols: carve_symbols)
+        document = Rendering.current
+        root = include_root
+        if root.nil? || document.nil? || document.path.to_s.empty?
+          return ::Carve.to_html(content.to_s,
+                                 extensions: carve_extensions,
+                                 symbols: carve_symbols)
+        end
+        # carve-lang added this entry point in 0.1.4; the floor stays lower for sites without includes.
+        unless ::Carve.respond_to?(:to_html_with_includes)
+          raise ArgumentError,
+                "carve.includes: the installed carve-lang (#{::Carve::VERSION}) has no " \
+                "to_html_with_includes; upgrade it to 0.1.4 or later, or set carve.includes: false"
+        end
+
+        begin
+          result = ::Carve.to_html_with_includes(content.to_s,
+                                                 root: root,
+                                                 source_path: document.path,
+                                                 extensions: carve_extensions,
+                                                 symbols: carve_symbols)
+        rescue ArgumentError => e
+          # A relative root, or a page outside it. Both are decided by the
+          # engine; what this adds is the key and the page to look at.
+          raise ArgumentError,
+                "carve.include_root: #{document.relative_path || document.path}: #{e.message}"
+        end
+        report_includes(result, document, root)
+        result[:value]
+      end
+
+      # The containment root configured under `carve.include_root`, or nil when
+      # `carve.includes` is off.
+      #
+      # A configured value is handed to the engine exactly as written. The
+      # engine refuses a relative root, and that refusal is what keeps
+      # containment off whatever directory the build ran from; expanding it
+      # here would mean it never fires. The default is Jekyll's own source
+      # directory, which this package derives rather than reads, so that one is
+      # expanded.
+      def include_root
+        return nil unless carve_config["includes"]
+
+        configured = carve_config["include_root"]
+        return configured.to_s if configured.is_a?(String) && !configured.empty?
+
+        File.expand_path(site_source)
       end
 
       # Carve extensions configured under `carve.extensions` in _config.yml.
@@ -129,6 +172,48 @@ module Jekyll
 
       private
 
+      # Surface what expansion degraded, and record what it read.
+      def report_includes(result, document, root)
+        page = document.relative_path || document.path
+        Array(result[:warnings]).each do |warning|
+          origin = warning[:file]
+          where = origin && origin != page ? "#{page} (#{origin})" : page
+          Jekyll.logger.warn "Carve:", "#{where}: #{warning[:rule]}: #{warning[:message]}"
+        end
+        suppressed = result[:suppressedWarnings].to_i
+        if suppressed.positive?
+          Jekyll.logger.warn "Carve:",
+                             "#{page}: #{suppressed} further include warnings suppressed"
+        end
+        Array(result[:dependencies]).each do |dependency|
+          # A containment refusal and a missing file are the same warning, so a
+          # page cannot probe the filesystem (spec I7). The class that was
+          # collapsed is here, for the build's own log.
+          if dependency[:denial]
+            Jekyll.logger.debug "Carve:",
+                                "#{page}: include #{dependency[:path]}: #{dependency[:denial]}"
+            next
+          end
+
+          register_dependency(document, File.join(root, dependency[:path].to_s))
+        end
+      end
+
+      # Tell Jekyll the page has to be rebuilt when this target changes.
+      #
+      # Only a RESOLVED target is registered. An unresolved dependency reports
+      # the directive as written rather than a path relative to the root, so
+      # joining it onto the root names the wrong file: a nested `missing.crv`
+      # would be recorded against the root rather than against the directory
+      # its parent sits in. A fragment appearing later is covered by Jekyll's
+      # own watch over the source directory.
+      def register_dependency(document, target)
+        regenerator = document.site&.regenerator
+        return unless regenerator.respond_to?(:add_dependency)
+
+        regenerator.add_dependency(document.path, target)
+      end
+
       # The `carve` table from _config.yml, or an empty Hash.
       def carve_config
         config = @config.is_a?(Hash) ? @config["carve"] : nil
@@ -247,9 +332,42 @@ module Jekyll
         end
       end
     end
+
+    # Which document Jekyll is rendering right now.
+    #
+    # `Jekyll::Converter#convert` is handed a String and nothing else, so a
+    # converter cannot see the file the body came from - and an include has to
+    # resolve against that file. The `:pre_render` hook carries it, and Jekyll
+    # renders documents one at a time, so the current one is a thread-local
+    # rather than a queue.
+    module Rendering
+      KEY = :jekyll_carve_document
+
+      module_function
+
+      def current
+        Thread.current[KEY]
+      end
+
+      def with(document)
+        Thread.current[KEY] = document
+      end
+
+      def clear
+        Thread.current[KEY] = nil
+      end
+    end
   end
 end
 
+Jekyll::Hooks.register %i[pages documents], :pre_render do |document|
+  Jekyll::Carve::Rendering.with(document)
+end
+
+Jekyll::Hooks.register %i[pages documents], :post_render do |_document|
+  Jekyll::Carve::Rendering.clear
+end
+
 # Resolve the symbol map once per build rather than once per process.
 #
 # `Site#reset` runs at the top of every `Site#process`, including every rebuild

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-carve
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang