jektex 0.0.2 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1247953962bc4063d49c80f23be942dba3f4ccbf52bc4f9612efb18ffe863358
-  data.tar.gz: bad878b76ed57f3c0a720d84bba5625267124287bb7a8b92f079a4ed678ea441
+  metadata.gz: 290626aa91c28cc4961baf40ec00dde81928da68e0a923ee84999027e7f3c9b0
+  data.tar.gz: 4ec8d501a4ab6f1b068ec01bb21a7d84bd844a5bca7d105bdc0c9c6e2652eec8
 SHA512:
-  metadata.gz: 2e859d1186b3aaae9d33cd1bcbfd96822f9d6470304c7ee23404b6ae6741163924caad83346811652e371738e6a6a7b6035e6df21c217ebf5fca3ef933d30d8c
-  data.tar.gz: ad53f03463c684a321c5a4c43def449a64f18d9ceccf1091004cd0bb5ce73c55dab9edbc29793b92856f9077ba8642de450b4310f97a110d7fa5882d45697f1d
+  metadata.gz: ccdddba235b4d0462ccb5e4d2ee4cbf5b97e9964c10fd0395e814635281563c6363a381422feeefdd9eb6a895877a47aba6fae95de36c98a6f710785ed18ba51
+  data.tar.gz: 4d0a8dad642c30c5f26ca5903d715e3728d918bb17fe1eaeaf3ce8ad814a25e9c50d0df15533522275665978971ee269164a2969cf73db9823b71b9ea29a7217

data/README.md

@@ -2,9 +2,9 @@
 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.
 
-## About
+## Features
 - Renders LaTeX formulas during Jekyll rendering
-- Works without any javascript o clients side
+- Works without any javascript on clients side
 - Is faster than any other server side Jekyll latex renderer
 - Supports user defined global macros
 - Has I/O efficient caching system
@@ -13,25 +13,25 @@ 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
+- Highly configurable but still having sensible defaults
 
 ## Usage
 
 ### Notation
 **Inline formula**  
-Put formula between two pairs of `$` inside of paragraph.
-
+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.
 ```
 
 **Display formula**  
-Put formula between two pairs of `$` and surround it between two empty lines.
+Put formula between two pairs of dolar sings (`$$`) and surround it by two empty lines.
 ```latex
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
 incididunt ut labore et dolore magna aliqua.
 
-$$ i\hbar\frac{\partial}{\partial t} \Psi(\mathbf{r},t) = \left [ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right ] \Psi(\mathbf{r},t) $$
+$$ \left[ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right] \Psi(\mathbf{r},t) $$
 
 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
 ea commodo consequat.
@@ -39,45 +39,116 @@ ea commodo consequat.
 
 _Why Jektex does not use conventional single `$` for inline formulas and double `$$` for
 display mode?  
-Unfortunately this is how [kramdown](https://kramdown.gettalong.org/) 
-(Jekyll's markdown parser) works and it would probably do be easier to write custom 
-markdown parser than hacking kramdown to behave differently._
+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._
+
+### 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
+---
+```
 
-### Macros
-You can define global macros in your `_config.yml` file:
+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:
-   - ["\\Q", "\\mathbb{Q}"]
-   - ["\\C", "\\mathbb{C}"]
+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/). YOU SHOULD ALWAYS delete jektex cache after changing
+definition of a macro for change to take effect.
+
+**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
+**Using bundler**  
 Add `jektex` to your `Gemfile` like this:
-
-```yaml
+```ruby
 group :jekyll_plugins do
-	gem "jektex"
+    gem "jektex"
 end
 ```
 
 and run `bundle install`
 
-### Without bundler
-Just run `gem install jektex` and add jektex to your plugin list in your `_config.yml` 
-file:
-```
-plugins:
-	- jektex
+**Without bundler**  
+Just run `gem install jektex`
 
+**After installation**  
+Add jektex to your plugin list in your `_config.yml` file:
+```yaml
+plugins:
+    - jektex
 ```
 
-### Style sheets
-Do not forget to add `katex.min.css` to you html head:
+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 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,22 +3,40 @@ 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"
 $global_macros = Hash.new
 $count_newly_generated_expressions = 0
+$path_to_cache = File.join(DEFAULT_CACHE_DIR, CACHE_FILE)
 $cache = nil
 $disable_disk_cache = false
+$ignored = Array.new
 
-def convert(doc)
-  # convert HTML enetities back to characters
-  post = HTMLEntities.new.decode(doc.to_s)
-  post = post.gsub(/(\\\()((.|\n)*?)(?<!\\)\\\)/) { |m| escape_method($1, $2, doc.path) }
-  post = post.gsub(/(\\\[)((.|\n)*?)(?<!\\)\\\]/) { |m| escape_method($1, $2, doc.path) }
+def is_ignored?(page)
+  for patern in $ignored
+    if File.fnmatch?(patern, page.relative_path, File::FNM_DOTMATCH) then
+      return true
+    end
+  end
+  return false
+end
+
+def render(page)
+  # check if document is not set to be ignored
+  if page.data == nil or is_ignored?(page) or page.data[FRONT_MATTER_TAG] == "false" then
+    return page.output
+  end
+
+  # convert HTML entities back to characters
+  post = HTMLEntities.new.decode(page.output.to_s)
+  # render inline expressions
+  post = post.gsub(/(\\\()((.|\n)*?)(?<!\\)\\\)/) { |m| escape_method($1, $2, page.path) }
+  # render display expressions
+  post = post.gsub(/(\\\[)((.|\n)*?)(?<!\\)\\\]/) { |m| escape_method($1, $2, page.path) }
   return post
 end
 
@@ -47,12 +65,12 @@ def escape_method( type, string, doc_path )
     # create the cache directory, if it doesn't exist
     begin
       # render using ExecJS
-      @result =  KATEX.call("katex.renderToString", string, 
+      @result =  KATEX.call("katex.renderToString", string,
                           {displayMode: @display,  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
       # catch parse error
@@ -70,41 +88,65 @@ end
 
 def print_stats
   print "             LaTeX: " + 
-        ($count_newly_generated_expressions).to_s + 
-        " expressions rendered (" + $cache.size.to_s + 
+        ($count_newly_generated_expressions).to_s +
+        " expressions rendered (" + $cache.size.to_s +
         " already cached)        \r"
   $stdout.flush
 end
 
+Jekyll::Hooks.register :pages, :post_render do |page|
+  page.output = render(page)
+end
+
 Jekyll::Hooks.register :documents, :post_render do |doc|
-  doc.output = convert(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"]
+  if site.config["jektex"] == nil then
+    # if no config is defined make empty one
+    config = Hash.new
+  else
+    # load jektex config from config file
+    config = site.config["jektex"]
+  end
+  # load macros
+  if config["macros"] != nil then
+    for macro_definition in config["macros"]
       $global_macros[macro_definition[0]] = macro_definition[1]
     end
   end
+
   # print macro information
-  if $global_macros.size == 0
+  if $global_macros.size == 0 then
     puts "             LaTeX: no macros loaded"
   else
-    puts "             LaTeX: " + $global_macros.size.to_s + " macro" + 
+    puts "             LaTeX: " + $global_macros.size.to_s + " macro" +
           ($global_macros.size == 1 ? "" : "s") + " loaded"
   end
 
-  if site.config["disable_disk_cache"] != nil
-    $disable_disk_cache = site.config["disable_disk_cache"]
+  # check if there is defined custom cache location in config
+  if config["cache_dir"] != nil then
+    $path_to_cache = File.join(config["cache_dir"].to_s, CACHE_FILE)
+  end
+
+  # load list of ignored files
+  if config["ignore"] != nil then
+    $ignored = config["ignore"]
   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)}
+  if(File.exist?($path_to_cache)) then
+    $cache = File.open($path_to_cache, "r"){|from_file| Marshal.load(from_file)}
   else
     $cache = Hash.new
   end
+
+  # check if cache is disable in config
+  if site.config["disable_disk_cache"] != nil then
+    $disable_disk_cache = site.config["disable_disk_cache"]
+  end
+
 end
 
 Jekyll::Hooks.register :site, :after_reset do
@@ -115,11 +157,10 @@ end
 Jekyll::Hooks.register :site, :post_write do
   # print new line to prevent overwriting previous output
   print "\n"
-  puts 
   # check if caching is enabled
   if $disable_disk_cache == false
     # 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)}
+    Dir.mkdir(File.dirname($path_to_cache)) unless File.exists?(File.dirname($path_to_cache))
+    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.2"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jektex
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.5
 platform: ruby
 authors:
 - Jan Černý
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-13 00:00:00.000000000 Z
+date: 2022-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: execjs