jekyll-carve 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d5439f1f1f23a853c560a40a84f7b210a2625682f4b5a66483cfb23361744f4
-  data.tar.gz: 87ae6478fa6a2af0e2026611f41fb4d2118677496222325d89e9f8cb03a7156e
+  metadata.gz: f2fa9dda47fb228d8edba3147048e720d9ee7995a14c38b9f4cac9cf8bfe8f6e
+  data.tar.gz: 83252c17f31ccdf1f34b64785dbf928fc96619e2a35e243facef5543a71439b8
 SHA512:
-  metadata.gz: b5cd475edd480cd1465c4114b13ecd817c916342e0b073939cc773e3e09f85d8a294aa55b3ed6eb28b56889de1cce67e3a3c91a2716ff53f1a8d5d36935c40b0
-  data.tar.gz: 79a03d86ffe55a4c7fcd8c0f23d071ff6479745d241b4f216775d27eb4d122e91c2b1c76fca5228e877a9279dcd0152abf69339a83f6c62bee59a719e914851a
+  metadata.gz: d9230de7ea7aed19ff33d752aee2c53c8529cf622e742134e41b22d188f61460ea2813b1f34ea82c3544101281004d4e0c42c18b44c5af4f4174bfd52cc178cb
+  data.tar.gz: 4f50c860251b43b10ea16807c6f8624226c6399a3044c1d1a063020fceb70ab994aa03b9161370ec0d6d472757a0ca544360fa25f0bb6dd757c4d1de58b8435c

data/README.md

@@ -51,6 +51,85 @@ 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.
+
 ## Usage
 
 Create a page with a `.crv` extension. It MUST begin with Jekyll
@@ -107,16 +186,39 @@ 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
+bundle exec rspec   # run the converter unit tests
 ```
 
-## License
+### 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)
+```
 
-MIT, markup-carve.
+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`.

data/lib/jekyll/carve/version.rb

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

data/lib/jekyll-carve.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require "jekyll"
 require "carve"
 
@@ -57,7 +59,9 @@ module Jekyll
       #
       # Returns the rendered HTML String.
       def convert(content)
-        ::Carve.to_html(content.to_s, extensions: carve_extensions)
+        ::Carve.to_html(content.to_s,
+                        extensions: carve_extensions,
+                        symbols: carve_symbols)
       end
 
       # Carve extensions configured under `carve.extensions` in _config.yml.
@@ -65,11 +69,198 @@ 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
+
+      # 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
   end
 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.1
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-27 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: