katex_on_rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3872cf936c63cb11367add5f9ad324663ed9bc83d023e55e342af3859658faa5
-  data.tar.gz: 9fd09a1fa1aea8f3ccad7aca1c2ef3dc6e97040a877979caaaf45d733af3a04b
+  metadata.gz: 65a6875d2787c1479ffd681369effa5f4a401020d7196a37de1fa351b46e8356
+  data.tar.gz: da26e87077a698b725e93077ce79eb4307b808d9922907ad5528c5f59736032c
 SHA512:
-  metadata.gz: cdeb03ab1ee3ce3dc1f5a7d7a5fac02a75068877092e43e148d5e3fb27705fccf58e2a935c68810487e151f10937b8f6cc510f4178cf274f9e1781281ac61735
-  data.tar.gz: 7582d254885462db762459c9d4bbda3635b1a35dd699d250fb2e00c28dd37b9e409ed29f7d5d238e271173c7d889a094ddfac84fe4933c42b06e130431739a23
+  metadata.gz: 2c181e0591c9732c1ec3414407b89ae08f6373476c0ccf6fb7bb3e974f179d5a64bf68078a48e5a36329cee7125c81e3f5703588aaa4fd595da5149e34412dc5
+  data.tar.gz: cc7bacb594ece4a57d5d4faeb8214ca450a372e4f5928a11eab93adc4103ae20a4fd197286c239e6fb6bf2178af907e44a96fd7269454113b43f46df8e8984f6

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0 (2025-06-30)
+
+- Add `render_in_html` method.
+- Add code documentation.
+
 ## 0.1.0 (2025-06-28)
 
 - Add `render_to_string` method.

data/README.md

@@ -35,17 +35,99 @@ from the `katex` Node.js package, make the KaTeX font files available to the cli
 and use the HTML5 doctype. See [browser usage](https://katex.org/docs/browser).
 Note, however, that you do not need to include `katex.js` on the client.
 
-## Usage
+## Configuration
+
+The KaTeX on Rails initializer allows you to customize how KaTeX processes mathematical expressions.
+You can specify which delimiters to recognize and which HTML tags to ignore during processing.
 
 ```ruby
+# Using the default configuration:
 katex = KatexOnRails.new
 
+# Specifying a custom configuration:
+katex = KatexOnRails.new(
+  delimiters: [
+    { left: '$$', right: '$$', display: true },
+    { left: '$', right: '$', display: false }
+  ],
+  ignored_tags: %w[span]
+)
+```
+
+### `delimiters` (`Array<Hash>`)
+
+A list of delimiters to look for math expressions, processed in the specified order.
+Each delimiter must be a Hash with the following keys:
+
+* `left` (`String`) – The opening delimiter that starts the math expression.
+* `right` (`String`) – The closing delimiter that ends the math expression.
+* `display` (`Boolean`) – Whether to render in display mode (block) or inline mode.
+
+Default delimiters:
+```ruby
+[
+  { left: '$$', right: '$$', display: true },
+  { left: '\(', right: '\)', display: false },
+  { left: '\begin{equation}', right: '\end{equation}', display: true },
+  { left: '\begin{align}', right: '\end{align}', display: true },
+  { left: '\begin{alignat}', right: '\end{alignat}', display: true },
+  { left: '\begin{gather}', right: '\end{gather}', display: true },
+  { left: '\begin{CD}', right: '\end{CD}', display: true },
+  { left: '\[', right: '\]', display: true }
+]
+```
+
+If you want to support inline math via `$`, be sure to place it after `$$` in the array.
+Otherwise, `$$` expressions will be incorrectly parsed as empty `$` expressions.
+
+### `ignored_tags` (`Array<String>`)
+
+A list of HTML tag names to skip when searching for math expressions.
+Use this to prevent processing math-like content in code blocks, scripts, etc.
+
+Default ignored tags:
+```ruby
+%w[script noscript style textarea pre code option]
+```
+
+## Usage
+
+### `render_to_string`
+
+This method takes a LaTeX math expression and converts it directly to an HTML fragment using KaTeX.
+
+Example:
+
+```ruby
 katex.render_to_string('x', { output: 'html' })
-#=> "<span class=\"katex\">..."
+# => "<span class=\"katex\">..."
 ```
 
-The last argument to `render_to_string` can contain a [variety of rendering options](https://katex.org/docs/options).
+Common rendering options are:
+- `display_mode` (`Boolean`) – Render in display (block) mode or inline mode.
+- `throw_on_error` (`Boolean`) – Throw an error on invalid LaTeX (default: true).
+- `output` (`String`) – Output format (`html`, `mathml`, or `htmlAndMathml`).
+
+All the supported options are listed in the [KaTeX documentation](https://katex.org/docs/options).
+
+### `render_in_html`
+
+This method processes an HTML string, automatically detecting and rendering all math expressions found in the HTML
+based on the configured delimiters. It returns a Nokogiri document fragment that can be converted back to a string.
+
+Common rendering options are:
+- `throw_on_error` (`Boolean`) – Throw an error on invalid LaTeX (default: true).
+- `output` (`String`) – Output format (`html`, `mathml`, or `htmlAndMathml`).
+
+All the supported options are listed in the [KaTeX documentation](https://katex.org/docs/options).
+
+Example:
+
+```ruby
+katex.render_in_html('<div>Formula: \(x^2\)</div>', { output: 'html' }).to_html
+# => "<div>Formula: <span class=\"katex\">...</span></div>"
+```
 
 ## License
 
-The KaTeX on Rails gem is is released under the [MIT License](https://opensource.org/licenses/MIT).
+The KaTeX on Rails gem is released under the [MIT License](https://opensource.org/licenses/MIT).

data/katex_on_rails.gemspec

@@ -23,4 +23,5 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.2.0'
   spec.add_dependency 'nodo', '>= 1.8.0'
+  spec.add_dependency 'nokogiri', '>= 1.18.0'
 end

data/lib/katex_on_rails/package.rb

@@ -7,8 +7,8 @@ class KatexOnRails
     require :katex
 
     function :render_to_string, code: <<~JS
-      (text, options) => {
-        return katex.renderToString(text, options);
+      (expression, options) => {
+        return katex.renderToString(expression, options);
       }
     JS
   end

data/lib/katex_on_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class KatexOnRails
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/katex_on_rails.rb

@@ -1,16 +1,182 @@
 # frozen_string_literal: true
 
-require 'katex_on_rails/version'
+require 'nokogiri'
+
 require 'katex_on_rails/package'
+require 'katex_on_rails/version'
 
 class KatexOnRails
-  def render_to_string(text, options = {})
-    katex_package.render_to_string(text, options)
+  DELIMITERS = [
+    { left: '$$', right: '$$', display: true },
+    { left: '\(', right: '\)', display: false },
+    { left: '\begin{equation}', right: '\end{equation}', display: true },
+    { left: '\begin{align}', right: '\end{align}', display: true },
+    { left: '\begin{alignat}', right: '\end{alignat}', display: true },
+    { left: '\begin{gather}', right: '\end{gather}', display: true },
+    { left: '\begin{CD}', right: '\end{CD}', display: true },
+    { left: '\[', right: '\]', display: true }
+  ].freeze
+
+  IGNORED_TAGS = %w[script noscript style textarea pre code option].freeze
+
+  # Initialize the KaTeX on Rails with the provided configuration.
+  #
+  # This initializer allows you to customize how KaTeX processes mathematical expressions
+  # in your HTML content. You can specify which delimiters to recognize and which HTML
+  # tags to ignore during processing.
+  #
+  # @param [Hash] configuration Custom KaTeX on Rails configuration options.
+  # @option configuration [Array<Hash>] delimiters A list of delimiters to look for math.
+  # @option configuration [Array<String>] ignored_tags A list of HTML tags to skip when searching for math.
+  #
+  # @return [KatexOnRails] The KaTeX on Rails instance.
+  #
+  # == Configuration Options
+  #
+  # === +:delimiters+ (Array<Hash>)
+  #
+  # A list of delimiters to look for math expressions, processed in the specified order.
+  # Each delimiter must be a Hash with the following keys:
+  #
+  # * +:left+ (String):: The opening delimiter that starts the math expression.
+  # * +:right+ (String):: The closing delimiter that ends the math expression.
+  # * +:display+ (Boolean):: Whether to render in display mode (block) or inline mode.
+  #
+  # Default delimiters:
+  #
+  #   [
+  #     { left: '$$', right: '$$', display: true },
+  #     { left: '\(', right: '\)', display: false },
+  #     { left: '\begin{equation}', right: '\end{equation}', display: true },
+  #     { left: '\begin{align}', right: '\end{align}', display: true },
+  #     { left: '\begin{alignat}', right: '\end{alignat}', display: true },
+  #     { left: '\begin{gather}', right: '\end{gather}', display: true },
+  #     { left: '\begin{CD}', right: '\end{CD}', display: true },
+  #     { left: '\[', right: '\]', display: true }
+  #   ]
+  #
+  # If you want to support inline math via +$+, be sure to place it after +$$+ in the array.
+  # Otherwise, +$$+ expressions will be incorrectly parsed as empty +$+ expressions.
+  #
+  # === +:ignored_tags+ (Array<String>)
+  #
+  # A list of HTML tag names to skip when searching for math expressions.
+  # Use this to prevent processing math-like content in code blocks, scripts, etc.
+  #
+  # Default ignored tags:
+  #
+  #   %w[script noscript style textarea pre code option]
+  #
+  # == Examples
+  #
+  # Usage with the default configuration:
+  #
+  #   katex = KatexOnRails.new
+  #
+  # Usage with a custom configuration:
+  #
+  #   katex = KatexOnRails.new(
+  #     delimiters: [
+  #       { left: '$$', right: '$$', display: true },
+  #       { left: '$', right: '$', display: false }
+  #     ],
+  #     ignored_tags: %w[span]
+  #   )
+  #
+  def initialize(**configuration)
+    @delimiters = configuration.fetch(:delimiters, DELIMITERS)
+    @ignored_tags = configuration.fetch(:ignored_tags, IGNORED_TAGS)
+    @katex_package ||= Package.new
+  end
+
+  # Generate an HTML string of the rendered math expression.
+  #
+  # This method takes a LaTeX math expression and converts it directly to an HTML fragment using KaTeX.
+  #
+  # @param [String] expression The LaTeX math expression to render.
+  # @param [Hash] options The KaTeX rendering options (see KaTeX documentation).
+  #
+  # @return [String] HTML string containing the rendered math.
+  #
+  # == Rendering Options
+  #
+  # Common options are:
+  #
+  # - +:display_mode+ (Boolean):: Render in display (block) mode or inline mode.
+  # - +:throw_on_error+ (Boolean):: Throw an error on invalid LaTeX (default: true).
+  # - +:output+ (String):: Output format ('html', 'mathml', or 'htmlAndMathml').
+  #
+  # All the supported options are listed in the {KaTeX documentation}[https://katex.org/docs/options].
+  #
+  # == Example
+  #
+  #   KatexOnRails.new.render_to_string('x', { output: 'html' })
+  #   # => "<span class=\"katex\">..."
+  #
+  def render_to_string(expression, options = {})
+    @katex_package.render_to_string(expression, options)
+  end
+
+  # Render all math expressions found within an HTML fragment.
+  #
+  # This method processes an HTML string, automatically detecting
+  # and rendering any math expressions based on the configured delimiters.
+  # It returns a Nokogiri document fragment that can be converted back to a string.
+  #
+  # @param [String] html_fragment The HTML content to process.
+  # @param [Hash] options KaTeX rendering options.
+  #
+  # @return [Nokogiri::HTML5::DocumentFragment] Processed HTML with rendered math.
+  #
+  # == Rendering Options
+  #
+  # Common options are:
+  #
+  # - +:throw_on_error+ (Boolean):: Throw an error on invalid LaTeX (default: true).
+  # - +:output+ (String):: Output format ('html', 'mathml', or 'htmlAndMathml').
+  #
+  # All the supported options are listed in the {KaTeX documentation}[https://katex.org/docs/options].
+  #
+  # == Examples
+  #
+  #   KatexOnRails.new.render_in_html('<div>Formula: \(x^2\)</div>', { output: 'html' }).to_html
+  #   # => "<div>Formula: <span class=\"katex\">...</span></div>"
+  #
+  def render_in_html(html_fragment, options = {})
+    html_fragment = html_fragment.to_html if html_fragment.respond_to?(:to_html)
+    doc = Nokogiri::HTML5.fragment(html_fragment.to_s)
+
+    @delimiters.each do |delimiter|
+      delimiter_left = Regexp.escape(delimiter[:left].to_s)
+      delimiter_right = Regexp.escape(delimiter[:right].to_s)
+      math_regexp = /#{delimiter_left}(.*?)#{delimiter_right}/
+
+      each_text_node(doc) do |current_node|
+        content = current_node.content
+        next unless math_regexp.match?(content)
+
+        new_content = content.gsub(math_regexp) do |_match|
+          render_to_string(
+            ::Regexp.last_match(1),
+            options.merge({ displayMode: delimiter[:display] })
+          )
+        end
+
+        new_fragment = Nokogiri::HTML5.fragment(new_content)
+        current_node.replace(new_fragment)
+      end
+    end
+
+    doc
   end
 
   private
 
-  def katex_package
-    @katex_package ||= Package.new
+  def each_text_node(node, &)
+    return if @ignored_tags.include?(node.name)
+
+    node.children.each { |child| each_text_node(child, &) }
+
+    yield node if node.text?
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: katex_on_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Juraj Kostolansky
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-28 00:00:00.000000000 Z
+date: 2025-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nodo
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.8.0
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.18.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.18.0
 description:
 email:
 - juraj@kostolansky.sk