jektex 0.0.7 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a6f411d475735a808e6fb495464688d7acca5fb2afa3d4f467612fc7d5308b7a
4
- data.tar.gz: e322f027b1c7080553a9cf3e3d4145b49166f6d26e3c5502b3daf8a0ce61a0a5
3
+ metadata.gz: 9405c84a9c1c4d137d5f9fe152943a72613a52fb741ea8dc3074c64368257b77
4
+ data.tar.gz: fcf023964df85b84be1ebab055fd778f923a63e3857facc083e451370168b366
5
5
  SHA512:
6
- metadata.gz: 30af1bad450e61c9085975a37b6a2142084854d96201eb67e11cc9c80a21d9d3dbbc5894c82610f2cac7ab52b8272f3f5aae8b74bfa054480edbea9865ebbc48
7
- data.tar.gz: 06c8353988adc7940217d6a75ca313cf72a65492db30ab5421567c822199dd6c4b57c86a28485a0b146de826b69c6c1ee80ccb00335277f0b23065881670949d
6
+ metadata.gz: 1fda6a4eda19f919edc732da120ccfe2a20c520476465d53d79a98eb80087d94b438a84b863194009213781f5b15d180a5e7b22a6ca1eeb35e4bf3676da709c2
7
+ data.tar.gz: 7f3bd08cb26988e28c5ff910148404dcc0dee7f83478bbd04786aa5bf73ca5ea50fc93117e536c417549cb98f2192a27b20bdea99e598d3fcc15b49ef9b71208
data/README.md CHANGED
@@ -1,26 +1,27 @@
1
1
  [![Gem Version](https://badge.fury.io/rb/jektex.svg)](https://rubygems.org/gems/jektex)
2
2
 
3
3
  # Jektex
4
- Jekyll plugin for blazing fast server side cached LaTeX rendering with support of macros.
5
- Enjoy comfort of latex and markdown without cluttering your site with bloated javascript.
4
+ A Jekyll plugin for blazing-fast server-side cached LaTeX rendering, with support for macros.
5
+ Enjoy the comfort of LaTeX and Markdown without cluttering your site with bloated JavaScript.
6
6
 
7
7
  ## Features
8
8
  - Renders LaTeX formulas during Jekyll rendering
9
- - Works without any javascript on clients side
10
- - Is faster than any other server side Jekyll latex renderer
11
- - Supports user defined global macros
12
- - Has I/O efficient caching system
13
- - Has dynamic and informative log during rendering
14
- - Is easy to setup
15
- - Does not interfere with Jekyll workflow and project structure
16
- - Marks invalid syntax in document
17
- - Prints location of invalid expression during rendering
18
- - Highly configurable but still having sensible defaults
9
+ - Works without any client-side JavaScript
10
+ - Is faster than any other server-side Jekyll LaTeX renderer
11
+ - Supports user-defined global macros
12
+ - Has I/O-efficient caching system
13
+ - Dynamically informs about the number of expressions during rendering
14
+ - Is very easy to setup
15
+ - Doesn't interfere with Jekyll workflow and project structure
16
+ - Marks invalid expressions in document, printing its location during rendering
17
+ - Is highly configurable with sensible defaults
19
18
  - Makes sure that cache does not contain expression rendered with outdated configuration
20
19
 
21
20
  ## Usage
22
21
 
23
- ### Notation
22
+ Jektex supports both the built-in Kramdown math notation, and the newer LaTeX-only math notation.
23
+
24
+ ### Kramdown notation
24
25
  **Inline formula**
25
26
  Put formula between two pairs of dolar signs (`$$`) inside of paragraph.
26
27
  ```latex
@@ -29,7 +30,7 @@ adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliq
29
30
  ```
30
31
 
31
32
  **Display formula**
32
- Put formula between two pairs of dolar sings (`$$`) and surround it by two empty lines.
33
+ Put formula between two pairs of dolar sings (`$$`) and surround it with two empty lines.
33
34
  ```latex
34
35
  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
35
36
  incididunt ut labore et dolore magna aliqua.
@@ -45,54 +46,74 @@ display mode?
45
46
  This is how [kramdown](https://kramdown.gettalong.org/)(Jekyll's markdown parser) works
46
47
  so I decided to respect this convention. It makes this plugin more consistent and universal._
47
48
 
49
+
50
+ ### LaTex math mode notation
51
+ **Inline formula**
52
+ Put formula between two escaped brackets `\(` `\)`.
53
+ Its position in the text does not matter.
54
+ ```latex
55
+ Lorem ipsum dolor sit amet, consectetur \(e^{i\theta}=\cos(\theta)+i\sin(\theta)\)
56
+ adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
57
+ ```
58
+
59
+ **Display formula**
60
+ Put formula between two escaped square brackets `\[` `\]`.
61
+ Its position in the text does not matter.
62
+ ```latex
63
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
64
+ incididunt ut labore et dolore magna aliqua.
65
+
66
+ \[ \left[ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right] \Psi(\mathbf{r},t) \]
67
+
68
+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
69
+ ea commodo consequat.
70
+ ```
71
+
48
72
  ### Config
49
- Jektex si highly configurable from your `_config.yml` file
73
+ Jektex si highly configurable via your `_config.yml` file.
50
74
 
51
75
  **Disabling cache**
52
- You can disable caching with `disable_disk_cache = true` in `_config.yml`. Cache is
53
- enabled by default. You can find more information on [Jekyll official website](https://jekyllrb.com/docs/configuration/options/).
76
+ You can disable caching with `disable_disk_cache = true` in `_config.yml`.
77
+ Caching is enabled by default.
78
+ You can find more information on [Jekyll's official website](https://jekyllrb.com/docs/configuration/options/).
54
79
 
55
80
  **Setting cache location**
56
- By default jektex cache will be saved in `.jekyll-cache` directory. This results in it's
57
- deletion when you call `jekyll clean`. To prevent cache deletion or you just want to
58
- change location of cache for another reason you can achieve that by specifying
59
- `cache_dir` in `_config.yml`.
81
+ By default, Jektex cache will be saved in `.jekyll-cache` directory.
82
+ This results in its deletion when you call `jekyll clean`.
83
+ To prevent cache deletion or to change the cache location, you can specify `cache_dir` in `_config.yml`:
60
84
  ```yaml
61
85
  # Jektex cache dir location
62
86
  jektex:
63
87
  cache_dir: ".jektex-cache"
64
88
  ```
65
89
 
66
- **Ignore**
67
- By default jektex tries to render LaTeX in all files not excluded by Jekyll. But
68
- sometimes you get in situation when you do not want to render some files. For example
69
- _RSS feed_ with excerpts containing LaTeX. As a solution jektex offers `ignore` option.
70
- You can use conventional wild cards using `*`. For example:
90
+ **Ignoring files**
91
+ By default, Jektex tries to render LaTeX in all files rendered by Jekyll.
92
+ This can sometimes be undesirable, for example when rendering an _RSS feed_ with excerpts containing LaTeX.
93
+ Jektex solves this by using the `ignore` option:
71
94
  ```yaml
72
95
  # Jektex ignore files
73
96
  jektex:
74
97
  ignore: ["*.xml", "README.md", "_drafts/*" ]
75
98
  ```
76
99
 
77
- This example configuration ignores all `.xml` files, `README.md` and all files
78
- in `_drafts` directory.
100
+ You can use conventional wild cards using `*`.
101
+ This example configuration ignores all `.xml` files, `README.md` and all files in the `_drafts` directory.
79
102
 
80
- Another option for ignoring specific posts is setting `jektex` tag in front matter of
81
- post to `false`. For example:
103
+ Another way to ignore specific posts is setting the `jektex` attribute in front matter to `false`:
82
104
  ```yaml
83
105
  ---
84
- title: "How Jektex works"
106
+ ttle: "How Jektex works"
85
107
  category: "Development"
86
108
  jektex: false
87
109
  layout: post
88
110
  ---
89
111
  ```
90
112
 
91
- Setting `jektex` tag to `true` or not setting at all will result in jektex rendering LaTeX
92
- expressions in that post.
113
+ Setting `jektex` tag to `true` or not setting at all will result in Jektex rendering LaTeX expressions in that post.
93
114
 
94
- **Macros**
95
- You can define global macros like this:
115
+ **Using macros**
116
+ You can define global macros:
96
117
  ```yaml
97
118
  # Jektex macros
98
119
  jektex:
@@ -100,8 +121,8 @@ jektex:
100
121
  - ["\\Q", "\\mathbb{Q}"]
101
122
  - ["\\C", "\\mathbb{C}"]
102
123
  ```
103
- And yes you have to escape backlash(`\`) with another backlash. This is caused by
104
- [yaml definition](https://yaml.org/).
124
+ And yes, you have to escape the backlash (`\`) with another backlash.
125
+ This is due to the [yaml specification](https://yaml.org/).
105
126
 
106
127
  **Complete examples**
107
128
  Recommended config:
@@ -113,6 +134,7 @@ jektex:
113
134
  - ["\\Q", "\\mathbb{Q}"]
114
135
  - ["\\C", "\\mathbb{C}"]
115
136
  ```
137
+
116
138
  Having no configuration is equivalent to this:
117
139
  ```yaml
118
140
  jektex:
@@ -125,7 +147,7 @@ jektex:
125
147
  This plugin is available as a [RubyGem](https://rubygems.org/gems/jektex).
126
148
 
127
149
  **Using bundler**
128
- Add `jektex` to your `Gemfile` like this:
150
+ Add Jektex to your `Gemfile`:
129
151
  ```ruby
130
152
  group :jekyll_plugins do
131
153
  gem "jektex"
@@ -135,22 +157,23 @@ end
135
157
  and run `bundle install`
136
158
 
137
159
  **Without bundler**
138
- Just run `gem install jektex`
160
+ Run `gem install jektex`
139
161
 
140
162
  **After installation**
141
- Add jektex to your plugin list in your `_config.yml` file:
163
+ Add Jektex to your plugin list in your `_config.yml` file
142
164
  ```yaml
143
165
  plugins:
144
166
  - jektex
145
167
  ```
146
168
 
147
- and do not forget to add `katex.min.css` to you html head:
169
+ and don't forget to add `katex.min.css` to you HTML head:
148
170
  ```html
149
171
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css" integrity="sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ" crossorigin="anonymous">
150
172
  ```
151
- 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.
173
+ It is much better practice to download the [**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.
152
174
  You can find more information on [KaTeX's website](https://katex.org/docs/browser.html).
153
175
 
154
176
  ## Contributions and bug reports
155
177
  Feel free to repost any bugs or even make feature request in [issues on official repository](https://github.com/yagarea/jektex/issues).
156
178
  I am opened for pull requests as well.
179
+
data/lib/jektex/jektex.rb CHANGED
@@ -7,7 +7,6 @@ PATH_TO_JS = File.join(__dir__, "/katex.min.js")
7
7
  DEFAULT_CACHE_DIR = ".jekyll-cache"
8
8
  CACHE_FILE = "jektex-cache.marshal"
9
9
  KATEX = ExecJS.compile(open(PATH_TO_JS).read)
10
- PARSE_ERROR_PLACEHOLDER = "<b style='color: red;'>PARSE ERROR</b>"
11
10
  FRONT_MATTER_TAG = "jektex"
12
11
  INDENT = " " * 13
13
12
 
@@ -48,7 +47,22 @@ def print_stats
48
47
  $stdout.flush
49
48
  end
50
49
 
51
- def render(page)
50
+ #######################################################################################
51
+ # Render
52
+
53
+ def render_latex_notation(page)
54
+ # check if document is not set to be ignored
55
+ return page.content if !page.data || is_ignored?(page)
56
+ # convert HTML entities back to characters
57
+ post = HTMLEntities.new.decode(page.content.to_s)
58
+ # render inline expressions
59
+ post = post.gsub(/(\\\()((.|\n)*?)(?<!\\)\\\)/) { |m| escape_method($1, $2, page.relative_path) }
60
+ # render display mode expressions
61
+ post = post.gsub(/(\\\[)((.|\n)*?)(?<!\\)\\\]/) { |m| escape_method($1, $2, page.relative_path) }
62
+ return post
63
+ end
64
+
65
+ def render_kramdown_notation(page)
52
66
  # check if document is not set to be ignored
53
67
  return page.output if !page.data || is_ignored?(page)
54
68
  # convert HTML entities back to characters
@@ -79,8 +93,10 @@ def escape_method( type, expression, doc_path )
79
93
  # create the cache directory, if it doesn't exist
80
94
  begin
81
95
  # render using ExecJS
82
- result = KATEX.call("katex.renderToString", expression,
83
- { displayMode: is_in_display_mode, macros: $global_macros})
96
+ result = KATEX.call("katex.renderToString", expression,
97
+ { displayMode: is_in_display_mode,
98
+ macros: $global_macros
99
+ })
84
100
  rescue SystemExit, Interrupt
85
101
  # save cache to disk
86
102
  File.open($path_to_cache, "w"){|to_file| Marshal.dump($cache, to_file)}
@@ -88,11 +104,16 @@ def escape_method( type, expression, doc_path )
88
104
  raise
89
105
  rescue ExecJS::ProgramError => pe
90
106
  # catch parse error
91
- puts "\e[31m " + pe.message.gsub("ParseError: ", "") + "\n\t" + doc_path + "\e[0m"
92
- return PARSE_ERROR_PLACEHOLDER
107
+ puts "\e[31m #{pe.message.gsub("ParseError: ", "")}\n\t#{doc_path}\e[0m"
108
+ # render expression with error highlighting enabled
109
+ return KATEX.call("katex.renderToString", expression,
110
+ { displayMode: is_in_display_mode,
111
+ macros: $global_macros,
112
+ throwOnError: false
113
+ })
93
114
  end
94
115
  # save to cache
95
- $cache[expression_hash] = @result
116
+ $cache[expression_hash] = result
96
117
  # update count of newly generated expressions
97
118
  $count_newly_generated_expressions += 1
98
119
  print_stats
@@ -101,13 +122,24 @@ def escape_method( type, expression, doc_path )
101
122
  end
102
123
 
103
124
  Jekyll::Hooks.register :pages, :post_render do |page|
104
- page.output = render(page)
125
+ page.output = render_kramdown_notation(page)
105
126
  end
106
127
 
107
128
  Jekyll::Hooks.register :documents, :post_render do |doc|
108
- doc.output = render(doc)
129
+ doc.output = render_kramdown_notation(doc)
130
+ end
131
+
132
+ Jekyll::Hooks.register :pages, :pre_render do |page|
133
+ page.content = render_latex_notation(page)
109
134
  end
110
135
 
136
+ Jekyll::Hooks.register :documents, :pre_render do |doc|
137
+ doc.content = render_latex_notation(doc)
138
+ end
139
+
140
+ #######################################################################################
141
+ # SETTINGS AND INIT
142
+
111
143
  Jekyll::Hooks.register :site, :after_init do |site|
112
144
  # load jektex config from config file and if no config is defined make empty one
113
145
  config = site.config["jektex"] || Hash.new
@@ -122,7 +154,7 @@ Jekyll::Hooks.register :site, :after_init do |site|
122
154
  $cache = Hash.new
123
155
  end
124
156
 
125
- # check if cache is disable in config
157
+ # check if cache is disabled in config
126
158
  $disable_disk_cache = site.config["disable_disk_cache"] if site.config.has_key?("disable_disk_cache")
127
159
 
128
160
  # load macros
@@ -138,8 +170,8 @@ Jekyll::Hooks.register :site, :after_init do |site|
138
170
  if $global_macros.empty?
139
171
  puts "#{INDENT}LaTeX: no macros loaded"
140
172
  else
141
- puts "#{INDENT}LaTeX: #{$global_macros.size} macro" +
142
- ($global_macros.size == 1 ? "" : "s") + " loaded" +
173
+ puts "#{INDENT}LaTeX: #{$global_macros.size} macro" \
174
+ "#{$global_macros.size == 1 ? "" : "s"} loaded" +
143
175
  ($updated_global_macros.empty? ? "" : " (#{$updated_global_macros.size} updated)")
144
176
  end
145
177
 
@@ -153,6 +185,8 @@ Jekyll::Hooks.register :site, :after_reset do
153
185
  end
154
186
 
155
187
  Jekyll::Hooks.register :site, :post_write do
188
+ # print stats once more to prevent them from being overwriten by error log
189
+ print_stats
156
190
  # print new line to prevent overwriting previous output
157
191
  print "\n"
158
192
  # check if caching is enabled
@@ -1,3 +1,3 @@
1
1
  module Jektex
2
- VERSION = "0.0.7"
2
+ VERSION = "0.0.8"
3
3
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: jektex
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.7
4
+ version: 0.0.8
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jan Černý
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2022-03-14 00:00:00.000000000 Z
11
+ date: 2022-03-22 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: execjs
@@ -127,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
127
127
  - !ruby/object:Gem::Version
128
128
  version: '0'
129
129
  requirements: []
130
- rubygems_version: 3.3.5
130
+ rubygems_version: 3.3.8
131
131
  signing_key:
132
132
  specification_version: 4
133
133
  summary: Highly optimized latex rendering for Jekyll