jektex 0.0.3 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daa553320105731fb20840fc40d211a73f576f6847b8b3de0019d72313ac0c97
-  data.tar.gz: 4479c3dc694c196845460e4ed63263ad5bb900ed9b3a42fe68e4900001dfccda
+  metadata.gz: 476a24b916af7e71a30a60cd2476063fa2d627959060179104e8a41871c5d4ab
+  data.tar.gz: 93243e4af6fea3e355f0cc4401e990cdb107f77c717b7e63d4902a172b56a7d0
 SHA512:
-  metadata.gz: 42333a3f6325918d8e1da7c6dd983c3f8404d10b2ae84449076ba768846793ec992af35e6962ebde5c3ae2619dfc2f4c3211370d9c75f6f6883707fbdf355c03
-  data.tar.gz: 24849a110d4ac120fcccab47f357d0c74ae8f7d640dbcd21c7741dc7cf88096aaef6afe088b99a486fe9589e6f67afa13703f09f395ad5c157f6b3ee542c8672
+  metadata.gz: d0ae577416fec788441659e670f4e85c0b34c091c81f666ab1cd62f5a39b3500548efb4238f53d77f1ea0dd30bd3571f001aa418311dcf6786a70afbbd3d0e8c
+  data.tar.gz: a7feff881708ffb27bffb76c2f00146c0bb4f7f4a90fe341ea88f121f1442ace72294596112f8c139e9a5628f4f14f0022e2f18dabe5a7e15e56e985d31c9d73

data/README.md

@@ -1,3 +1,5 @@
+[![Gem Version](https://badge.fury.io/rb/jektex.svg)](https://rubygems.org/gems/jektex)
+
 # Jektex
 Jekyll plugin for blazing fast server side cached LaTeX rendering with support of macros.
 Enjoy comfort of latex and markdown without cluttering your site with bloated javascript.
@@ -13,14 +15,14 @@ Enjoy comfort of latex and markdown without cluttering your site with bloated ja
 - Does not interfere with Jekyll workflow and project structure
 - Marks invalid syntax in document
 - Prints location of invalid expression during rendering
-- Tags places within the rendered documents with syntax errors
+- Highly configurable but still having sensible defaults
+- Makes sure that cache does not contain expression rendered with outdated configuration
 
 ## Usage
 
 ### Notation
 **Inline formula**  
 Put formula between two pairs of dolar signs (`$$`) inside of paragraph.
-
 ```latex
 Lorem ipsum dolor sit amet, consectetur $$e^{i\theta}=\cos(\theta)+i\sin(\theta)$$
 adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
@@ -43,31 +45,87 @@ display mode?
 This is how [kramdown](https://kramdown.gettalong.org/)(Jekyll's markdown parser) works 
 so I decided to respect this convention. It makes this plugin more consistent and universal._
 
-### Macros
-You can define global macros in your `_config.yml` file:
+### Config
+Jektex si highly configurable from your `_config.yml` file
+
+**Disabling cache**  
+You can disable caching with `disable_disk_cache = true` in `_config.yml`. Cache is
+enabled by default. You can find more information on [Jekyll official website](https://jekyllrb.com/docs/configuration/options/).
+
+**Setting cache location**  
+By default jektex cache will be saved in `.jekyll-cache` directory. This results in it's
+deletion when you call `jekyll clean`. To prevent cache deletion or you just want to
+change location of cache for another reason you can achieve that by specifying
+`cache_dir` in `_config.yml`.
+```yaml
+# Jektex cache dir location
+jektex:
+  cache_dir: ".jektex-cache"
+```
+
+**Ignore**  
+By default jektex tries to render LaTeX in all files not excluded by Jekyll. But 
+sometimes you get in situation when you do not want to render some files. For example
+_RSS feed_ with excerpts containing LaTeX. As a solution jektex offers `ignore` option.
+You can use conventional wild cards using `*`. For example:
+```yaml
+# Jektex ignore files
+jektex:
+  ignore: ["*.xml", "README.md", "_drafts/*" ]
+```
+
+This example configuration ignores all `.xml` files, `README.md` and all files 
+in `_drafts` directory.
+
+Another option for ignoring specific posts is setting `jektex` tag in front matter of
+post to `false`. For example:
+```yaml
+---
+title: "How Jektex works"
+category: "Development"
+jektex: false
+layout: post
+---
+```
+
+Setting `jektex` tag to `true` or not setting at all will result in jektex rendering LaTeX
+expressions in that post.
 
+**Macros**  
+You can define global macros like this:
 ```yaml
 # Jektex macros
-jektex-macros:
+jektex:
+  macros:
     - ["\\Q", "\\mathbb{Q}"]
     - ["\\C", "\\mathbb{C}"]
 ```
+And yes you have to escape backlash(`\`) with another backlash. This is caused by
+[yaml definition](https://yaml.org/).
 
-### Cache control
-
-**Clearing cache**  
-To clear cached expressions you have to delete `.jektex-cache` directory in your 
-project directory.
-
-**Disabling cache**  
-You can disable caching with `disable_disk_cache = false` in `_config.yml`.
+**Complete examples**  
+Recommended config:
+```yaml
+jektex:
+  cache_dir: ".jektex-cache"
+  ignore: ["*.xml"]
+  macros:
+    - ["\\Q", "\\mathbb{Q}"]
+    - ["\\C", "\\mathbb{C}"]
+```
+Having no configuration is equivalent to this:
+```yaml
+jektex:
+  cache_dir: ".jekyll-cache"
+  ignore: []
+  macros: []
+```
 
 ## Installation
 This plugin is available as a [RubyGem](https://rubygems.org/gems/jektex).
 
 **Using bundler**  
 Add `jektex` to your `Gemfile` like this:
-
 ```ruby
 group :jekyll_plugins do
     gem "jektex"
@@ -90,6 +148,9 @@ and do not forget to add `katex.min.css` to you html head:
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css" integrity="sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ" crossorigin="anonymous">
 ```
-It is much better practice to download **css** file and loaded as an asset from your server directly.
+It is much better practice to download [**css** file](https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css) and load it as an asset from your server directly.
 You can find more information on [KaTeX's website](https://katex.org/docs/browser.html).
 
+## Contributions and bug reports
+Feel free to repost any bugs or even make feature request in [issues on official repository](https://github.com/yagarea/jektex/issues).
+I am opened for pull requests as well.

data/lib/jektex/jektex.rb

@@ -3,108 +3,148 @@ require 'digest'
 require 'htmlentities'
 
 
-PATH_TO_JS = __dir__ + "/katex.min.js"
-CACHE_DIR = "./.jektex-cache/"
+PATH_TO_JS = File.join(__dir__, "/katex.min.js")
+DEFAULT_CACHE_DIR = ".jekyll-cache"
 CACHE_FILE = "jektex-cache.marshal"
-PATH_TO_CACHE = CACHE_DIR + CACHE_FILE
 KATEX = ExecJS.compile(open(PATH_TO_JS).read)
 PARSE_ERROR_PLACEHOLDER = "<b style='color: red;'>PARSE ERROR</b>"
+FRONT_MATTER_TAG = "jektex"
+INDENT = " " * 13
+
 $global_macros = Hash.new
+$updated_global_macros = Array.new
+
 $count_newly_generated_expressions = 0
+
+$path_to_cache = File.join(DEFAULT_CACHE_DIR, CACHE_FILE)
 $cache = nil
 $disable_disk_cache = false
 
-def convert(page)
+$ignored = Array.new
+
+def get_list_of_updated_global_macros(current_macros, cached_global_macros)
+  return Array.new unless cached_global_macros || current_macros
+  return current_macros.keys unless cached_global_macros
+  return cached_global_macros.keys unless current_macros
+
+  macro_set = Set.new(cached_global_macros.keys + current_macros.keys)
+  macro_set.delete_if { |m| cached_global_macros[m] == current_macros[m] }
+  return macro_set.to_a
+end
+
+def is_ignored?(page)
+  return true if page.data[FRONT_MATTER_TAG] == "false"
+  return $ignored.any? { |patern| File.fnmatch?(patern, page.relative_path, File::FNM_DOTMATCH) }
+end
+
+def contains_updated_global_macro?(expression)
+  return $updated_global_macros.any? { |m| expression[m] }
+end
+
+def print_stats
+  print "#{INDENT}LaTeX: " \
+  "#{$count_newly_generated_expressions} expressions rendered " \
+  "(#{$cache.size} already cached)".ljust(72) + "\r"
+  $stdout.flush
+end
+
+def render(page)
+  # check if document is not set to be ignored
+  return page.output if !page.data || is_ignored?(page)
   # convert HTML entities back to characters
   post = HTMLEntities.new.decode(page.output.to_s)
-  post = post.gsub(/(\\\()((.|\n)*?)(?<!\\)\\\)/) { |m| escape_method($1, $2, page.path) }
-  post = post.gsub(/(\\\[)((.|\n)*?)(?<!\\)\\\]/) { |m| escape_method($1, $2, page.path) }
+  # render inline expressions
+  post = post.gsub(/(\\\()((.|\n)*?)(?<!\\)\\\)/) { |m| escape_method($1, $2, page.relative_path) }
+  # render display mode expressions
+  post = post.gsub(/(\\\[)((.|\n)*?)(?<!\\)\\\]/) { |m| escape_method($1, $2, page.relative_path) }
   return post
 end
 
-def escape_method( type, string, doc_path )
-  @display = false
-
-  # detect if expression is display view
-  case type.downcase
-    when /\(/
-      @display = false
-    else /\[/
-      @display = true
-  end
+def escape_method( type, expression, doc_path )
+  # detect if expression is in display mode
+  is_in_display_mode? = type.downcase =~ /\[/
 
   # generate a hash from the math expression
-  @expression_hash = Digest::SHA2.hexdigest(string) + @display.to_s
+  expression_hash = Digest::SHA2.hexdigest(string) + is_in_display_mode?.to_s
 
   # use it if it exists
-  if($cache.has_key?(@expression_hash))
+  if($cache.has_key?(expression_hash) && !contains_updated_global_macro?(string))
+    # check if expressin conains updated macro
     $count_newly_generated_expressions += 1
     print_stats
-    return $cache[@expression_hash]
+    return $cache[expression_hash]
 
   # else generate one and store it
   else
     # create the cache directory, if it doesn't exist
     begin
       # render using ExecJS
-      @result =  KATEX.call("katex.renderToString", string,
-                          {displayMode: @display,  macros: $global_macros})
+      result =  KATEX.call("katex.renderToString", expression,
+                          {is_in_display_mode?Mode: is_in_display_mode?,  macros: $global_macros})
     rescue SystemExit, Interrupt
       # save cache to disk
-      File.open(PATH_TO_CACHE, "w"){|to_file| Marshal.dump($cache, to_file)}
-      # this stops jekyll being immune to interupts and kill command
+      File.open($path_to_cache, "w"){|to_file| Marshal.dump($cache, to_file)}
+      # this stops jekyll being immune to interrupts and kill command
       raise
-    rescue Exception => e
+    rescue ExecJS::ProgramError => pe
       # catch parse error
-      puts "\e[31m " + e.message.gsub("ParseError: ", "") + "\n\t"  + doc_path + "\e[0m"
+      puts "\e[31m " + pe.message.gsub("ParseError: ", "") + "\n\t"  + doc_path + "\e[0m"
       return PARSE_ERROR_PLACEHOLDER
     end
     # save to cache
-    $cache[@expression_hash] = @result
+    $cache[expression_hash] = @result
     # update count of newly generated expressions
     $count_newly_generated_expressions += 1
     print_stats
-    return @result
+    return result
   end
 end
 
-def print_stats
-  print "             LaTeX: " + 
-        ($count_newly_generated_expressions).to_s +
-        " expressions rendered (" + $cache.size.to_s +
-        " already cached)        \r"
-  $stdout.flush
+Jekyll::Hooks.register :pages, :post_render do |page|
+  page.output = render(page)
 end
 
-Jekyll::Hooks.register :pages, :post_render do |page|
-  page.output = convert(page)
+Jekyll::Hooks.register :documents, :post_render do |doc|
+  doc.output = render(doc)
 end
 
 Jekyll::Hooks.register :site, :after_init do |site|
-  # load macros from config file
-  if site.config["jektex-macros"] != nil
-    for macro_definition in site.config["jektex-macros"]
-      $global_macros[macro_definition[0]] = macro_definition[1]
-    end
-  end
-  # print macro information
-  if $global_macros.size == 0
-    puts "             LaTeX: no macros loaded"
+  # load jektex config from config file and if no config is defined make empty one
+  config = site.config["jektex"] || Hash.new
+
+  # check if there is defined custom cache location in config
+  $path_to_cache = File.join(config["cache_dir"].to_s, CACHE_FILE) if config.has_key?("cache_dir")
+
+  # load content of cache file if it exists
+  if File.exist?($path_to_cache)
+    $cache = File.open($path_to_cache, "r"){ |from_file| Marshal.load(from_file)}
   else
-    puts "             LaTeX: " + $global_macros.size.to_s + " macro" +
-          ($global_macros.size == 1 ? "" : "s") + " loaded"
+    $cache = Hash.new
   end
 
-  if site.config["disable_disk_cache"] != nil
-    $disable_disk_cache = site.config["disable_disk_cache"]
+  # check if cache is disable in config
+  $disable_disk_cache = site.config["disable_disk_cache"] if site.config.has_key?("disable_disk_cache")
+
+  # load macros
+  if config.has_key?("macros")
+    for macro_definition in config["macros"]
+      $global_macros[macro_definition[0]] = macro_definition[1]
+    end
   end
 
-  # load content of cache file if it exists
-  if(File.exist?(PATH_TO_CACHE))
-    $cache = File.open(PATH_TO_CACHE, "r"){|from_file| Marshal.load(from_file)}
+  # make list of updated macros
+  $updated_global_macros = get_list_of_updated_global_macros($global_macros, $cache["cached_global_macros"])
+  # print macro information
+  if $global_macros.empty?
+    puts "#{INDENT}LaTeX: no macros loaded"
   else
-    $cache = Hash.new
+    puts "#{INDENT}LaTeX: #{$global_macros.size} macro" +
+      ($global_macros.size == 1 ? "" : "s") + " loaded" +
+      ($updated_global_macros.empty? ? "" : " (#{$updated_global_macros.size} updated)")
   end
+
+  # load list of ignored files
+  $ignored = config["ignore"] if config.has_key?("ignore")
 end
 
 Jekyll::Hooks.register :site, :after_reset do
@@ -116,9 +156,13 @@ Jekyll::Hooks.register :site, :post_write do
   # print new line to prevent overwriting previous output
   print "\n"
   # check if caching is enabled
-  if $disable_disk_cache == false
+  if !$disable_disk_cache
+    # save global macros to cache
+    $cache["cached_global_macros"] = $global_macros
+    # create cache path
+    Pathname.new($path_to_cache).dirname.mkpath
     # save cache to disk
-    Dir.mkdir(CACHE_DIR) unless File.exists?(CACHE_DIR)
-    File.open(PATH_TO_CACHE, "w"){|to_file| Marshal.dump($cache, to_file)}
+    File.open($path_to_cache, "w"){|to_file| Marshal.dump($cache, to_file)}
   end
 end
+

data/lib/jektex/version.rb

@@ -1,3 +1,3 @@
 module Jektex
-  VERSION = "0.0.3"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jektex
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.6
 platform: ruby
 authors:
 - Jan Černý
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-18 00:00:00.000000000 Z
+date: 2022-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: execjs
@@ -108,7 +108,7 @@ licenses:
 - GPL-3.0-or-later
 metadata:
   bug_tracker_uri: https://github.com/yagarea/jektex/issues
-  documentation_uri: https://github.com/yagarea/jektex
+  documentation_uri: https://github.com/yagarea/jektex/blob/master/README.md
   homepage_uri: https://github.com/yagarea/jektex
   source_code_uri: https://github.com/yagarea/jektex
   changelog_uri: https://github.com/yagarea/jektex/blob/master/changelog.md