middleman-commonmarker 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2843575c04f2b516147d5aaaa62789482ead5e3e65950ac268b824759883c1bf
-  data.tar.gz: 9e90c64fba5895575d957c0d9ad174254f7242d06e648405f7a84b01e9e7703c
+  metadata.gz: a84e082e8ec76cfb63d7acbde0e2fdd5ab6a2f4355e7fe322924b74ecaa81d16
+  data.tar.gz: 1d2ef217f0fe335f01c98d5e28292dfb98f3c56eca4e25c25fdf7d04e6e57022
 SHA512:
-  metadata.gz: 18e343279365e8a11a2ace792f8441cf5f4f8753c40d4a8772389117937346428d8461474c77888cca55dc117e95277f62e64d54dc0bca77aaa735bf999cf49f
-  data.tar.gz: 60024dfa0cc18d349f5b93f8d2a1ddaa2b60e6cba42fa83c53b710196d6268db4629ef24360d71d2ff511f876804c1e80f12b4066a026e90bd1ba0f9e4600672
+  metadata.gz: babd88f6b95ea0b671f00d824bb3a1e5e3a16ebbd101b95de6ebac79740f8a1365c4b063fe5720ea4bf3a9ebe2a5ce2819f3fbeb52ae4826d56229f015e67573
+  data.tar.gz: 81b518c5818560624547091fab0da203dbf772c775af1079540f416ee82280f49ef8ef7d4ffb77b255bae13ed70c5bbea662ccc563ef27c6605a5e77fba1234a

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-25
+
+- Add `plugins` option to pass commonmarker plugins (e.g. syntax highlighter theme) ([#18](https://github.com/unasuke/middleman-commonmarker/pull/18))
+
 ## [0.1.0] - 2026-05-27
 
 - Initial release

data/README.md

@@ -46,6 +46,29 @@ Note that flat keys on `activate` (e.g. `activate :commonmarker, table: true`) a
 
 These flat options are mapped onto commonmarker's `parse` / `render` / `extension` option groups (and `smartypants` maps to `parse.smart`).
 
+### Syntax highlighting
+
+By default, commonmarker highlights fenced code blocks with the `base16-ocean.dark` theme, writing the colors as inline `style` attributes.
+
+Use the `plugins` option to change this. Its value is passed as-is to commonmarker's `plugins:` argument; see [commonmarker's README](https://github.com/gjtorikian/commonmarker#plugins) for the available values.
+
+```ruby
+# Use another built-in theme
+set :markdown, plugins: {syntax_highlighter: {theme: "InspiredGitHub"}}
+
+# Load syntax_themes/my-theme.tmTheme
+set :markdown, plugins: {
+  syntax_highlighter: {theme: "my-theme", path: File.expand_path("syntax_themes", __dir__)}
+}
+
+# Disable syntax highlighting
+set :markdown, plugins: {syntax_highlighter: nil}
+```
+
+Give `path` as an absolute path; a relative path is resolved against the current working directory.
+
+`plugins` can also be given through `activate :commonmarker, options: { plugins: ... }`. When both are set, the `activate` value replaces the `set :markdown` value entirely (no deep merge).
+
 ### Raw HTML is enabled during rendering
 
 To emit the `<img>` HTML produced by `image_tag`, the renderer forces commonmarker's `unsafe: true` during transformation.
@@ -53,7 +76,7 @@ As a result, raw HTML in your Markdown is passed through (consistent with Redcar
 
 ## Scope
 
-This extension covers helper integration (`image_tag` / `url_for`), `automatic_image_sizes`, and commonmarker's native parse/render/extension options (`table`, `strikethrough`, `autolink`, `smartypants`, `tasklist`, …).
+This extension covers helper integration (`image_tag` / `url_for`), `automatic_image_sizes`, commonmarker's native parse/render/extension options (`table`, `strikethrough`, `autolink`, `smartypants`, `tasklist`, …), and commonmarker plugins such as the syntax highlighter (`plugins`).
 Redcarpet-specific options such as `no_images`, `no_links`, `link_attributes`, and `filter_html` are out of scope.
 
 ## Development

data/features/commonmarker.feature

@@ -75,6 +75,27 @@ Feature: Markdown (Commonmarker) support
     When I go to "/tables.html"
     Then I should see "<table>"
 
+  Scenario: Commonmarker passes plugins through set :markdown
+    Given a fixture app "markdown-app"
+    And a file named "config.rb" with:
+      """
+      activate :commonmarker
+      set :markdown, plugins: {syntax_highlighter: {theme: "InspiredGitHub"}}
+      """
+    Given the Server is running at "markdown-app"
+    When I go to "/fenced_code_blocks.html"
+    Then I should see "background-color:#ffffff"
+
+  Scenario: Commonmarker passes plugins through activate
+    Given a fixture app "markdown-app"
+    And a file named "config.rb" with:
+      """
+      activate :commonmarker, options: {plugins: {syntax_highlighter: {theme: "InspiredGitHub"}}}
+      """
+    Given the Server is running at "markdown-app"
+    When I go to "/fenced_code_blocks.html"
+    Then I should see "background-color:#ffffff"
+
   Scenario: Commonmarker uses our link_to and image_tag helpers
     Given a fixture app "markdown-app"
     And a file named "config.rb" with:

data/lib/middleman-commonmarker/commonmarker_template.rb

@@ -2,6 +2,7 @@
 
 require "commonmarker"
 require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/hash/keys"
 
 module Middleman
   module Renderers
@@ -21,6 +22,7 @@ module Middleman
 
       def prepare
         @context = options.delete(:context)
+        @commonmarker_plugins = build_commonmarker_plugins
         @commonmarker_options = build_commonmarker_options
       end
 
@@ -36,10 +38,10 @@ module Middleman
             end
           end
           # Force unsafe so the injected raw <img> HTML is emitted.
-          return doc.to_html(options: render_options_with_unsafe)
+          return render_html(doc, render_options_with_unsafe)
         end
 
-        doc.to_html(options: @commonmarker_options)
+        render_html(doc, @commonmarker_options)
       end
 
       private
@@ -77,12 +79,32 @@ module Middleman
         nil
       end
 
+      # Render with the user's `plugins` when given; otherwise let commonmarker
+      # apply its default plugins.
+      def render_html(doc, commonmarker_options)
+        doc.to_html(options: commonmarker_options, **@commonmarker_plugins)
+      end
+
       def render_options_with_unsafe
         @commonmarker_options.merge(
           render: @commonmarker_options[:render].merge(unsafe: true)
         )
       end
 
+      # Take `plugins` out of the options as keyword arguments for to_html: {}
+      # when unset, {plugins: value} when set (a nil value disables the syntax
+      # highlighter). When both :plugins and "plugins" are present, the later
+      # one wins, as with the flat options, so `activate` overrides
+      # `set :markdown`.
+      def build_commonmarker_plugins
+        keys = options.keys.select { |key| key.to_s == "plugins" }
+        return {} if keys.empty?
+
+        value = keys.map { |key| options.delete(key) }.last
+        value = value.deep_symbolize_keys if value.is_a?(Hash)
+        {plugins: value}
+      end
+
       # Distribute the flat `set :markdown, ...` options into the
       # parse/render/extension nested structure, mapping `smartypants` to
       # parse.smart.

data/lib/middleman-commonmarker/version.rb

@@ -2,6 +2,6 @@
 
 module Middleman
   module Commonmarker
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/sig/middleman-commonmarker/commonmarker_template.rbs

@@ -16,7 +16,9 @@ module Middleman
       def transform_link_node: (untyped node) -> void
       def extract_text: (untyped node) -> String
       def html_node_from: (String html) -> untyped
+      def render_html: (untyped doc, Hash[Symbol, untyped] commonmarker_options) -> String
       def render_options_with_unsafe: () -> Hash[Symbol, untyped]
+      def build_commonmarker_plugins: () -> Hash[Symbol, untyped]
       def build_commonmarker_options: () -> Hash[Symbol, untyped]
     end
   end

data/test/commonmarker_template_test.rb

@@ -1,18 +1,29 @@
 # frozen_string_literal: true
 
 require "test_helper"
+require "pathname"
 
 class CommonmarkerTemplateTest < Minitest::Test
-  # Build a template instance; prepare runs on init and computes
-  # @commonmarker_options from the given options.
-  def build(opts = {})
-    Middleman::Renderers::CommonmarkerTemplate.new(nil, 1, opts) { "" }
+  CODE_BLOCK = "```ruby\nputs 1\n```\n"
+  THEMES_DIR = File.expand_path("fixtures", __dir__)
+
+  # Build a template instance whose source is `body`; prepare runs on init
+  # and computes @commonmarker_plugins and @commonmarker_options from the
+  # given options.
+  def build(opts = {}, body = "")
+    Middleman::Renderers::CommonmarkerTemplate.new(nil, 1, opts) { body }
   end
 
   def options_for(opts)
     build(opts).instance_variable_get(:@commonmarker_options)
   end
 
+  # Render CODE_BLOCK with the given options. Tilt passes Object.new as the
+  # scope, so this goes through the scope branch of evaluate.
+  def html_for(opts)
+    build(opts, CODE_BLOCK).render
+  end
+
   def image_node(markdown)
     node = Commonmarker.parse(markdown)
     found = nil
@@ -53,4 +64,88 @@ class CommonmarkerTemplateTest < Minitest::Test
   def test_html_node_from_returns_nil_when_no_html_present
     assert_nil build.send(:html_node_from, "just plain text")
   end
+
+  def test_plugins_unset_matches_commonmarker_default
+    template = build({}, CODE_BLOCK)
+    opts = template.send(:render_options_with_unsafe)
+    expected = Commonmarker.parse(CODE_BLOCK, options: opts).to_html(options: opts)
+    assert_equal expected, template.render
+  end
+
+  def test_plugins_with_builtin_theme
+    html = html_for(plugins: {syntax_highlighter: {theme: "InspiredGitHub"}})
+    assert_includes html, "background-color:#ffffff"
+  end
+
+  def test_plugins_with_theme_from_path
+    html = html_for(plugins: {syntax_highlighter: {theme: "test-theme", path: THEMES_DIR}})
+    assert_includes html, "background-color:#123456"
+  end
+
+  def test_plugins_with_path_only_keeps_default_theme
+    assert_equal html_for({}), html_for(plugins: {syntax_highlighter: {path: THEMES_DIR}})
+  end
+
+  def test_plugins_with_empty_theme_outputs_classes
+    html = html_for(plugins: {syntax_highlighter: {theme: ""}})
+    assert_includes html, %(<pre class="syntax-highlighting">)
+    refute_includes html, "style="
+  end
+
+  def test_plugins_disabling_highlighter
+    [{syntax_highlighter: nil}, {}, nil].each do |plugins|
+      refute_includes html_for(plugins:), "style=", "plugins: #{plugins.inspect}"
+    end
+  end
+
+  def test_plugins_with_misspelled_key_disables_highlighter
+    refute_includes html_for(plugins: {syntax_highlight: {theme: "InspiredGitHub"}}), "style="
+  end
+
+  def test_plugins_with_string_keys
+    assert_equal html_for(plugins: {syntax_highlighter: {theme: "InspiredGitHub"}}),
+      html_for(plugins: {"syntax_highlighter" => {"theme" => "InspiredGitHub"}})
+  end
+
+  def test_later_plugins_key_takes_precedence
+    inspired = {syntax_highlighter: {theme: "InspiredGitHub"}}
+    assert_equal html_for(plugins: inspired), html_for({:plugins => nil, "plugins" => inspired})
+    assert_equal html_for(plugins: nil), html_for({"plugins" => inspired, :plugins => nil})
+  end
+
+  def test_plugins_with_unknown_theme_raises
+    assert_raises(ArgumentError) { html_for(plugins: {syntax_highlighter: {theme: "no-such-theme"}}) }
+  end
+
+  def test_plugins_with_empty_highlighter_raises
+    assert_raises(TypeError) { html_for(plugins: {syntax_highlighter: {}}) }
+  end
+
+  def test_plugins_with_nil_theme_raises
+    assert_raises(TypeError) { html_for(plugins: {syntax_highlighter: {theme: nil}}) }
+  end
+
+  def test_plugins_with_non_hash_value_raises
+    {"x" => NoMethodError, [1] => TypeError}.each do |plugins, error|
+      assert_raises(error, "plugins: #{plugins.inspect}") { html_for(plugins:) }
+    end
+  end
+
+  def test_plugins_with_pathname_path_raises
+    assert_raises(TypeError) do
+      html_for(plugins: {syntax_highlighter: {theme: "test-theme", path: Pathname(THEMES_DIR)}})
+    end
+  end
+
+  def test_plugins_are_not_mixed_into_commonmarker_options
+    opts = options_for(plugins: {syntax_highlighter: {theme: "InspiredGitHub"}})
+    refute opts[:parse].key?(:plugins)
+    refute opts[:render].key?(:plugins)
+    refute opts[:extension].key?(:plugins)
+  end
+
+  def test_plugins_apply_without_scope
+    template = build({plugins: {syntax_highlighter: {theme: "InspiredGitHub"}}}, CODE_BLOCK)
+    assert_includes template.send(:evaluate, nil, {}), "background-color:#ffffff"
+  end
 end

data/test/fixtures/test-theme.tmTheme

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>name</key>
+  <string>test-theme</string>
+  <key>settings</key>
+  <array>
+    <dict>
+      <key>settings</key>
+      <dict>
+        <key>background</key>
+        <string>#123456</string>
+        <key>foreground</key>
+        <string>#abcdef</string>
+      </dict>
+    </dict>
+  </array>
+</dict>
+</plist>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: middleman-commonmarker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yusuke Nakamura
@@ -85,6 +85,7 @@ files:
 - sig/middleman-commonmarker/extension.rbs
 - sig/middleman-commonmarker/version.rbs
 - test/commonmarker_template_test.rb
+- test/fixtures/test-theme.tmTheme
 - test/test_helper.rb
 homepage: https://github.com/unasuke/middleman-commonmarker
 licenses:
@@ -109,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Commonmarker (CommonMark) markdown engine extension for Middleman
 test_files: []