jekyll-carve 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d5439f1f1f23a853c560a40a84f7b210a2625682f4b5a66483cfb23361744f4
-  data.tar.gz: 87ae6478fa6a2af0e2026611f41fb4d2118677496222325d89e9f8cb03a7156e
+  metadata.gz: 1fd1b876054b8355dc08cdf7569c46cafd968c9e8874c65cd4e6e2866f29d6e7
+  data.tar.gz: c4866d9b82ff1d2bf963eb8945fa4a67b70b94aaa4d3e78b300229d369cefc4d
 SHA512:
-  metadata.gz: b5cd475edd480cd1465c4114b13ecd817c916342e0b073939cc773e3e09f85d8a294aa55b3ed6eb28b56889de1cce67e3a3c91a2716ff53f1a8d5d36935c40b0
-  data.tar.gz: 79a03d86ffe55a4c7fcd8c0f23d071ff6479745d241b4f216775d27eb4d122e91c2b1c76fca5228e877a9279dcd0152abf69339a83f6c62bee59a719e914851a
+  metadata.gz: b0c225c70722c0ed014f0ade97aae1b534992dd6830b02acf47a27b1914fe92208f478aefb72ec071794be0fd9e33f75be25a365fe55ef5f3b7be0b8e23b1f0a
+  data.tar.gz: 6c86ca36aec167aa996d1b01df87113e9e0ef8796f97a0cde5c4a1e4f6badc6b0edbad271886c7cd192a7e1167f7c23042952e74641907cae0e1a87f7e65f2e2

data/README.md

@@ -51,6 +51,131 @@ hyphenated/underscored forms, passed straight through to the engine). When the
 key is absent, no extensions are enabled. The recognized extensions are listed
 in `Carve::EXTENSIONS`; an unknown name raises `ArgumentError` at build time.
 
+### `carve.symbols` - what `:smile:` renders as
+
+Carve parses `:name:` in core, no extension needed, but what a name renders as
+is a render option. With no map configured a shortcode renders as its own
+source text:
+
+```text
+Ship it :smile:
+```
+
+```html
+<p>Ship it :smile:</p>
+```
+
+`carve.symbols` supplies the map. It takes a mapping written inline:
+
+```yaml
+carve:
+  symbols:
+    smile: "😄"
+    ship: "🚀"
+```
+
+or a path to a JSON object, so a large map does not have to live in
+`_config.yml`:
+
+```yaml
+carve:
+  symbols: _data/symbols.json
+```
+
+```json
+{
+  "smile": "😄",
+  "ship": "🚀"
+}
+```
+
+or a list mixing both, merged left to right, so a generated map can carry a few
+site-specific overrides:
+
+```yaml
+carve:
+  symbols:
+    - _data/emoji.json
+    - ship: "🚀"
+```
+
+A path is resolved against the site source and confined to it, symlinks
+included - a link inside the source pointing at a file outside it is refused
+rather than followed. A name that
+is not in the map keeps rendering as its own text, and the map does not loosen
+Carve's word-boundary rule: `10:30:` and `a:smile:b` are not shortcodes, and
+`` `:smile:` `` inside a code span stays code.
+
+No emoji table ships with this plugin. Jekyll has no emoji database in core, so
+bundling one here would be a second source of truth next to whatever your
+Markdown pages already use (`jemoji`, for instance) - and the two would drift.
+Point `carve.symbols` at a JSON file you generate from that same source and
+both page types resolve one map.
+
+A misconfigured map fails the build rather than being warned past: a missing
+file, invalid JSON, a JSON top level that is not an object, or a value that is
+not a string each raise `ArgumentError` naming the file or the key. A value is
+not coerced, because it reaches the page raw - `count: 1` is a mistake worth
+stopping for, not something to stringify and emit. A NAME is coerced, since
+YAML hands back a Symbol or a boolean for some unquoted keys and a name never
+reaches the output.
+
+> [!WARNING]
+> A symbol value is inserted as **trusted raw output**. It is not escaped, so
+> `smile: "<img src='/s.svg'>"` emits a real `<img>` element rather than
+> escaped text. This is deliberate in the engine - `carve-lang` documents it as
+> "NEVER build a symbols map out of untrusted / user-supplied input" - and it
+> is why this plugin reads the map only from `_config.yml` and from files at
+> paths named there. Never generate `carve.symbols` from page content, from
+> 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
@@ -107,16 +232,11 @@ has already removed the leading block by the time Carve runs.
 | ------ | -------- |
 | `matches(ext)` | `true` for `.crv` (with or without the leading dot, case-insensitive), `false` otherwise. |
 | `output_ext(ext)` | `".html"` (includes the dot so Jekyll emits `page.html`). |
-| `convert(content)` | `Carve.to_html(content, extensions: configured)` - the rendered HTML. |
+| `convert(content)` | `Carve.to_html(content, extensions: configured, symbols: configured)` - the rendered HTML. |
 | `carve_extensions` | The extension list read from `carve.extensions` in `_config.yml` (empty by default). |
+| `carve_symbols` | The `:name:` map read from `carve.symbols` in `_config.yml`, or `nil` when the key is absent. Resolved once per build. |
+| `reset_symbols` | Drops the cached map. Called from the `site, after_reset` hook this plugin registers, which is what scopes the cache to a build so `jekyll serve --watch` picks up an edit to a symbol file. |
 
 ## Development
 
-```sh
-bundle install
-rspec            # run the converter unit tests
-```
-
-## License
-
-MIT, markup-carve.
+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.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/jekyll-carve.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require "jekyll"
 require "carve"
 
@@ -57,7 +59,52 @@ module Jekyll
       #
       # Returns the rendered HTML String.
       def convert(content)
-        ::Carve.to_html(content.to_s, extensions: carve_extensions)
+        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.
@@ -65,11 +112,273 @@ module Jekyll
       # Returns an Array of extension names (Strings/Symbols passed through to
       # the engine). Empty when nothing is configured.
       def carve_extensions
-        carve_config = @config.is_a?(Hash) ? @config["carve"] : nil
-        return [] unless carve_config.is_a?(Hash)
-
         Array(carve_config["extensions"])
       end
+
+      # The `:name:` symbol map configured under `carve.symbols` in _config.yml.
+      #
+      # Carve parses `:name:` in core, but what a name renders as is a render
+      # option, so a document reaching the engine without a map renders the
+      # shortcode as its own source text.
+      #
+      # The key accepts three shapes:
+      #
+      #   carve:
+      #     symbols:                    # a mapping, written inline
+      #       smile: "😄"
+      #
+      #   carve:
+      #     symbols: _data/symbols.json # a path to a JSON object
+      #
+      #   carve:
+      #     symbols:                    # both, merged left to right
+      #       - _data/emoji.json
+      #       - { ship: "🚀" }
+      #
+      # A path is resolved against the site source and clamped inside it, so it
+      # names a file in the project and never one outside it.
+      #
+      # SECURITY: the engine substitutes a symbol value as TRUSTED RAW output -
+      # it is NOT escaped, so `{ "l" => "<img src='/l.svg'>" }` emits a real
+      # element. carve-rb states the rule this inherits: "NEVER build a symbols
+      # map out of untrusted / user-supplied input." That is why the only
+      # inputs here are _config.yml and files at paths named in it. Page
+      # content and front matter cannot reach this method - `convert` ignores
+      # its argument when building the map, and Jekyll hands a converter no
+      # front matter at all.
+      #
+      # Returns a Hash of String name => String value, or nil when nothing is
+      # configured (nil, so the engine keeps its own default rather than being
+      # told there are no symbols).
+      def carve_symbols
+        return @symbols if defined?(@symbols)
+
+        @symbols = build_symbols
+      end
+
+      # Drop the cached map, so the next render resolves it again.
+      #
+      # Called from the `:site, :after_reset` hook at the bottom of this file,
+      # which is what makes the map resolve once per BUILD rather than once per
+      # process. Jekyll instantiates converters from `Site#initialize` while
+      # `Site#process` calls only `reset`, so under `jekyll serve --watch` ONE
+      # converter instance serves every rebuild - and a map memoized outright
+      # would keep serving a file the author has since edited.
+      #
+      # Returns nothing.
+      def reset_symbols
+        remove_instance_variable(:@symbols) if defined?(@symbols)
+      end
+
+      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
+        config.is_a?(Hash) ? config : {}
+      end
+
+      # The configured symbol sources, always as an Array.
+      #
+      # NOT `Array(value)`: a Hash passed to Kernel#Array comes back as an
+      # array of PAIRS ({"a" => "b"} becomes [["a", "b"]]), which would silently
+      # shred an inline mapping into something that is no longer a map.
+      def symbol_sources
+        value = carve_config["symbols"]
+        case value
+        when nil   then []
+        when Array then value
+        else            [value]
+        end
+      end
+
+      # The site source directory a symbol path is resolved against.
+      def site_source
+        source = @config.is_a?(Hash) ? @config["source"].to_s : ""
+        source.empty? ? Dir.pwd : source
+      end
+
+      # One configured path, resolved and confined to the site source.
+      #
+      # Two layers, because they stop different things.
+      #
+      # `Jekyll.sanitized_path` clamps the LEXICAL path: "../../etc/passwd"
+      # comes back as "<source>/etc/passwd", so a written path cannot name a
+      # file outside the project.
+      #
+      # A symlink is not lexical. A link INSIDE the source pointing at a file
+      # outside it survives that clamp, and `File.read` follows it - which on a
+      # host building a site it did not write would read and potentially
+      # publish that file, through a converter that declares `safe true`. So
+      # the resolved path is compared against the site source with both sides
+      # fully resolved. Jekyll takes the same posture in safe mode: its reader
+      # excludes symlinked entries outright.
+      def symbol_path(relative_path)
+        path = Jekyll.sanitized_path(site_source, relative_path)
+        real, root = begin
+          [File.realpath(path), File.realpath(site_source)]
+        rescue SystemCallError
+          # Nothing there to resolve. load_symbol_file raises naming the path.
+          return path
+        end
+        return real if real == root || real.start_with?(root + File::SEPARATOR)
+
+        raise ArgumentError,
+              "carve.symbols: #{relative_path} resolves to #{real}, which is " \
+              "outside the site source #{root}"
+      end
+
+      # Merge every configured source, left to right, into one map.
+      def build_symbols
+        merged = symbol_sources.each_with_object({}) do |source, out|
+          case source
+          when Hash   then out.merge!(normalize_symbols(source, "carve.symbols"))
+          when String then out.merge!(load_symbol_file(source))
+          else
+            raise ArgumentError,
+                  "carve.symbols: expected a mapping or a path to a JSON file, " \
+                  "got #{source.class}"
+          end
+        end
+        merged.empty? ? nil : merged
+      end
+
+      # Read one JSON file named by carve.symbols.
+      #
+      # A misconfigured map is raised rather than warned past: every page loses
+      # every symbol, and a build that renders `:smile:` as text with a line in
+      # the log is the version of this that costs an afternoon.
+      def load_symbol_file(relative_path)
+        path = symbol_path(relative_path)
+        raise ArgumentError, "carve.symbols: no such file: #{path}" unless File.file?(path)
+
+        begin
+          parsed = JSON.parse(File.read(path))
+        rescue JSON::ParserError => e
+          raise ArgumentError, "carve.symbols: #{path} is not valid JSON: #{e.message}"
+        end
+        unless parsed.is_a?(Hash)
+          raise ArgumentError,
+                "carve.symbols: #{path} must hold a JSON object mapping a name " \
+                "to its value, got #{parsed.class}"
+        end
+
+        normalize_symbols(parsed, path)
+      end
+
+      # Check one source and key it by String name.
+      #
+      # These are Hash keys of a shortcode map, NOT Ruby Symbols - `carve.symbols`
+      # and the `Strings/Symbols passed through` of `carve_extensions` are
+      # different things that share a word. A name IS coerced, because YAML
+      # hands back a Symbol or a boolean for some unquoted keys (`:on:` is a
+      # perfectly ordinary shortcode to want) and a name never reaches output.
+      #
+      # A VALUE is not coerced. It goes into the page RAW, so `count: 1` or a
+      # nested mapping is a mistake worth stopping the build for rather than
+      # something to stringify and emit. The engine draws the same line: it
+      # raises TypeError on a non-String value.
+      def normalize_symbols(map, origin)
+        map.each_with_object({}) do |(name, value), out|
+          unless value.is_a?(String)
+            raise ArgumentError,
+                  "#{origin}: the value for #{name.to_s.inspect} must be a string, " \
+                  "got #{value.class}"
+          end
+
+          out[name.to_s] = value
+        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
+# under `jekyll serve --watch`, and it is the only site event that fires on a
+# rebuild without also re-instantiating the converters. See
+# Jekyll::Carve::Converter#reset_symbols.
+#
+# `converters` is nil the first time this fires: `Site#initialize` calls `reset`
+# BEFORE `setup`, and `setup` is what builds the converter list.
+Jekyll::Hooks.register :site, :after_reset do |site|
+  Array(site.converters).each do |converter|
+    converter.reset_symbols if converter.is_a?(Jekyll::Carve::Converter)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-carve
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement
@@ -68,7 +74,8 @@ files:
 homepage: https://github.com/markup-carve/jekyll-carve
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: