jekyll-carve 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28da599466525fea6bbc65a8c6143d8579241a20f1838d6ccb0f9d0317ac3405
-  data.tar.gz: f36f40e656e8d8ea3da71e207cbaeb61f7daf43b06f8ae7ef41f6d34dd9ad4f7
+  metadata.gz: ee0dd725f2e978b4b58399574f0048b8c3b57e065c4b829313a49b19405181b6
+  data.tar.gz: 9aafac417e690c501f476bba589f0eb59bdda2987ce9a76b5fd6144ef80c199b
 SHA512:
-  metadata.gz: 869155a13081b84dcbd811b2a6474a8e1df7b282924c3b187226c0b16e782d8180f46dfd3b9fa9348c9ed631c0d8b37f33381c7e41849ec6571052c2619cd85b
-  data.tar.gz: 7fceaae2aee055d86faccc18445e2e5191dba2d9c3a74a73bd91ba1bffac31b531aa7fbcfce58da156379cb42f1f80214b9576a712d488f060e07cde018cd57b
+  metadata.gz: 63a663cb509fc3fa5ff68b776be24add79aedf2dfdf3523c2fbab7d0d4d4f3d390015aa027722e8a22e48cda0dec6c3106fdf038179febdc5c245678ec9fc89e
+  data.tar.gz: 72d041918581593eef7bb4cd4dd3f57ab96f1d868b9f15cdb207259557c704c150813fbb79df03b30350ff5b3f634ee12f2c7d6aef20254f55d719a12a547a4d

data/README.md

@@ -1,242 +1,25 @@
 # jekyll-carve
 
-A [Jekyll](https://jekyllrb.com) converter plugin for the
-[Carve](https://github.com/markup-carve/carve) markup language. It renders
-`.crv` pages to HTML by delegating to the native
-[`carve-lang`](https://github.com/markup-carve/carve-rb) gem (`Carve.to_html`). No
-parser is reimplemented here; this is a thin `Jekyll::Converter` adapter over
-the engine.
+Jekyll converter for `.crv` pages, using the carve-lang gem 0.1.11 or later. It renders Carve pages through the native engine. Read the [Carve documentation](https://markup-carve.github.io/carve/) for the language syntax.
 
 ## Install
 
-Add both gems to your site's `Gemfile`:
-
-```ruby
-# Gemfile
-gem "jekyll-carve"
-gem "carve-lang" # the native Carve engine (a runtime dependency, listed for clarity)
-```
-
 ```sh
-bundle install
-```
-
-Then enable the plugin in `_config.yml`:
-
-```yaml
-plugins:
-  - jekyll-carve
-```
-
-> [!NOTE]
-> The `carve-lang` gem ships a Rust native extension and is compiled at install
-> time. It requires a Rust toolchain (`cargo`) and Ruby development headers.
-> See the carve-rb README for build notes (including the libclang/`stdarg.h`
-> workaround on some systems).
-
-## Configuration
-
-Carve engine options are read from `_config.yml` under the `carve` key:
-
-```yaml
-carve:
-  extensions:
-    - heading_permalinks
-    - math_block
-    - autolink
-```
-
-`carve.extensions` is an array of opt-in Carve extension names (Strings or
-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: "🚀"
+bundle add jekyll-carve
 ```
 
-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
-YAML front matter, and the Carve body follows below:
-
-```text
----
-layout: default
-title: Home
----
-# Welcome to *Carve*
-
-This is /italic/ and *bold* text.
-
-- Apple
-- Banana
-```
-
-Note Carve's inline syntax: `*...*` is **strong** (bold) and `/.../` is
-_emphasis_ (italic) - the opposite of Markdown.
-
-## Important: Jekyll front matter vs. Carve frontmatter
-
-This is the one nuance to understand:
-
-- **Jekyll only runs a file through a converter if it has YAML front matter**
-  (a `---` ... `---` block at the very top). A `.crv` file with no front
-  matter is treated as a static file and copied verbatim, NOT converted.
-- **Jekyll strips that front matter before calling the converter.** So the
-  converter (and therefore the Carve engine) receives only the document
-  **body**, never the Jekyll front matter.
-- **Carve itself also uses `---` for its own frontmatter.** In a Jekyll site
-  the Jekyll front matter wins: the top `---` ... `---` block is consumed by
-  Jekyll, and whatever remains is handed to Carve as the body.
-
-Practical rule: a `.crv` page in Jekyll needs at least an empty front matter
-block so Jekyll processes it:
-
-```text
----
----
-# Your Carve content here
+```yaml
+plugins: [jekyll-carve]
 ```
 
-Put page metadata (`title`, `layout`, etc.) in the Jekyll front matter. Do not
-add a second Carve `---` frontmatter block expecting Carve to parse it; Jekyll
-has already removed the leading block by the time Carve runs.
-
-## Converter API
-
-`Jekyll::Carve::Converter < Jekyll::Converter`:
+## Documentation
 
-| Method | Behavior |
-| ------ | -------- |
-| `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, 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. |
+- [Carve documentation](https://markup-carve.github.io/carve/)
+- [Documentation index](docs/README.md)
+- [Development](docs/development.md)
 
-## Development
+## License
 
-Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).
+[MIT](LICENSE)

data/lib/jekyll/carve/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Carve
-    VERSION = "0.1.3"
+    VERSION = "0.1.5"
   end
 end

data/lib/jekyll-carve.rb

@@ -61,32 +61,46 @@ module Jekyll
       def convert(content)
         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
+        include_page = !(root.nil? || document.nil? || document.path.to_s.empty?)
+        html = render(content.to_s, document, include_page ? root : nil)
+        lint(content.to_s, document, include_page ? root : nil) if lint_mode
+        html
+      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.
+      # How `carve.lint` is set: nil (off), :warn or :strict.
+      #
+      # `true` logs each finding as a build warning; `"strict"` also fails the
+      # build once every page has been linted.
+      def lint_mode
+        case (value = carve_config["lint"])
+        when nil, false then nil
+        when true then :warn
+        when "strict", :strict then :strict
+        else
           raise ArgumentError,
-                "carve.include_root: #{document.relative_path || document.path}: #{e.message}"
+                "carve.lint: expected true, false or \"strict\", got #{value.inspect}"
         end
-        report_includes(result, document, root)
-        result[:value]
+      end
+
+      # Lint findings counted under `carve.lint: strict` since the last reset.
+      def lint_findings
+        @lint_findings ||= 0
+      end
+
+      # Fail the build when strict lint counted a finding.
+      #
+      # Called from the `:site, :post_render` hook below, so every page is
+      # linted and reported before the build stops.
+      def check_lint!
+        return unless lint_mode == :strict && lint_findings.positive?
+
+        raise Jekyll::Errors::FatalException,
+              "carve.lint: #{lint_findings} lint finding(s) under strict mode; see the warnings above"
+      end
+
+      # Drop the strict-mode count, so each build is judged on its own.
+      def reset_lint
+        @lint_findings = 0
       end
 
       # The containment root configured under `carve.include_root`, or nil when
@@ -172,6 +186,71 @@ module Jekyll
 
       private
 
+      def render(content, document, root)
+        if root.nil?
+          return ::Carve.to_html(content,
+                                 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,
+                                                 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
+
+      # Log each lint finding as a build warning, located in the source file.
+      #
+      # Runs after rendering, so a bad include root is reported by the render
+      # path with its own message. With includes on, the include-* findings
+      # repeat the include warnings `report_includes` already logged, so they
+      # are counted but not logged twice.
+      def lint(content, document, root)
+        page = document && (document.relative_path || document.path).to_s
+        page = "(no page)" if page.nil? || page.empty?
+        options = { extensions: carve_extensions }
+        options.update(root: root, source_path: document.path) if root
+        findings = ::Carve.lint(content, **options)
+        offset = front_matter_lines(document)
+        findings.each do |finding|
+          next if root && finding[:rule].start_with?("include-")
+
+          where = if finding[:file]
+                    "#{page} (#{finding[:file]}:#{finding[:line]}:#{finding[:column]})"
+                  else
+                    "#{page}:#{finding[:line] + offset}:#{finding[:column]}"
+                  end
+          Jekyll.logger.warn "Carve lint:", "#{where}: #{finding[:rule]}: #{finding[:message]}"
+        end
+        @lint_findings = lint_findings + findings.size if lint_mode == :strict
+      end
+
+      # Lines of YAML front matter above the body, so a finding names the line
+      # in the file. Jekyll strips the front matter before `convert` sees it.
+      def front_matter_lines(document)
+        path = document&.path.to_s
+        return 0 if path.empty? || !File.file?(path)
+
+        match = Jekyll::Document::YAML_FRONT_MATTER_REGEXP.match(File.read(path, encoding: "bom|utf-8"))
+        match ? match[0].count("\n") : 0
+      end
+
       # Surface what expansion degraded, and record what it read.
       def report_includes(result, document, root)
         page = document.relative_path || document.path
@@ -379,6 +458,17 @@ end
 # 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)
+    next unless converter.is_a?(Jekyll::Carve::Converter)
+
+    converter.reset_symbols
+    converter.reset_lint
+  end
+end
+
+# `carve.lint: strict` fails here, after every page was linted and before any
+# output is written.
+Jekyll::Hooks.register :site, :post_render do |site|
+  Array(site.converters).each do |converter|
+    converter.check_lint! 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.3
+  version: 0.1.5
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.11
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.11
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0