jekyll-carve 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d5439f1f1f23a853c560a40a84f7b210a2625682f4b5a66483cfb23361744f4
+  data.tar.gz: 87ae6478fa6a2af0e2026611f41fb4d2118677496222325d89e9f8cb03a7156e
+SHA512:
+  metadata.gz: b5cd475edd480cd1465c4114b13ecd817c916342e0b073939cc773e3e09f85d8a294aa55b3ed6eb28b56889de1cce67e3a3c91a2716ff53f1a8d5d36935c40b0
+  data.tar.gz: 79a03d86ffe55a4c7fcd8c0f23d071ff6479745d241b4f216775d27eb4d122e91c2b1c76fca5228e877a9279dcd0152abf69339a83f6c62bee59a719e914851a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 markup-carve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# 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.
+
+## 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.
+
+## 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
+```
+
+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`:
+
+| 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)` - the rendered HTML. |
+| `carve_extensions` | The extension list read from `carve.extensions` in `_config.yml` (empty by default). |
+
+## Development
+
+```sh
+bundle install
+rspec            # run the converter unit tests
+```
+
+## License
+
+MIT, markup-carve.

data/lib/jekyll/carve/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Carve
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll-carve.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "carve"
+
+require "jekyll/carve/version"
+
+module Jekyll
+  module Carve
+    # Jekyll converter for the Carve markup language.
+    #
+    # Registers the `.crv` file extension and renders Carve
+    # bodies to HTML by delegating to the native `carve-lang` gem
+    # (Carve.to_html). No parsing is reimplemented here; this is a thin
+    # Jekyll::Converter adapter over the engine.
+    class Converter < Jekyll::Converter
+      # File extensions this converter handles (lowercased, with and without
+      # the leading dot so callers may pass either form).
+      EXTENSIONS = %w[.crv].freeze
+
+      safe true
+      priority :low
+
+      # Does the given file extension belong to Carve?
+      #
+      # Accepts both ".crv" and "crv" (Jekyll passes the dotted form).
+      #
+      # ext - The String extension to check.
+      #
+      # Returns true if it matches, false otherwise.
+      def matches(ext)
+        return false if ext.nil?
+
+        normalized = ext.to_s.downcase
+        normalized = ".#{normalized}" unless normalized.start_with?(".")
+        EXTENSIONS.include?(normalized)
+      end
+
+      # The output extension for a converted Carve file.
+      #
+      # Jekyll appends this string directly to the output path
+      # (":basename:output_ext"), so it MUST include the leading dot to
+      # produce "index.html" rather than "indexhtml". This matches Jekyll's
+      # own Markdown converter, which returns ".html".
+      #
+      # Returns ".html".
+      def output_ext(_ext)
+        ".html"
+      end
+
+      # Convert a Carve document body to HTML.
+      #
+      # Jekyll strips the YAML front matter before calling this, so `content`
+      # is the Carve body only.
+      #
+      # content - String body of the source file (front matter removed).
+      #
+      # Returns the rendered HTML String.
+      def convert(content)
+        ::Carve.to_html(content.to_s, extensions: carve_extensions)
+      end
+
+      # Carve extensions configured under `carve.extensions` in _config.yml.
+      #
+      # 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
+    end
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-carve
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- markup-carve
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: carve-lang
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |-
+  A Jekyll plugin that renders Carve (.crv) pages to HTML. It is a
+  thin Jekyll::Converter over the native `carve-lang` gem (Carve.to_html);
+  no parser is reimplemented.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll-carve.rb
+- lib/jekyll/carve/version.rb
+homepage: https://github.com/markup-carve/jekyll-carve
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Jekyll converter for the Carve markup language.
+test_files: []