asciidoctor-katex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8fe4e14368b676f0b85542bf052faaac55308d0a53229551034b0343f5efbdaf
+  data.tar.gz: acc3c63000b2f03af463b8e2b3129d4374aa6add7f4eef24ad1dabcd8d9597ed
+SHA512:
+  metadata.gz: 0a0544bff51d8b8cc3db4cf041feab4c1c64a326517063d39c33e81e99b57a5883fe53634e6f8f82837862b5ff68d63635297c16231422cb836a38fa2280fb1f
+  data.tar.gz: acb95d9a74f1e2f02b7ea296e05e77f9825e41007c405cc258bb4cd51c0af6f8803295d08877068121ce27f65dafd7defbc230682834b0312e4d7a8022fba05a

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright 2018 Jakub Jirutka <jakub@jirutka.cz>.
+
+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.adoc

@@ -0,0 +1,139 @@
+= Asciidoctor KaTeX
+:source-language: shell
+// custom
+:gem-name: asciidoctor-katex
+:gh-name: jirutka/{gem-name}
+:gh-branch: master
+:codacy-id: 58f6aa6e3ef04c8aad1ecd276a8a2c35
+
+ifdef::env-github[]
+image:https://travis-ci.com/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.com/{gh-name}"]
+image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"]
+image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"]
+image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
+image:https://img.shields.io/npm/v/{gem-name}.svg?style=flat[npm Version, link="https://www.npmjs.org/package/{gem-name}"]
+image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"]
+endif::env-github[]
+
+
+This project provides an http://asciidoctor.org/[Asciidoctor] extension for converting block and inline https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM] in TeX notation (latexmath) to HTML using https://khan.github.io/KaTeX[KaTeX] library right during document conversion (instead of in browser on client-side).
+
+
+== Requirements
+
+=== Ruby
+
+* https://www.ruby-lang.org/[Ruby] 2.3+ or http://jruby.org/[JRuby] 9.1+
+* https://rubygems.org/gems/asciidoctor/[Asciidoctor] 1.5.6+
+* https://rubygems.org/gems/katex[katex (gem)] 0.4.3+
+* JavaScript engine supported by https://github.com/rails/execjs#execjs[ExecJS]
+* https://rubygems.org/gems/thread_safe/[thread_safe] (not required, but recommended for Ruby MRI)
+
+
+=== Node.js
+
+* https://nodejs.org/[Node.js] 8+
+* https://www.npmjs.com/package/asciidoctor.js[asciidoctor.js] 1.5.6
+* https://www.npmjs.com/package/katex[katex (module)] 0.9.0+
+
+
+== Installation
+
+=== Ruby
+
+Install {gem-name} from Rubygems:
+
+[source, subs="+attributes"]
+gem install {gem-name}
+
+or to install the latest development version:
+
+[source, subs="+attributes"]
+gem install {gem-name} --pre
+
+
+=== Node.js
+
+Install {gem-name} from npmjs.com:
+
+[source, sh, subs="+attributes"]
+npm install --save {gem-name}
+
+
+== Usage
+
+=== CLI
+
+If you invoke Asciidoctor from command-line, use option `-r` to load the extension:
+
+[source, subs="+attributes"]
+asciidoctor -r {gem-name} README.adoc
+
+
+=== Ruby
+
+Just `require '{gem-name}'`.
+However, if you don’t want the extension to be automatically registered in Asciidoctor, `require 'asciidoctor/katex/treeprocessor'` instead.
+
+IMPORTANT: Bundler automatically _requires_ all the specified gems.
+           To prevent it, use +
+           `gem '{gem-name}', require: false`.
+
+
+=== Node.js
+
+[source, js, subs="+attributes"]
+----
+// Load asciidoctor.js and {gem-name}.
+const asciidoctor = require('asciidoctor.js')()
+const asciidoctorKatex = require('{gem-name}')
+
+// See documentation at the end of this section.
+const options = {
+  katexOptions: {
+    macros: {
+      "\\RR": "\\mathbb{R}",
+    },
+  },
+}
+
+// Configure the extension and register it into global registry.
+asciidoctorKatex.register(asciidoctor.Extensions, options)
+
+// Convert the content to HTML.
+const content = `
+:stem: latexmath
+
+Do some math: stem:[E = mc^2]
+`
+const html = asciidoctor.convert(content)
+console.log(html)
+----
+
+
+You may also register the extension into a custom extensions registry:
+
+[source, js]
+const registry = asciidoctor.Extensions.create()
+asciidoctorKatex.register(registry, options)
+
+.*Options:*
+katex::
+  The katex object to use for rendering.
+  Defaults to `require('katex')`.
+
+requireStemAttr::
+  Whether to require `stem` attribute to be defined (Asciidoctor’s standard behaviour).
+  Set to `false` to process latexmath even when `stem` attribute is not defined.
+  Default is `true`. +
+  Note that the default stem type hard-coded by Asciidoctor is `asciimath` (not `latexmath`), so `[stem]` block and `++stem:[...]++` macro will not be rendered anyway (only `[latexmath]` block and `++latexmath:[...]++` macro).
+
+katexOptions::
+  The default options for `katex.render()`.
+  Defaults to empty object.
+
+
+== License
+
+This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
+For the full text of the license, see the link:LICENSE[LICENSE] file.

data/asciidoctor-katex.gemspec

@@ -0,0 +1,27 @@
+require File.expand_path('../lib/asciidoctor/katex/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'asciidoctor-katex'
+  s.version     = Asciidoctor::Katex::VERSION
+  s.author      = 'Jakub Jirutka'
+  s.email       = 'jakub@jirutka.cz'
+  s.homepage    = 'https://github.com/jirutka/asciidoctor-katex/'
+  s.license     = 'MIT'
+
+  s.summary     = 'Asciidoctor extension that converts latexmath to HTML using KaTeX at build-time'
+
+  s.files       = Dir['lib/**/*', '*.gemspec', 'LICENSE*', 'README*']
+
+  s.required_ruby_version = '>= 2.3'
+
+  s.add_runtime_dependency 'asciidoctor', '~> 1.5.6'
+  s.add_runtime_dependency 'katex', '~> 0.4.3'
+
+  s.add_development_dependency 'kramdown', '~> 1.17'
+  s.add_development_dependency 'rake', '~> 12.0'
+  s.add_development_dependency 'rspec', '~> 3.7'
+  s.add_development_dependency 'rspec-html-matchers', '~> 0.9.1'
+  s.add_development_dependency 'rubocop', '~> 0.51.0'
+  s.add_development_dependency 'simplecov', '~> 0.16'
+  s.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/asciidoctor-katex.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require 'asciidoctor/katex'

data/lib/asciidoctor/katex.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+require 'asciidoctor' unless RUBY_PLATFORM == 'opal'
+require 'asciidoctor/extensions' unless RUBY_PLATFORM == 'opal'
+require 'asciidoctor/katex/version'
+require 'asciidoctor/katex/treeprocessor'
+
+unless RUBY_PLATFORM == 'opal'
+  Asciidoctor::Extensions.register do
+    treeprocessor Asciidoctor::Katex::Treeprocessor
+  end
+end

data/lib/asciidoctor/katex/katex_adapter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+require 'asciidoctor/katex/version'
+require 'katex' unless RUBY_PLATFORM == 'opal'
+
+module Asciidoctor::Katex
+  # Adapter for KaTeX library supporting both Ruby and Opal environment.
+  class KatexAdapter
+
+    # @param default_options [Hash] the default options for the KaTeX renderer.
+    # @param katex_object the katex object to use under Opal (defaults to
+    #   global variable `katex`).
+    def initialize(default_options = {}, katex_object = nil)
+      @default_options = default_options
+      @katex_object = katex_object || `katex` if RUBY_PLATFORM == 'opal'
+    end
+
+    # @return [Boolean] whether is KaTeX library installed and loaded.
+    #   This is useful only under Opal.
+    def available?
+      if RUBY_PLATFORM == 'opal'
+        `#{@katex_object} != 'undefined' && #{@katex_object}.renderToString != undefined`
+      else
+        defined? ::Katex
+      end
+    end
+
+    # Renders the given math expression to HTML using KaTeX.
+    #
+    # @param math [String] the math (LaTeX) expression.
+    # @param options [Hash] options for `katex.renderToString`.
+    #   Keys in under_score notation will be converted to camelCase.
+    #   See <https://github.com/Khan/KaTeX#rendering-options>.
+    # @return [String] a rendered HTML fragment.
+    def render(math, options = {})
+      options = hash_camelize(options || {})
+
+      if RUBY_PLATFORM == 'opal'
+        `#{@katex_object}.renderToString(#{math}, #{options}.$$smap)`
+      else
+        ::Katex.render(math, options)
+      end
+    end
+
+    alias call render
+
+    # @return [String] version of the KaTeX library.
+    def version
+      if RUBY_PLATFORM == 'opal'
+        '0.9.0'  # TODO: replace with `katex.version` after update to 0.10+.
+      else
+        ::Katex::KATEX_VERSION.sub(/^v/, '')
+      end
+    end
+
+    private
+
+    # @param hash [Hash] the hash to transform.
+    # @return [Hash] a copy of the *hash* with under_score keys transformed to camelCase.
+    def hash_camelize(hash)
+      hash.map { |k, v|
+        [k.to_s.gsub(/_\w/) { |s| s[1].upcase }.to_sym, v]
+      }.to_h
+    end
+  end
+end

data/lib/asciidoctor/katex/stem_converter_decorator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+require 'asciidoctor/katex/version'
+require 'delegate'
+
+module Asciidoctor::Katex
+  # The converter decorator that renders delimited math expressions
+  # in block and inline latexmath stem nodes after.
+  class StemConverterDecorator < ::SimpleDelegator
+
+    # @param converter [Asciidoctor::Converter] the decorated converter to
+    #   delegate all method calls to.
+    # @param math_renderer [#call] callable that accepts a math expression
+    #   [String] and options [Hash], and returns a rendered expression [String].
+    def initialize(converter, math_renderer)
+      super(converter)
+      @math_renderer = math_renderer
+      @block_re = regexp_from_delimiters(::Asciidoctor::BLOCK_MATH_DELIMITERS[:latexmath])
+      @inline_re = regexp_from_delimiters(::Asciidoctor::INLINE_MATH_DELIMITERS[:latexmath])
+    end
+
+    # @param node [Asciidoctor::AbstractNode] the node to convert.
+    # @param transform [String, nil] the conversion method to call.
+    # @param opts [Hash] options to pass to the converter.
+    # @return [String] output of the converter.
+    def convert(node, transform = nil, opts = {})
+      # Call the underlying converter.
+      output = __getobj__.convert(node, transform, opts)
+
+      if latexmath? node
+        render_latexmath(output, node)
+      else
+        output
+      end
+    end
+
+    protected
+
+    # @param output [String] the converted *node* with delimited math expression.
+    # @param node [Asciidoctor::AbstractNode] the AST node.
+    # @return [String] a copy of *output* with math expression rendered.
+    def render_latexmath(output, node)
+      @throw_on_error ||= node.document.attr('katex-throw-on-error', false)
+      isblock = node.block?
+
+      output.sub(isblock ? @block_re : @inline_re) do
+        @math_renderer.call(::Regexp.last_match[1].strip,
+                            display_mode: isblock,
+                            throw_on_error: @throw_on_error)
+      end
+    end
+
+    # @param node [Asciidoctor::AbstractNode] the AST node to test.
+    # @return [Boolean] `true` if the given *node* is a block or inline latexmath,
+    #   `false` otherwise.
+    def latexmath?(node)
+      case node.node_name
+      when 'stem'
+        return true if node.style == 'latexmath'
+      when 'inline_quoted'
+        return true if node.type == :latexmath
+      end
+      false
+    end
+
+    private
+
+    # @param delimiters [Array<String>] tuple with open and close delimiter.
+    # @return [Regexp]
+    def regexp_from_delimiters(delimiters)
+      open, close = delimiters.map { |s| ::Regexp.escape(s) }
+      /#{open}(.+)#{close}/m
+    end
+  end
+end

data/lib/asciidoctor/katex/treeprocessor.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require 'asciidoctor' unless RUBY_PLATFORM == 'opal'
+require 'asciidoctor/extensions' unless RUBY_PLATFORM == 'opal'
+require 'asciidoctor/katex/version'
+require 'asciidoctor/katex/katex_adapter'
+require 'asciidoctor/katex/stem_converter_decorator'
+
+module Asciidoctor::Katex
+  # Asciidoctor processor that renders delimited latexmath expressions using
+  # the KaTeX library.
+  class Treeprocessor < ::Asciidoctor::Extensions::Treeprocessor
+
+    # @param katex_renderer [#call] callable that accepts a math expression
+    #   [String] and options [Hash], and returns a rendered expression [String].
+    #   Default is an instance of KatexAdapter.
+    # @param require_stem_attr [Boolean] `true` to skip when `stem` attribute
+    #   is not declared, `false` to process anyway.
+    def initialize(katex_renderer: KatexAdapter.new,
+                   require_stem_attr: true,
+                   **)
+      super
+      @katex_renderer = katex_renderer
+      @require_stem_attr = require_stem_attr
+    end
+
+    # @param document [Asciidoctor::Document] the document to process.
+    def process(document)
+      return if skip? document
+
+      converter = document.instance_variable_get(:@converter)
+      decorator = StemConverterDecorator.new(converter, @katex_renderer)
+      document.instance_variable_set(:@converter, decorator)
+      nil
+    end
+
+    protected
+
+    # @param document [Asciidoctor::Document] the document to process.
+    # @return [Boolean] whether to skip processing of the *document*.
+    def skip?(document)
+      @require_stem_attr && !document.attr?('stem')
+    end
+  end
+end

data/lib/asciidoctor/katex/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Katex
+    # Version of the asciidoctor-katex gem.
+    VERSION = '0.1.0'
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-katex
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jakub Jirutka
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-08-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+- !ruby/object:Gem::Dependency
+  name: katex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rspec-html-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.51.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.51.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 
+email: jakub@jirutka.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.adoc
+- asciidoctor-katex.gemspec
+- lib/asciidoctor-katex.rb
+- lib/asciidoctor/katex.rb
+- lib/asciidoctor/katex/katex_adapter.rb
+- lib/asciidoctor/katex/stem_converter_decorator.rb
+- lib/asciidoctor/katex/treeprocessor.rb
+- lib/asciidoctor/katex/version.rb
+homepage: https://github.com/jirutka/asciidoctor-katex/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Asciidoctor extension that converts latexmath to HTML using KaTeX at build-time
+test_files: []